@devalok/shilp-sutra 0.38.0 → 0.40.0

package/scripts/welcome.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * Postinstall welcome banner for @devalok/shilp-sutra.
+ *
+ * Runs once per major.minor version on consumer install. Silent under CI,
+ * non-TTY environments, NO_COLOR, npm silent loglevel, or when the
+ * SHILP_SUTRA_NO_WELCOME env var is set. Falls back to a compact 6-line
+ * text block if the terminal is narrower than 70 columns or shorter than
+ * 28 rows. Never throws — wrapped in a try/catch so an internal error can
+ * never break the consumer install.
+ *
+ * Safety guards (industry best practice — see research notes in
+ * .changeset/wave-4-install-experience.md):
+ *
+ *   - process.env.CI                          → silent (avoid log noise on CI)
+ *   - process.env.SHILP_SUTRA_NO_WELCOME=1    → silent (user opt-out)
+ *   - process.env.NO_COLOR                    → plain text, no ANSI
+ *   - process.stdout.isTTY === false          → silent (piped builds, Docker)
+ *   - npm_config_loglevel === 'silent'        → silent (respect pkg manager)
+ *   - !INIT_CWD || INIT_CWD inside the package → silent (dev install, not consumer)
+ *   - Sentinel file with current version       → silent on re-install of same ver
+ *   - try/catch around everything              → always exit 0
+ *
+ * The sentinel encodes the version (`node_modules/.shilp-sutra-welcomed`)
+ * so version bumps re-fire the banner once.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = resolve(__dirname, '..')
+
+// ── Guard rails — bail out early if any condition says "silent". ────────────
+function shouldSkip() {
+  if (process.env.CI) return 'CI environment'
+  if (process.env.SHILP_SUTRA_NO_WELCOME === '1' || process.env.SHILP_SUTRA_NO_WELCOME === 'true') return 'SHILP_SUTRA_NO_WELCOME set'
+  if (process.env.npm_config_loglevel === 'silent') return 'npm silent loglevel'
+  if (!process.stdout.isTTY) return 'not a TTY (piped/Docker/etc.)'
+  // Dev install — we're inside the design-system repo itself, not a consumer
+  const initCwd = process.env.INIT_CWD || process.cwd()
+  const cwd = process.cwd()
+  const isInsideNodeModules = cwd.includes(`${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`) || cwd.includes('/node_modules/')
+  if (!isInsideNodeModules) return 'dev install (not running from node_modules/)'
+  // INIT_CWD points at the consumer's project root. If absent → odd setup; skip.
+  if (!initCwd || initCwd === cwd) return 'no INIT_CWD set (unusual install context)'
+  return null
+}
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf-8'))
+    return pkg.version
+  } catch {
+    return null
+  }
+}
+
+// Sentinel: re-fire only on version change. Stored at the workspace root's
+// node_modules/.shilp-sutra-welcomed so it survives pnpm dedupe rebuilds.
+function getSentinelPath() {
+  // Walk up from PKG_DIR (node_modules/@devalok/shilp-sutra/) to the
+  // enclosing node_modules/ root, then write inside it.
+  const parts = PKG_DIR.split(/[/\\]/)
+  const nmIdx = parts.lastIndexOf('node_modules')
+  if (nmIdx === -1) return null
+  const nmRoot = parts.slice(0, nmIdx + 1).join(process.platform === 'win32' ? '\\' : '/')
+  return join(nmRoot, '.shilp-sutra-welcomed')
+}
+
+function alreadyWelcomed(version) {
+  const sentinel = getSentinelPath()
+  if (!sentinel) return false
+  try {
+    if (!existsSync(sentinel)) return false
+    const previousVersion = readFileSync(sentinel, 'utf-8').trim()
+    return previousVersion === version
+  } catch {
+    return false
+  }
+}
+
+function markWelcomed(version) {
+  const sentinel = getSentinelPath()
+  if (!sentinel) return
+  try {
+    mkdirSync(dirname(sentinel), { recursive: true })
+    writeFileSync(sentinel, version + '\n')
+  } catch {
+    // ignored — banner already printed, sentinel write is best-effort
+  }
+}
+
+// ── ANSI rendering ──────────────────────────────────────────────────────────
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY
+
+// Devalok pink #d946a6 = RGB(217, 70, 166)
+const PINK = useColor ? '\x1b[38;2;217;70;166m' : ''
+const PINK_DIM = useColor ? '\x1b[38;2;167;55;128m' : ''
+const BOLD = useColor ? '\x1b[1m' : ''
+const DIM = useColor ? '\x1b[2m' : ''
+const RESET = useColor ? '\x1b[0m' : ''
+
+function colour(text, code) {
+  return useColor ? `${code}${text}${RESET}` : text
+}
+
+// Lotus — 13 rows × 30 cols Braille. Centered in a 63-col inner box (16 left,
+// 17 right padding).
+const LOTUS = [
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⠟⠹⣧⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⣷⣦⣄⣠⣿⠃⢠⣄⠈⢻⣆⣠⣴⡞⡆⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⢀⣀⣀⣿⠀⠈⢻⣇⢀⣾⢟⡄⣸⡿⠋⠀⡇⣇⣀⣀⠀⠀⠀⠀⠀',
+  '⠀⣤⣤⣤⣀⣱⢻⠚⠻⣧⣀⠀⢹⡿⠃⠈⢻⣟⠀⢀⣤⠧⠓⣹⣟⣀⣤⣤⣤⡀',
+  '⠀⠈⠻⣧⠉⠛⣽⠀⠀⠀⠙⣷⡿⠁⠀⠀⠀⢻⣶⠛⠁⠀⠀⡟⠟⠉⣵⡟⠁⠀',
+  '⠀⠀⠀⠹⣧⡀⠏⡇⠀⠀⠀⣿⠁⠀⠀⠀⠀⠀⣿⡄⠀⠀⢠⢷⠀⣼⡟⠀⠀⠀',
+  '⠀⠀⠀⠀⠙⣟⢼⡹⡄⠀⠀⣿⡄⠀⠀⠀⠀⢀⣿⡇⠀⢀⣞⣦⢾⠟⠀⠀⠀⠀',
+  '⠀⠠⢶⣿⣛⠛⢒⣭⢻⣶⣤⣹⣿⣤⣀⣀⣠⣾⣟⣠⣔⡛⢫⣐⠛⢛⣻⣶⠆⠀',
+  '⠀⠀⠀⠉⣻⡽⠛⠉⠁⠀⠉⢙⣿⠖⠒⠛⠻⣿⡋⠉⠁⠈⠉⠙⢿⣿⠉⠀⠀⠀',
+  '⠀⠀⠀⠸⠿⠷⠒⣦⣤⣴⣶⢿⣿⡀⠀⠀⠀⣽⡿⢷⣦⠤⢤⡖⠶⠿⠧⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠛⢿⣦⣴⡾⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+]
+
+const TOP = '╭───────────────────────────────────────────────────────────────╮'
+const BOTTOM = '╰───────────────────────────────────────────────────────────────╯'
+const EMPTY = '│                                                               │'
+const INNER_WIDTH = 63
+
+function row(content) {
+  // content is a string of visible chars (ANSI-stripped width assumed equal to char count for ASCII)
+  // We can't easily measure visible width when ANSI codes are present, so always pad based on the
+  // PASSED visibleWidth in callers that contain colour. For plain rows, fall back to .length.
+  const visible = content.replace(/\x1b\[[0-9;]*m/g, '')
+  const padLen = Math.max(0, INNER_WIDTH - visible.length)
+  return `│${content}${' '.repeat(padLen)}│`
+}
+
+function centeredLotusRow(braille) {
+  // 30-col Braille row, 16-left + 17-right padding
+  return `│                ${colour(braille, PINK)}                 │`
+}
+
+function buildFullBanner(version) {
+  const lines = []
+  lines.push(colour(TOP, PINK_DIM))
+  lines.push(colour(EMPTY, PINK_DIM))
+  for (const lotusRow of LOTUS) {
+    lines.push(`${colour('│', PINK_DIM)}                ${colour(lotusRow, PINK)}                 ${colour('│', PINK_DIM)}`)
+  }
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('✦', PINK)}  ${colour('@devalok/shilp-sutra', BOLD)}  ${version}`))
+  lines.push(row(`      ${colour('Tailwind 4 design system · 110+ components · RSC-safe', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('▸', PINK)} Setup recipe (pick your framework):`))
+  lines.push(row(`     ${colour('node_modules/@devalok/shilp-sutra/docs/recipes/', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('▸', PINK)} Theme it in 30 seconds:`))
+  lines.push(row(`     ${colour('https://shilp-sutra.devalok.in/themer', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('▸', PINK)} Wire your AI agent (Claude Code / Cursor / Codex):`))
+  lines.push(row(`     ${colour('cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
+  lines.push(row(`        ${colour('~/.claude/skills/shilp-sutra', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('Disable this banner: SHILP_SUTRA_NO_WELCOME=1', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('Built by Devalok · devalok.in', PINK)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(colour(BOTTOM, PINK_DIM))
+  return lines.join('\n')
+}
+
+function buildCompactBanner(version) {
+  return [
+    '',
+    `${colour('✦', PINK)} ${colour('@devalok/shilp-sutra', BOLD)} ${version} ${colour('· Tailwind 4 design system', DIM)}`,
+    `  ${colour('▸', PINK)} Setup: ${colour('node_modules/@devalok/shilp-sutra/docs/recipes/', DIM)}`,
+    `  ${colour('▸', PINK)} Theme: ${colour('https://shilp-sutra.devalok.in/themer', DIM)}`,
+    `  ${colour('▸', PINK)} AI: ${colour('cp -r node_modules/@devalok/shilp-sutra/skill ~/.claude/skills/shilp-sutra', DIM)}`,
+    `  ${colour('Built by Devalok · devalok.in', PINK)}  ${colour('(SHILP_SUTRA_NO_WELCOME=1 to disable)', DIM)}`,
+    '',
+  ].join('\n')
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+function main() {
+  // --preview / --compact bypass all guards. Used by maintainers + by the
+  // pre-publish-audit gate to verify the banner renders without ever
+  // shipping a broken one. Compose only — never writes the sentinel.
+  const preview = process.argv.includes('--preview')
+  const forceCompact = process.argv.includes('--compact')
+
+  if (!preview) {
+    const skipReason = shouldSkip()
+    if (skipReason) return // silent
+  }
+
+  const version = readPkgVersion() || '0.0.0-preview'
+
+  if (!preview && alreadyWelcomed(version)) return
+
+  const cols = process.stdout.columns || 80
+  const rows = process.stdout.rows || 40
+  const fitsFull = !forceCompact && cols >= 70 && rows >= 28
+
+  const banner = fitsFull ? buildFullBanner(version) : buildCompactBanner(version)
+  process.stdout.write('\n' + banner + '\n')
+
+  if (!preview) markWelcomed(version)
+}
+
+try {
+  main()
+} catch {
+  // Never crash the consumer install. A failure here is a UX bug, not a
+  // blocker — pretend nothing happened.
+}

package/skill/README.md

@@ -0,0 +1,99 @@
+# shilp-sutra — Devalok Design System
+
+> Agent Skill for `@devalok/shilp-sutra` — Devalok Design & Strategy Studios' React design system. Tailwind 4, React 19, CVA, OKLCH tokens, framer-motion, 110+ accessible components.
+
+Use this skill when working in a React project that depends on `@devalok/shilp-sutra` (or when adding the package to one). It teaches the agent the correct setup, the per-framework playbook, the component API, the brand-token override pattern, and the Server Component import rules — all from the same files the design system ships in its npm tarball, so the skill never drifts from the live package.
+
+## When the agent should activate this skill
+
+- The user mentions `shilp-sutra`, `@devalok`, or Devalok's design system.
+- The project's `package.json` lists `@devalok/shilp-sutra` or `@devalok/shilp-sutra-brand`.
+- The user asks to install Tailwind, add UI components, theme an app, or migrate from shadcn/MUI/Chakra in a project that already has the package.
+
+## What's inside
+
+```
+shilp-sutra/
+├── SKILL.md                              # Entry — load this first
+├── README.md                             # This file (marketplace listing)
+├── LICENSE                               # MIT
+└── references/
+    ├── components.md                     # Concise component cheatsheet (~660 lines)
+    ├── components-full.md                # Exhaustive per-component reference (~6900 lines)
+    ├── setup-next-app-router.md          # Next.js (App Router) install playbook
+    ├── setup-next-pages.md               # Next.js (Pages Router) install playbook
+    ├── setup-vite.md                     # Vite + React install playbook
+    ├── setup-astro.md                    # Astro install playbook
+    ├── setup-remix.md                    # Remix install playbook
+    ├── setup-tanstack-start.md           # TanStack Start install playbook
+    ├── customize-brand.md                # Token override cookbook
+    ├── server-components.md              # RSC-safety matrix and import patterns
+    └── troubleshoot.md                   # Decision tree for the 8 most common breakages
+```
+
+## Install
+
+### Claude Code (personal)
+
+```bash
+# Option A — clone the repo (sparse) and copy the skill
+git clone --depth=1 --filter=blob:none --sparse https://github.com/devalok-design/shilp-sutra
+cd shilp-sutra
+git sparse-checkout set skills/shilp-sutra
+cp -r skills/shilp-sutra ~/.claude/skills/shilp-sutra
+
+# Option B — if @devalok/shilp-sutra is already a dependency in your project
+cp -r node_modules/@devalok/shilp-sutra/skill ~/.claude/skills/shilp-sutra
+
+# Option C — direct curl (latest from main)
+curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
+```
+
+Restart Claude Code or open a new session. Verify with `What skills are available?` — `shilp-sutra` should appear.
+
+### Project-scoped (commit to repo)
+
+```bash
+mkdir -p .claude/skills
+curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | INSTALL_DIR=.claude/skills bash
+git add .claude/skills/shilp-sutra
+git commit -m "chore: add shilp-sutra agent skill"
+```
+
+Every contributor (and their agent) on the project gets the skill automatically.
+
+### Cursor, Codex, Aider, and other tools
+
+The skill follows the [Agent Skills open standard](https://agentskills.io/specification) — any compatible agent loads it from the same directory. See your tool's docs for the install path.
+
+## What it teaches the agent
+
+- **Setup playbook** for Next.js (App + Pages), Vite, Astro, Remix, TanStack Start. Each recipe is concrete, copy-pasteable, and has been validated against real consumer projects.
+- **Hard constraints** — the eight ways to break Tailwind 4 + framer-motion setup that look unrelated to the design system but aren't.
+- **Component API** — every component, every variant, every example. Two layers: a cheatsheet for fast scans and a full reference for prop tables.
+- **RSC import patterns** — which components are server-safe, which need `"use client"`, and why per-component imports matter for Next.js.
+- **Theming** — how to override OKLCH ramps, radius, fonts, and the spacing scale without forking the package.
+- **Troubleshoot tree** — the eight most common breakages with the symptom, root cause, and exact fix for each.
+
+## Source of truth
+
+This skill is **built from** the package's own documentation (`packages/core/llms.txt`, `packages/core/llms-full.txt`, `packages/core/docs/recipes/`) by `scripts/build-skill.mjs`. The pre-publish audit fails if the bundled references drift from source, so the skill stays in sync with every release.
+
+## Versioning
+
+The skill version tracks the package version. Both are at the top of `SKILL.md` (frontmatter `metadata.version`) and in `package.json`. If you've installed the skill but upgraded the package, regenerate the skill or pull the latest from the repo.
+
+## Feedback
+
+If a recipe is wrong, a constraint is outdated, or a component behavior contradicts the docs, file an issue at <https://github.com/devalok-design/shilp-sutra/issues> with the label `ai-agent-feedback`. Include the package version, the file/recipe path, the command or error, and what you expected.
+
+## License
+
+MIT © Devalok Design & Strategy Studios. See `LICENSE`.
+
+## Links
+
+- npm: <https://www.npmjs.com/package/@devalok/shilp-sutra>
+- Storybook: <https://devalok-design.github.io/shilp-sutra/>
+- Repo: <https://github.com/devalok-design/shilp-sutra>
+- Agent Skills spec: <https://agentskills.io/specification>

package/skill/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: shilp-sutra
+description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
+license: MIT
+metadata:
+  version: "0.40.0"
+  author: Devalok Design & Strategy Studios
+  homepage: https://github.com/devalok-design/shilp-sutra
+  npm: https://www.npmjs.com/package/@devalok/shilp-sutra
+  source: https://github.com/devalok-design/shilp-sutra/tree/main/skills/shilp-sutra
+---
+
+# shilp-sutra — Devalok Design System
+
+`@devalok/shilp-sutra` is a React design system. It is **not** shadcn/ui. It uses similar primitives (Radix, CVA, Tailwind) but the consumer setup, token namespace, and component APIs are different. Your training data is older than the current package — read the bundled references before writing code, do not improvise from memory.
+
+## When this skill triggers
+
+- The user mentions `shilp-sutra`, `@devalok`, Devalok, or Devalok's design system.
+- The project's `package.json` lists `@devalok/shilp-sutra` (or `@devalok/shilp-sutra-brand`).
+- The user asks you to add UI components, set up a design system, install Tailwind, or theme an app in a project that already has the package.
+- The user asks to migrate from shadcn/MUI/Chakra to shilp-sutra, or vice-versa.
+
+## Decision tree (read this first, then jump)
+
+```
+Q1. Is @devalok/shilp-sutra already installed?
+    NO  → go to "First-time setup" below
+    YES → continue
+
+Q2. What does the user want to do?
+    a) Add or use a component        → references/components.md (skim), then components-full.md (deep)
+    b) Change colors/fonts/radius    → references/customize-brand.md
+    c) Server Components / Next.js   → references/server-components.md
+    d) Something is broken           → references/troubleshoot.md
+    e) Upgrading from older version  → fetch MIGRATION.md from repo or node_modules
+```
+
+## First-time setup
+
+Detect the framework from the consumer's lockfile and config files, then open the matching reference:
+
+| Detection                                                          | Reference                                |
+| ------------------------------------------------------------------ | ---------------------------------------- |
+| `app/` directory + `next.config.*`                                 | `references/setup-next-app-router.md`    |
+| `pages/` directory (no `app/`) + `next.config.*`                   | `references/setup-next-pages.md`         |
+| `vite.config.*` + `react` in deps (no Remix/TanStack)              | `references/setup-vite.md`               |
+| `astro.config.*`                                                   | `references/setup-astro.md`              |
+| `remix.config.*` or Remix v2 with Vite                             | `references/setup-remix.md`              |
+| `app.config.*` with `@tanstack/start`                              | `references/setup-tanstack-start.md`     |
+| Anything else (React + Tailwind)                                   | Fall back to `setup-vite.md` and adapt   |
+
+Every line in those recipes is there because skipping it broke a real consumer. Do not paraphrase steps — execute them.
+
+## Hard constraints (these silently break things if violated)
+
+These are non-negotiable. Violating any of them produces runtime errors that look unrelated to the design system.
+
+1. **Tailwind 4 only.** Do not create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup is CSS-only:
+   ```css
+   @import "tailwindcss";
+   @import "@devalok/shilp-sutra/css";
+   ```
+2. **`framer-motion@^12` is a required peer dep.** The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies of framer-motion resolve. Configure pnpm/yarn to dedupe.
+3. **`sonner@^2` is an optional peer dep.** Install only when rendering `<Toaster />`.
+4. **Per-component imports are mandatory for React Server Components.** `@devalok/shilp-sutra/ui/text` is server-safe; the barrel `@devalok/shilp-sutra/ui` pulls client code and crashes RSC. See `references/server-components.md` for the per-component matrix.
+5. **Spacing namespace is `--spacing-ds-*`.** Write `p-ds-04`, not `p-4`. Same for typography: `text-ds-body-md`, not `text-base`.
+6. **Bare `shadow` does not exist in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`. Bare `rounded` is fine (maps to `--radius`); `rounded-ds-lg` etc. for sized variants.
+7. **Do not invent variant names.** CVA source files at `node_modules/@devalok/shilp-sutra/dist/ui/*.d.ts` (or `packages/core/src/ui/*.tsx` in the DS repo) are authoritative. When in doubt, check `references/components-full.md` for the enumerated list. If you guess a variant that doesn't exist, the prop is silently dropped and the default applies.
+8. **Default `variant="soft"` over `variant="outline"` for non-primary Button actions.** Soft (tinted bg + tinted text, no border) reads warmer in data-dense UIs. Use outline only when soft would disappear on a colored background or when a primary/secondary hierarchy needs a visible border.
+
+## Surface layering (when building cards, panels, dialogs)
+
+The semantic surface names are the public API. The old numeric names (`surface-1` … `surface-4`) are deprecated aliases — do not use them.
+
+| Token                          | Use for                                                                            |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `bg-surface-base`              | Page background                                                                    |
+| `bg-surface-raised`            | Cards, widgets, panels — anything that sits **on** the page                        |
+| `bg-surface-sunken`            | Shell chrome (Sidebar, TopBar), recessed regions                                   |
+| `bg-surface-overlay`           | Dialog, Sheet, Popover, Toast, Combobox menus, any floating overlay                |
+| `bg-surface-raised-hover`      | Hover state on raised surfaces                                                     |
+| `bg-surface-raised-active`     | Active/pressed state on raised surfaces                                            |
+| `bg-surface-disabled`          | Disabled surfaces (paired with `text-surface-fg-disabled`)                         |
+| `bg-surface-inverted`          | Inverted surfaces (dark on light themes, light on dark themes)                     |
+
+Putting `bg-surface-base` on a card is a bug — cards belong on `surface-raised`. The pre-publish audit in the DS repo enforces this and blocks the old numeric aliases in component source files.
+
+## Adding a component
+
+1. Skim `references/components.md` — the concise cheatsheet, ~660 lines. Tells you what exists, what variants ship, what the common gotchas are.
+2. If `components.md` does not have enough detail (you need full prop tables, every variant, every example), open `references/components-full.md`.
+3. Import from the per-component entry: `import { Button } from "@devalok/shilp-sutra/ui/button"`. The barrel `@devalok/shilp-sutra/ui` works in client-only contexts but is heavier — prefer per-component.
+4. Use **semantic tokens** for color (`text-foreground`, `bg-surface-2`, `border-border-default`). Never raw OKLCH values, never `text-white`.
+5. Compose with primitives the package already ships. Do not rebuild Dialog/Popover/Combobox from scratch.
+
+## Theming and brand customization
+
+### Step 0 — Send the user to the Themer
+
+Before hand-rolling CSS variables, send the user to **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)**. One funnel, four doors:
+
+| User context | Door |
+|---|---|
+| "Make it look like Linear / Stripe / Apple / Notion / Vercel / Material" | `/themer/archetypes` |
+| "Here is our brand color: `#…`" | `/themer/brand` |
+| "Not sure what we want yet" | `/themer/wizard` |
+| "Just show me what we'd ship away with" | `/themer/result?archetype=devalok` |
+
+Every door drops them at `/themer/result` with: a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp), install commands for their package manager, a live preview, and 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 is it — no `tailwind.config.ts`, no provider, no JS bundle.
+
+If the user is in a hurry and asks you to just pick something, default to `archetype=devalok` (the studio's own preset, balanced for most apps) and use their brand hex if they have one, else `hue=340 chroma=0.19`.
+
+### Step 1 — Hand-roll fallback
+
+`references/customize-brand.md` covers what the Themer doesn't expose yet: font swap, spacing scale, focus-ring overrides, dark-mode mapping nuance. Customization is CSS-only: override CSS custom properties under `:root` and `.dark`. There is no theme provider component.
+
+For the Devalok logo and other brand assets, the sibling package `@devalok/shilp-sutra-brand` ships SVG + PNG. Install it separately.
+
+## Server Components and import patterns
+
+`references/server-components.md` has the per-component RSC-safety matrix. The short version:
+
+- Layout, typography, and presentational components (`Text`, `Heading`, `Card`, `Container`, `Stack`) → server-safe.
+- Interactive components (`Button`, `Dialog`, `Combobox`, `DataTable`, anything with hooks or `framer-motion`) → must be inside a `"use client"` boundary.
+- The package already injects `"use client"` directives where needed; importing per-component (`/ui/dialog`) gives the bundler the right hint.
+- Next.js consumers must add `transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]` to `next.config.*`.
+
+## When something breaks
+
+Go straight to `references/troubleshoot.md`. It is a decision tree for the 8 most common breakages: Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches.
+
+Do not guess — most of these failures look identical from the outside but have different root causes. The tree disambiguates.
+
+## Browsing the system
+
+- **Storybook** (live previews, every story, MCP server available when running locally): https://devalok-design.github.io/shilp-sutra/
+- **Component reference (this skill)**: `references/components.md` (cheatsheet) and `references/components-full.md` (full API).
+- **Source**: https://github.com/devalok-design/shilp-sutra — `packages/core/src/ui/*.tsx` are the CVA sources of truth.
+
+When the package is installed locally, the same content also ships in the npm tarball:
+
+- `node_modules/@devalok/shilp-sutra/llms.txt` — cheatsheet
+- `node_modules/@devalok/shilp-sutra/llms-full.txt` — full reference
+- `node_modules/@devalok/shilp-sutra/docs/recipes/` — setup recipes
+- `node_modules/@devalok/shilp-sutra/skill/` — this skill (offline-installable)
+
+## Reporting feedback
+
+If a recipe is wrong, a constraint above is no longer accurate, or a component behavior contradicts the docs:
+
+1. File a GitHub issue at https://github.com/devalok-design/shilp-sutra/issues with the label `ai-agent-feedback`.
+2. Include the package version (`pnpm view @devalok/shilp-sutra version` or read from the consumer's lockfile), the file/recipe path, the exact command or error, and what you expected.
+
+## Stay current
+
+`@devalok/shilp-sutra` ships breaking changes during `0.x`. Before writing code:
+
+1. Check the installed version: `cat node_modules/@devalok/shilp-sutra/package.json | grep version` (or read from the consumer's lockfile).
+2. If the version is older than the metadata `version` field at the top of this SKILL.md, suggest the user upgrade and consult `MIGRATION.md` from the package root.
+3. Never trust APIs you remember from earlier versions — re-check `components.md` against the installed version.

package/skill/install.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Install the shilp-sutra Agent Skill into ~/.claude/skills (or $INSTALL_DIR).
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
+#
+# Custom install dir (e.g. project-scoped):
+#   curl -fsSL ... | INSTALL_DIR=.claude/skills bash
+
+set -euo pipefail
+
+REPO="devalok-design/shilp-sutra"
+BRANCH="${BRANCH:-main}"
+INSTALL_DIR="${INSTALL_DIR:-$HOME/.claude/skills}"
+SKILL_NAME="shilp-sutra"
+DEST="$INSTALL_DIR/$SKILL_NAME"
+
+if [[ -d "$DEST" ]]; then
+  echo "warning: $DEST already exists. Overwriting."
+  rm -rf "$DEST"
+fi
+
+mkdir -p "$DEST/references"
+
+# Fetch the skill tree via the GitHub trees API and download each file.
+echo "Fetching skill manifest from github.com/$REPO@$BRANCH ..."
+tree_json="$(curl -fsSL "https://api.github.com/repos/$REPO/git/trees/$BRANCH?recursive=1")"
+
+# Extract every path under skills/shilp-sutra/ that is a blob.
+paths="$(printf '%s\n' "$tree_json" \
+  | python3 -c '
+import json, sys
+tree = json.load(sys.stdin).get("tree", [])
+for item in tree:
+    if item.get("type") == "blob" and item.get("path", "").startswith("skills/shilp-sutra/"):
+        # Skip the install.sh itself when bootstrapping; user already has it via curl.
+        if item["path"].endswith("/install.sh"):
+            continue
+        print(item["path"])
+')"
+
+if [[ -z "$paths" ]]; then
+  echo "error: no files found under skills/shilp-sutra/ on $REPO@$BRANCH" >&2
+  exit 1
+fi
+
+count=0
+while IFS= read -r path; do
+  rel="${path#skills/shilp-sutra/}"
+  target="$DEST/$rel"
+  mkdir -p "$(dirname "$target")"
+  curl -fsSL "https://raw.githubusercontent.com/$REPO/$BRANCH/$path" -o "$target"
+  count=$((count + 1))
+done <<< "$paths"
+
+echo
+echo "installed $count files to $DEST"
+echo "restart Claude Code (or open a new session) to pick up the skill."
+echo "verify with: ask Claude 'what skills are available?'"