@devalok/shilp-sutra 0.44.0 → 0.45.0

package/mcp-manifest.schema.json

@@ -0,0 +1,232 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://shilp-sutra.devalok.in/mcp-manifest.schema.json",
+  "title": "shilp-sutra MCP manifest",
+  "description": "Machine-readable component/token reference emitted at build time and shipped in the npm tarball from 0.45.0. The hosted docs MCP server extracts this file from published tarballs and serves slices of it — it never parses markdown. Prop shape mirrors react-docgen/Storybook ArgTypes so AI agents consume it zero-shot. Authored standard: docs/specs/mcp-manifest-standard.md.",
+  "type": "object",
+  "required": ["manifestVersion", "package", "packageVersion", "components", "tokens"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "manifestVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver of the manifest FORMAT (this standard), not the package. The MCP server declares a supported range; mismatch is an explicit error, never a silent misparse."
+    },
+    "package": {
+      "type": "string",
+      "examples": ["@devalok/shilp-sutra"]
+    },
+    "packageVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Must equal package.json version at build time — enforced by pre-publish audit gate."
+    },
+    "generatedAt": {
+      "type": "string",
+      "description": "ISO 8601 build timestamp."
+    },
+    "components": {
+      "type": "object",
+      "description": "Every published component, keyed by kebab-name. Coverage must equal the component scan in build-component-docs.mjs — a missing entry fails the audit gate.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": { "$ref": "#/$defs/component" }
+      },
+      "additionalProperties": false
+    },
+    "tokens": {
+      "type": "object",
+      "description": "Design-token reference by category, extracted from src/tokens/*.css.",
+      "properties": {
+        "color": { "$ref": "#/$defs/tokenList" },
+        "spacing": { "$ref": "#/$defs/tokenList" },
+        "typography": { "$ref": "#/$defs/tokenList" },
+        "radius": { "$ref": "#/$defs/tokenList" },
+        "shadow": { "$ref": "#/$defs/tokenList" },
+        "motion": { "$ref": "#/$defs/tokenList" },
+        "z": { "$ref": "#/$defs/tokenList" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "component": {
+      "type": "object",
+      "required": ["displayName", "tier", "import", "serverSafe", "description", "props", "composition", "docPath"],
+      "additionalProperties": false,
+      "properties": {
+        "displayName": { "type": "string", "examples": ["Button"] },
+        "tier": { "enum": ["ui", "composed", "shell", "ai"] },
+        "import": { "type": "string", "examples": ["@devalok/shilp-sutra/ui/button"] },
+        "serverSafe": { "type": "boolean" },
+        "description": { "type": "string", "description": "One-line purpose." },
+        "props": {
+          "type": "object",
+          "description": "react-docgen convention: object keyed by prop name.",
+          "additionalProperties": { "$ref": "#/$defs/prop" }
+        },
+        "defaults": {
+          "type": "object",
+          "description": "Convenience mirror of each prop's defaultValue for props with defaults (from the doc's Defaults section).",
+          "additionalProperties": { "type": ["string", "number", "boolean"] }
+        },
+        "examples": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Verbatim JSX snippets from the doc's Example section."
+        },
+        "composition": { "$ref": "#/$defs/composition" },
+        "gotchas": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Known-misuse bullets, verbatim, DO-NOT phrasing preferred."
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["version", "summary"],
+            "additionalProperties": false,
+            "properties": {
+              "version": { "type": "string" },
+              "summary": { "type": "string" }
+            }
+          },
+          "description": "Per-component change history from the doc's Changes section, newest first."
+        },
+        "storybook": { "type": "string", "description": "Published Storybook docs URL for this component." },
+        "docPath": {
+          "type": "string",
+          "description": "Tarball-relative path to the human/fallback markdown doc.",
+          "examples": ["docs/components/ui/button.md"]
+        }
+      }
+    },
+    "prop": {
+      "type": "object",
+      "required": ["type", "required"],
+      "additionalProperties": false,
+      "description": "react-docgen/ArgTypes shape: { type: { name, value?, raw? }, required, defaultValue?, description? }.",
+      "properties": {
+        "type": {
+          "type": "object",
+          "required": ["name"],
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "enum": ["enum", "boolean", "string", "number", "function", "ReactNode", "ReactElement", "object", "union"]
+            },
+            "value": {
+              "type": "array",
+              "items": { "type": ["string", "number", "boolean"] },
+              "description": "Enum members when type.name is 'enum'."
+            },
+            "raw": {
+              "type": "string",
+              "description": "Literal TypeScript type text for unions/functions/objects that enum members can't express.",
+              "examples": ["boolean | 'ambient' | 'working' | 'urgent'", "(e: MouseEvent) => Promise<void>"]
+            }
+          }
+        },
+        "required": { "type": "boolean" },
+        "defaultValue": { "type": ["string", "number", "boolean"] },
+        "description": { "type": "string" }
+      }
+    },
+    "composition": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Design-intent layer — how this component composes. Not extractable from CVA; authored via tagged bullets in the doc's Composability section (see standard §1.3/§2).",
+      "properties": {
+        "parts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "examples": ["CardHeader"] },
+              "slot": { "type": "string", "description": "Position contract within the parent.", "examples": ["top"] },
+              "required": { "type": "boolean" },
+              "description": { "type": "string" }
+            }
+          },
+          "description": "Compound subcomponents this component exports."
+        },
+        "slots": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "examples": ["children"] },
+              "accepts": { "type": "array", "items": { "type": "string" } },
+              "description": { "type": "string" }
+            }
+          },
+          "description": "Named children positions and what they accept."
+        },
+        "composesWith": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["component", "relation"],
+            "additionalProperties": false,
+            "properties": {
+              "component": { "type": "string", "description": "kebab-name of the related component." },
+              "relation": {
+                "enum": ["specializes", "contains", "pairs", "provides-context", "consumes-context", "alternative-to"],
+                "description": "Closed vocabulary. 'specializes' = builds ON the target instead of re-rolling it (StatCard specializes Card)."
+              },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "containedBy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "kebab-names (or 'page') where this component legitimately lives."
+        },
+        "contexts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "effect"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "examples": ["ButtonGroup"] },
+              "effect": { "type": "string", "examples": ["inherits variant/color/size; position-aware radius"] }
+            }
+          },
+          "description": "React contexts consumed or provided that change rendered behavior."
+        },
+        "antiPatterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Known composition misuse, DO-NOT phrasing with the correct alternative."
+        },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Untagged Composability prose bullets carried over verbatim — lets existing docs parse before incremental tagging."
+        }
+      }
+    },
+    "tokenList": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "description": "CSS custom property.", "examples": ["--spacing-ds-03"] },
+          "utility": { "type": "string", "description": "Tailwind utility it generates, if any.", "examples": ["p-ds-03"] },
+          "value": { "type": "string", "description": "Resolved value (light mode where dual)." },
+          "darkValue": { "type": "string", "description": "Dark-mode value when it differs." },
+          "usage": { "type": "string", "description": "One-line when-to-use." }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",
@@ -432,6 +432,11 @@
       "import": "./dist/ui/tooltip.js",
       "default": "./dist/ui/tooltip.js"
     },
