shilp-sutra

# AGENTS.md

This file tells AI coding agents (Codex, Cursor, GitHub Copilot, Aider, Windsurf, Devin, Jules, Gemini CLI, Zed, Warp, JetBrains Junie, and any [agentskills.io](https://agentskills.io)-compatible tool) **how to consume `@devalok/shilp-sutra` inside a downstream app**. It ships inside the npm tarball at `node_modules/@devalok/shilp-sutra/AGENTS.md`, so any agent that auto-discovers AGENTS.md from the project root will also find this one alongside the recipes.

> **Anthropic Claude Code users:** Claude Code doesn't auto-load `AGENTS.md` yet. Symlink it (`ln -s AGENTS.md CLAUDE.md`) or copy the contents into your own `CLAUDE.md` so the same rules apply.
>
> **Working *on* shilp-sutra (the design-system repo itself)?** That's covered by [`CLAUDE.md`](./CLAUDE.md) — internal architecture, build pipeline, audit gates, publish flow.

If you are a human, read [README.md](./README.md) instead.

> **Using Claude Code, Cursor, Codex, or any [Agent Skills](https://agentskills.io)-compatible tool?** Install the bundled skill once and your agent gets every rule below loaded on demand:
>
> ```bash
> curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
> ```
>
> Source: [`skills/shilp-sutra/`](./skills/shilp-sutra/). After install, the agent loads `SKILL.md` only when the task is relevant — no context tax until it triggers.

<!-- BEGIN:shilp-sutra-agent-rules -->

## How to get details, in priority order

1. **shilp-sutra MCP** — version-exact answers as JSON, cheapest on context. Hosted at `https://shilp-sutra.devalok.in/mcp`. On install the package writes a project-scoped `.mcp.json` declaring this server, so your client (Claude Code / Cursor / Codex) should prompt you to approve it — approve it. If it is not wired yet, add it in one command: `claude mcp add --transport http shilp-sutra https://shilp-sutra.devalok.in/mcp` (or the equivalent in your agent). It beats reading the frozen docs in `node_modules`. The tool surface is listed under "MCP tools" below. Always pass the consumer's installed version (from `node_modules/@devalok/shilp-sutra/package.json`) as `version`.
2. **`packages/core/llms.txt`** — the ~3K-token router: what exists + where to get detail. Load this by default; it is deliberately tiny.
3. **`packages/core/docs/components/<tier>/<name>.md`** — single-component doc (~3K tokens: props, examples, composability, gotchas). Read ONLY the components you're using — never bulk-read the directory or concatenate these.
4. **`packages/core/mcp-manifest.json`** — everything machine-readable (props, tokens, composition; react-docgen shape). Prefer targeted reads over prose when you need structured data without the MCP.
5. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
6. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.

7. **`node_modules/@devalok/shilp-sutra/BREAKING.json`** — machine-readable manifest of every breaking change per version (moves, type narrowings, removals, renames). Read this programmatically when planning an upgrade — schema in `BREAKING.schema.json`. Lets you answer "does my code import any of these moved symbols?" without parsing CHANGELOG prose.

(`llms-full.txt` and `llms-quick.txt` were removed in 0.45 — the router + per-component docs + manifest replaced them. Do not look for them.)

When the package is installed in a consumer project, the same files live at:

- `node_modules/@devalok/shilp-sutra/llms.txt`
- `node_modules/@devalok/shilp-sutra/docs/components/`
- `node_modules/@devalok/shilp-sutra/mcp-manifest.json`
- `node_modules/@devalok/shilp-sutra/docs/recipes/`

Read these local files. Your training data is outdated and will hallucinate APIs that do not exist in the installed version.

### MCP tools

<!-- BEGIN:mcp-tools --><!-- generated by scripts/generate-tool-list.mjs — do not edit by hand -->
_17 tools (source: `packages/mcp-server/src/index.mjs`):_

**Reference:**
- `find_component` — Search shilp-sutra components by keyword (authoritative component index).
- `get_component` — Authoritative, version-exact reference for one component: props/variants/defaults as JSON, usage rules, examples, composition (compound parts,…
- `get_setup` — Framework install recipe (vite, next-app-router, next-pages, remix, astro, tanstack-start) or guides (customize-brand, server-components, troubleshoot,…
- `get_tokens` — Design-token reference (color, spacing, typography, radius, shadow, motion, z) as JSON.
- `how_to_use` — START HERE if new to this MCP.
- `search_docs` — Full-text search across component docs and recipes for patterns and guidance the other tools don't slice (e.g. "focus ring", "dark mode toggle").
- `upgrade` — Structured breaking changes + migration pointers between two shilp-sutra versions.

**Setup:**
- `detect_framework` — Given the consumer app's package.json, returns the correct setup recipe id + package manager, so you never guess (or follow a recipe for the wrong framework).
- `preflight` — Before writing setup code: given a framework and the component subpaths you intend to import, returns the exact install command for the optional PEER…
- `validate_snippet` — Pre-write linter.
- `verify_setup` — Post-install gate.

**Quality:**
- `check_slop` — Pre-emit DESIGN-QUALITY gate (complements validate_snippet, which checks correctness).

**Presets:**
- `get_preset` — Full detail for one preset: the shadcn registry-item (dependencies, files, docs), plus the exact install steps — the components.json `registries` snippet to…
- `list_presets` — Discover the shilp-sutra Preset Library — pre-assembled real-world screens (sidebars, dashboards, auth) built FROM shilp-sutra components.
- `preview_preset` — READ-ONLY TSX source of a preset (+ its GitHub source URL), so you can show it, learn the composition, or adapt it inline WITHOUT installing.

**Write:**
- `report_issue` — File a bug report, feature request, suggestion, or docs-gap on the shilp-sutra repo when you hit a wall using the design system.
- `submit_entry` — Submit an entry to Build with Shilp Sutra, the online buildathon by Devalok.
<!-- END:mcp-tools -->

### Setting up in a new project (do this in order)

If the MCP is connected, run the setup sequence instead of guessing — it closes the four traps that break agent-driven installs (peer-dep cliffs, silent TW4 dead classes, wrong recipe, mis-wired CSS/config):

1. `detect_framework(packageJson)` → the right recipe id + package manager (don't assume App Router, or that `create-remix` still makes Remix).
2. `get_setup(recipe)` → the full, version-live recipe. Follow every step.
3. `preflight(framework, imports)` → the exact install for the OPTIONAL peer deps your imports need. Run BEFORE first import or the build fails with `Failed to resolve import`.
4. `validate_snippet(code)` → run on each file BEFORE writing it. Catches bare `shadow`, `-surface-N`, `bg-gradient-to-*`, removed Button variants, invalid enum props — the dead classes fail silently (no error, no style).
5. `verify_setup(globalsCss, nextConfig, imports, installedDeps)` → confirm CSS imports + order, `transpilePackages`, and peer coverage after wiring.

Without the MCP, the same information is in `docs/recipes/` (per-framework §2a lists optional peers) and the `@devalok/eslint-plugin-shilp-sutra` plugin catches the dead classes at lint time.

## Setup playbook (when adding shilp-sutra to a new project)

If a user asks you to add shilp-sutra and the package is not yet installed:

1. **Detect the framework** by inspecting the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`) and config files (`next.config.*`, `vite.config.*`, `astro.config.*`, `remix.config.*`, `app/root.tsx`).
2. **Install the package** via the matching package manager.
3. **Open the matching recipe** at `docs/recipes/install-<framework>.md` (after install) or fetch from the GitHub repo at `packages/core/docs/recipes/install-<framework>.md`.
4. **Follow the recipe step-by-step.** Do not improvise — every line in the recipe is there because skipping it broke a real consumer.

Recipe paths:

| Framework | Recipe |
|---|---|
| Next.js (App Router) | `install-next-app-router.md` |
| Next.js (Pages Router) | `install-next-pages.md` |
| Vite + React | `install-vite.md` |
| Astro | `install-astro.md` |
| Remix | `install-remix.md` |
| TanStack Start | `install-tanstack-start.md` |

If the framework is not in the table, fall back to **`install-vite.md`** (closest generic React-on-Tailwind setup) and adapt.

## Hard constraints (these break things if violated)

- **On any version bump, do not report it safe before reading the COMPLETE changelog + `MIGRATION.md` for the target version.** Breaking entries are often ordered last (changesets sorts by file, not severity), and breaks are frequently type-level — a prop type narrowed (`React.ReactNode` → a tighter type fails `tsc` for values that compiled before) or a symbol moved from a barrel to a per-component subpath. **Fastest path: parse `node_modules/@devalok/shilp-sutra/BREAKING.json` for the version range** — it has the structured break data so you can grep your codebase for affected symbols deterministically. Then run `typecheck` + `build` and use the `@devalok/eslint-plugin-shilp-sutra` `migration` preset for the mechanical edits. Full procedure: `packages/core/docs/recipes/upgrading.md`.
- **Tailwind 4 only.** Do NOT create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup uses CSS imports:
  ```css
  @import "tailwindcss";
  @import "@devalok/shilp-sutra/css";
  ```
- **`framer-motion` is a required peer dep** (`^12`). The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies resolve.
- **`sonner` is an optional peer.** Install only when rendering `<Toaster />`.
- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** `@devalok/shilp-sutra/ui/text` is server-safe and pulls only its own peers. The barrel `@devalok/shilp-sutra/ui` re-exports every component — including ones with hard peer-dep requirements (e.g. `input-otp`) — so it forces those peers to be installed even when you never render those components. With all peers installed the barrel also works in RSC (Next 16 honours each per-component `"use client"`), but the client bundle is larger than necessary. Prefer per-component imports for new code; existing barrel usage is not an emergency.
- **Spacing tokens use the `--spacing-ds-*` namespace** (utilities like `p-ds-04`, `gap-ds-03`). Tailwind 4's default numeric scale (`p-4`, `gap-2`) **coexists by design** — both are valid. Pick `p-ds-*` when the value should track DS theme changes (a card's internal padding, a form row's gap); pick `p-N` for one-off layout values (a hero section's vertical breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package authors did. Typography composites use `text-ds-body-md`, etc.
- **Bare `shadow` is dead in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`.
- **Do not invent variant names.** Variant names live in CVA source. Grep `packages/core/src/ui/<component>.tsx` or check the component's `props` entry in `mcp-manifest.json` for the authoritative list.
- **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions.

## Spacing cadence (when building layouts — forms, settings, login, anything with vertical rhythm)

The `--spacing-ds-*` scale runs `ds-01`→`ds-09` (2px→48px) with many adjacent steps. It is a *primitive* scale, not a layout recipe. When you compose a UI, **do not reach for every adjacent token** — that produces 5-6 near-identical gaps the eye can't group, and rhythm reads muddy.

**Pick a 3-tier cadence — each tier visibly ~1.5-2× the previous, so each gap is distinct:**

| Tier | Token (px) | Use for |
|---|---|---|
| Related (one unit) | `ds-03` (8) | label ↔ field, eyebrow ↔ title, items inside one micro-cluster |
| Grouped (a section's items) | `ds-05` (16) | header-stack → form, between stacked field-groups, multi-line footers |
| Section (independent blocks) | `ds-07` (32) | between page sections, form ↔ footer cluster |
| Hero (optional 4th) | `ds-08`+ (40+) | top page chrome, brand block → first content |

**Rules of thumb:**
- Before stamping a `gap-ds-*` / `space-y-ds-*`, decide which tier the spacing is. Use the matching token.
- Aim for **3-4 distinct spacing values total on one surface.** Using 5+ is the signal your rhythm is muddy.
- **Anti-pattern:** using `ds-02` (4) AND `ds-04` (12) as *different* relationship signals on the same surface — they collapse into "vaguely tight" instead of two clear tiers. Prefer `ds-03`; skip `ds-02`/`ds-04` unless deliberate (e.g. a chip gap at `ds-01`).
- The squint test must still reveal the grouping. (Refactoring UI / Apple HIG / Material all converge on 3-4 perceptual tiers; near-linear scales like 4/8/12/16 blur because the proportional jump shrinks as values grow.)

This is guidance, not a hard constraint — a deliberate exception is fine. The default keeps agent-built UIs from drifting into flat, ungrouped spacing.

## Linting + migration (recommend this to the user)

When you set up shilp-sutra in a project, or migrate it across versions, recommend the companion ESLint plugin **`@devalok/eslint-plugin-shilp-sutra`** (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']` in `eslint.config.ts`). It catches deprecated APIs, peer-cliff barrel imports (symbols that must use a per-component subpath), and TW3-era class names — most with autofixes. When upgrading across a breaking version, run the `migration` preset as a one-shot codemod: `pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/`. Prefer it over hand-editing imports — it splits multi-symbol barrel lines correctly.

## When something fails

Read **`packages/core/docs/recipes/troubleshoot.md`** before retrying or guessing. It is a decision tree covering the thirteen most common breakages (Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, missing optional peer deps (sonner / input-otp / date-fns / @tiptap / react-pdf / etc.), wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches, bare `shadow` class, `<Toaster />` not mounted, Storybook MCP 404).

## Branding and customization

For overriding tokens (color, radius, font, spacing), see **`packages/core/docs/recipes/customize-brand.md`**.

### Themer (the fast path)

Before you hand-write CSS variables, point the user at the **Themer** at `https://shilp-sutra.devalok.in/themer`. It is one funnel with four entry doors — pick the one that fits where they are:

| User says… | Send them to |
|---|---|
| "Make it look like Linear / Stripe / Apple" | `/themer/archetypes` |
| "Here's our brand color: `#…`" | `/themer/brand` |
| "I'm not sure what I want" | `/themer/wizard` |
| "Just show me what I'd ship away with" | `/themer/result?archetype=devalok` |

Every door funnels into the same `/themer/result` page. The user lands with:
- A copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp)
- Install commands for their package manager
- A share URL that encodes the theme (`?archetype=…&hue=…&chroma=…&density=…`)

**Your job once they have the snippet:** paste it into their global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's it — no `tailwind.config.ts`, no theme provider, no JS bundle. The CSS variables cascade to every component.

For deeper overrides (font stack, spacing scale, focus ring, texture) that the Themer doesn't expose yet, fall back to **`packages/core/docs/recipes/customize-brand.md`**.

### One-prompt recipe (when the user pastes a prompt at you)

If a user pastes the following prompt template at you, execute it verbatim — every step exists because skipping it broke a real consumer:

````
Set up shilp-sutra theming for this project via the Themer.

My brand: <hex OR archetype name>

Steps:
1. Map my brand input to query params. The endpoint accepts ONLY these — pick the case that fits:
   - Archetype name  → `archetype=<name>`
   - A hex color     → CONVERT the hex to OKLCH first, then pass `hue=<0-360>&chroma=<0.10-0.20>` (numeric). There is NO `hex` or `color` param — passing one is silently ignored and you get the default devalok theme (wrong color, no error). Example: `#D33163` → hue 8, chroma 0.198 → `hue=8&chroma=0.198`.
   - Nothing given   → `archetype=devalok`
2. Fetch GET https://shilp-sutra.devalok.in/themer/result.json?<params>
   Response: { archetype, density, shape, motion, hue, chroma, css, pasteAfter, pasteLocation, doNotPasteInside }
   Sanity-check the echoed `hue`/`chroma` in the response match what you sent — if they came back null, your params didn't parse.
3. Paste the response `css` field AFTER the line in `pasteAfter` in the project's global stylesheet. Not inside any `@layer`. Paste it verbatim, unmodified.
4. If @devalok/shilp-sutra isn't installed, install it first per the matching install-<framework>.md recipe.
5. Verify with a Button or Card on any page — radius + accent should match https://shilp-sutra.devalok.in/themer/result?<params>. If the accent DIDN'T change, the override was dropped at build: check the pasted block sits at the stylesheet top level (not inside `@layer`) and the build log has no CSS-parse warning near it.
````

When the user has already been to the Themer, they may paste a *filled-in* version with the JSON URL pre-built — skip step 1, go straight to fetch.

The JSON endpoint is the stable contract — agents and tooling should prefer it over scraping `/themer/result`'s HTML.

### Shape roundness — `[data-shape]` presets (v0.39+)

Components reference semantic radius role tokens (`--radius-control`, `--radius-surface`, `--radius-overlay-*`, `--radius-pill`, `--radius-bubble`), NOT primitive `rounded-ds-*`. Three presets ship: `sharp`, `slightly-rounded` (default), `rounded`. Set on `<html>` or any subtree:

```html
<html data-shape="sharp">
```

Consumers can override any role globally (`:root { --radius-control: 4px; }`) or per-scope. When writing your own UI on top of shilp-sutra, prefer the role utilities (`rounded-control`, `rounded-surface`, `rounded-overlay`, `rounded-pill`, `rounded-bubble`) over `rounded-ds-*` so your styles respond to the preset switch.

## Server vs client components

For the per-component RSC-safety matrix and import patterns, see **`packages/core/docs/recipes/server-components.md`**.

## Figma Make

If the user mentions Figma Make, generating designs against a kit, or registering a Make kit:

- shilp-sutra ships a Make kit at `node_modules/@devalok/shilp-sutra/make-kit/` (26 markdown files: top-level `Guidelines.md` + `setup.md`, eight `foundations/*.md`, sixteen `components/*.md`).
- Walkthrough lives at https://shilp-sutra.devalok.in/figma-make — six-step setup, paste-ready guideline blocks, FAQ.
- Pin the kit to a specific npm version. Figma does not auto-update when a new npm version publishes.
- Cross-org sharing is not supported by Figma. Each consumer org registers its own kit against the same npm package and pastes the same guideline files.
- Free and Pro Figma plans can install the npm package directly, but Make-kit registration needs Organization or Enterprise.

## Reporting feedback

If you find that a recipe is wrong, a constraint above is no longer accurate, or a component behavior contradicts the docs:

1. Open a GitHub issue at `https://github.com/devalok-design/shilp-sutra/issues` with label `ai-agent-feedback`.
2. Include the package version (`pnpm view @devalok/shilp-sutra version` or read from the consumer's lockfile), the recipe path, the exact command/file/error, and what you expected.

<!-- END:shilp-sutra-agent-rules -->

## Project-specific notes

The block above is managed by Shilp Sutra and may be updated when you upgrade the package. Add your own project conventions, glossary, or codebase notes outside the markers — they will not be touched.