+    "./ui/truncated-text": {
+      "types": "./dist/ui/truncated-text.d.ts",
+      "import": "./dist/ui/truncated-text.js",
+      "default": "./dist/ui/truncated-text.js"
+    },
     "./ui/visually-hidden": {
       "types": "./dist/ui/visually-hidden.d.ts",
       "import": "./dist/ui/visually-hidden.js",
@@ -812,8 +817,8 @@
     "MIGRATION.md",
     "README.md",
     "llms.txt",
-    "llms-quick.txt",
-    "llms-full.txt"
+    "mcp-manifest.json",
+    "mcp-manifest.schema.json"
   ],
   "agents": {
     "skills": [

package/skill/README.md

@@ -19,7 +19,6 @@ shilp-sutra/
 ├── 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

package/skill/SKILL.md

@@ -3,7 +3,7 @@ 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.44.0"
+  version: "0.45.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra
@@ -29,7 +29,7 @@ Q1. Is @devalok/shilp-sutra already installed?
     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)
+    a) Add or use a component        → references/components.md (router), then the per-component doc at node_modules/@devalok/shilp-sutra/docs/components/<tier>/<name>.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
@@ -67,7 +67,7 @@ These are non-negotiable. Violating any of them produces runtime errors that loo
 4. **Prefer per-component imports — they keep RSC bundles small 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 deps like `input-otp`), so it forces those peers to install even when unused. With all peers installed the barrel also works in RSC (per-component `"use client"` is honoured), but the client bundle is larger. Prefer per-component for new code; existing barrel usage is not an emergency. See `references/server-components.md`.
 5. **Spacing uses the `--spacing-ds-*` namespace** (`p-ds-04`, `gap-ds-03`); typography uses `text-ds-body-md`. These **coexist with** Tailwind 4's numeric scale (`p-4`, `gap-2`) by design — both valid. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout. Do NOT mass-codemod `p-4` → `p-ds-04`. **Cadence when building layouts:** pick a 3-tier scale, not every adjacent token — `ds-03` (related: label↔field), `ds-05` (grouped: between field-groups), `ds-07` (section: between blocks), optional `ds-08`+ (hero). 3-4 distinct gaps per surface; 5+ reads muddy. Anti-pattern: `ds-02` + `ds-04` as different signals on one surface — they collapse. The squint test must still reveal grouping.
 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.
+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 `node_modules/@devalok/shilp-sutra/mcp-manifest.json` (props as JSON) or the per-component doc 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)
@@ -89,8 +89,8 @@ Putting `bg-surface-base` on a card is a bug — cards belong on `surface-raised
 
 ## 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`.
+1. Skim `references/components.md` — the router. Tells you what exists and where each component's full doc lives.
+2. If `components.md` does not have enough detail (you need full prop tables, every variant, every example), open the per-component doc at `node_modules/@devalok/shilp-sutra/docs/components/<tier>/<name>.md`, or read the component's entry in `node_modules/@devalok/shilp-sutra/mcp-manifest.json`.
 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.
@@ -140,13 +140,14 @@ Do not guess — most of these failures look identical from the outside but have
 ## 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).
+- **Component reference (this skill)**: `references/components.md` (router); full API per component via `docs/components/` or `mcp-manifest.json` in the installed package.
 - **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/llms.txt` — router (what exists + where to get detail)
+- `node_modules/@devalok/shilp-sutra/docs/components/<tier>/<name>.md` — per-component reference
+- `node_modules/@devalok/shilp-sutra/mcp-manifest.json` — machine-readable props/tokens/composition
 - `node_modules/@devalok/shilp-sutra/docs/recipes/` — setup recipes
 - `node_modules/@devalok/shilp-sutra/skill/` — this skill (offline-installable)