npm - @devalok/shilp-sutra - Versions diffs - 0.38.0 → 0.39.0 - Mend

@devalok/shilp-sutra 0.38.0 → 0.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (212) hide show

package/MIGRATION.md +118 -0
package/dist/_chunks/badge-group.js +4 -4
package/dist/_chunks/badge-group.js.map +1 -1
package/dist/_chunks/chat.js +14 -14
package/dist/_chunks/chat.js.map +1 -1
package/dist/_chunks/date-picker.js +9 -9
package/dist/_chunks/date-picker.js.map +1 -1
package/dist/_chunks/document-preview.js +2 -2
package/dist/_chunks/document-preview.js.map +1 -1
package/dist/_chunks/file-preview.js +11 -11
package/dist/_chunks/file-preview.js.map +1 -1
package/dist/_chunks/image-preview.js +2 -2
package/dist/_chunks/image-preview.js.map +1 -1
package/dist/_chunks/mention-suggestion.js +5 -5
package/dist/_chunks/mention-suggestion.js.map +1 -1
package/dist/_chunks/popover.js +3 -3
package/dist/_chunks/popover.js.map +1 -1
package/dist/_chunks/rich-chat-input.js +33 -33
package/dist/_chunks/rich-chat-input.js.map +1 -1
package/dist/_chunks/shared.js +5 -5
package/dist/_chunks/shared.js.map +1 -1
package/dist/_chunks/text.js +2 -2
package/dist/_chunks/text.js.map +1 -1
package/dist/_chunks/tree-view.js +1 -1
package/dist/_chunks/tree-view.js.map +1 -1
package/dist/_chunks/use-calendar.js +5 -5
package/dist/_chunks/use-calendar.js.map +1 -1
package/dist/ai/command-bar.js +10 -10
package/dist/ai/command-bar.js.map +1 -1
package/dist/ai/conversation.js +4 -4
package/dist/ai/conversation.js.map +1 -1
package/dist/composed/activity-feed.js +5 -5
package/dist/composed/activity-feed.js.map +1 -1
package/dist/composed/avatar-group.js +4 -4
package/dist/composed/avatar-group.js.map +1 -1
package/dist/composed/bulk-action-bar.js +1 -1
package/dist/composed/bulk-action-bar.js.map +1 -1
package/dist/composed/command-palette.js +5 -5
package/dist/composed/command-palette.js.map +1 -1
package/dist/composed/content-card.js +1 -1
package/dist/composed/content-card.js.map +1 -1
package/dist/composed/emoji-picker.js +4 -4
package/dist/composed/emoji-picker.js.map +1 -1
package/dist/composed/empty-state.js +1 -1
package/dist/composed/empty-state.js.map +1 -1
package/dist/composed/error-boundary.js +3 -3
package/dist/composed/error-boundary.js.map +1 -1
package/dist/composed/filter-bar.js +1 -1
package/dist/composed/filter-bar.js.map +1 -1
package/dist/composed/inline-edit.js +1 -1
package/dist/composed/inline-edit.js.map +1 -1
package/dist/composed/loading-skeleton.js +9 -9
package/dist/composed/loading-skeleton.js.map +1 -1
package/dist/composed/markdown-viewer.js +3 -3
package/dist/composed/markdown-viewer.js.map +1 -1
package/dist/composed/multi-select-popover.js +1 -1
package/dist/composed/multi-select-popover.js.map +1 -1
package/dist/composed/page-header.js +1 -1
package/dist/composed/page-header.js.map +1 -1
package/dist/composed/page-skeletons.js +15 -15
package/dist/composed/page-skeletons.js.map +1 -1
package/dist/composed/priority-indicator.js +3 -3
package/dist/composed/priority-indicator.js.map +1 -1
package/dist/composed/rich-text-editor.js +11 -11
package/dist/composed/rich-text-editor.js.map +1 -1
package/dist/composed/schedule-view.js +3 -3
package/dist/composed/schedule-view.js.map +1 -1
package/dist/composed/status-badge.js +3 -3
package/dist/composed/status-badge.js.map +1 -1
package/dist/shell/bottom-navbar.js +6 -6
package/dist/shell/bottom-navbar.js.map +1 -1
package/dist/shell/notification-center.js +8 -8
package/dist/shell/notification-center.js.map +1 -1
package/dist/shell/notification-preferences.js +1 -1
package/dist/shell/notification-preferences.js.map +1 -1
package/dist/shell/sidebar.js +6 -6
package/dist/shell/sidebar.js.map +1 -1
package/dist/shell/top-bar.js +4 -4
package/dist/shell/top-bar.js.map +1 -1
package/dist/tokens/semantic.css +82 -9
package/dist/ui/accordion.js +1 -1
package/dist/ui/accordion.js.map +1 -1
package/dist/ui/alert-dialog.js +3 -3
package/dist/ui/alert-dialog.js.map +1 -1
package/dist/ui/alert.js +2 -2
package/dist/ui/alert.js.map +1 -1
package/dist/ui/autocomplete.js +2 -2
package/dist/ui/autocomplete.js.map +1 -1
package/dist/ui/avatar.js +11 -11
package/dist/ui/avatar.js.map +1 -1
package/dist/ui/badge-indicator.js +1 -1
package/dist/ui/badge-indicator.js.map +1 -1
package/dist/ui/banner.js +1 -1
package/dist/ui/banner.js.map +1 -1
package/dist/ui/breadcrumb.js +1 -1
package/dist/ui/breadcrumb.js.map +1 -1
package/dist/ui/button.d.ts +2 -2
package/dist/ui/button.js +14 -14
package/dist/ui/button.js.map +1 -1
package/dist/ui/card.js +5 -5
package/dist/ui/card.js.map +1 -1
package/dist/ui/charts/index.js +5 -5
package/dist/ui/charts/index.js.map +1 -1
package/dist/ui/checkbox.js +1 -1
package/dist/ui/checkbox.js.map +1 -1
package/dist/ui/code.js +2 -2
package/dist/ui/code.js.map +1 -1
package/dist/ui/color-input.js +10 -10
package/dist/ui/color-input.js.map +1 -1
package/dist/ui/color-swatch.js +3 -3
package/dist/ui/color-swatch.js.map +1 -1
package/dist/ui/combobox.js +5 -5
package/dist/ui/combobox.js.map +1 -1
package/dist/ui/context-menu.js +6 -6
package/dist/ui/context-menu.js.map +1 -1
package/dist/ui/data-table-body.js +1 -1
package/dist/ui/data-table-body.js.map +1 -1
package/dist/ui/data-table-bulk-actions.js +2 -2
package/dist/ui/data-table-bulk-actions.js.map +1 -1
package/dist/ui/data-table-card.js +2 -2
package/dist/ui/data-table-card.js.map +1 -1
package/dist/ui/data-table-header.js +2 -2
package/dist/ui/data-table-header.js.map +1 -1
package/dist/ui/data-table-pagination.js +3 -3
package/dist/ui/data-table-pagination.js.map +1 -1
package/dist/ui/data-table-toolbar.js +1 -1
package/dist/ui/data-table-toolbar.js.map +1 -1
package/dist/ui/data-table.js +1 -1
package/dist/ui/data-table.js.map +1 -1
package/dist/ui/devalok-grain.d.ts +1 -1
package/dist/ui/devalok-grain.js.map +1 -1
package/dist/ui/dialog.js +2 -2
package/dist/ui/dialog.js.map +1 -1
package/dist/ui/dropdown-menu.js +6 -6
package/dist/ui/dropdown-menu.js.map +1 -1
package/dist/ui/file-upload.js +4 -4
package/dist/ui/file-upload.js.map +1 -1
package/dist/ui/hover-card.js +1 -1
package/dist/ui/hover-card.js.map +1 -1
package/dist/ui/icon-button.js +1 -1
package/dist/ui/icon-button.js.map +1 -1
package/dist/ui/input-otp.js +1 -1
package/dist/ui/input-otp.js.map +1 -1
package/dist/ui/input.js +2 -2
package/dist/ui/input.js.map +1 -1
package/dist/ui/link.js +1 -1
package/dist/ui/link.js.map +1 -1
package/dist/ui/menubar.js +8 -8
package/dist/ui/menubar.js.map +1 -1
package/dist/ui/navigation-menu.js +3 -3
package/dist/ui/navigation-menu.js.map +1 -1
package/dist/ui/number-input.js +3 -3
package/dist/ui/number-input.js.map +1 -1
package/dist/ui/pagination.js +1 -1
package/dist/ui/pagination.js.map +1 -1
package/dist/ui/progress.js +1 -1
package/dist/ui/progress.js.map +1 -1
package/dist/ui/radio.js +1 -1
package/dist/ui/radio.js.map +1 -1
package/dist/ui/segmented-control.js +3 -3
package/dist/ui/segmented-control.js.map +1 -1
package/dist/ui/select.js +3 -3
package/dist/ui/select.js.map +1 -1
package/dist/ui/sheet.js +2 -2
package/dist/ui/sheet.js.map +1 -1
package/dist/ui/sidebar.js +11 -11
package/dist/ui/sidebar.js.map +1 -1
package/dist/ui/skeleton.js +9 -9
package/dist/ui/skeleton.js.map +1 -1
package/dist/ui/slider.js +2 -2
package/dist/ui/slider.js.map +1 -1
package/dist/ui/split-button.js +7 -7
package/dist/ui/split-button.js.map +1 -1
package/dist/ui/stat-card.js +7 -7
package/dist/ui/stat-card.js.map +1 -1
package/dist/ui/status-dot.js +2 -2
package/dist/ui/status-dot.js.map +1 -1
package/dist/ui/stepper.js +2 -2
package/dist/ui/stepper.js.map +1 -1
package/dist/ui/switch.js +2 -2
package/dist/ui/switch.js.map +1 -1
package/dist/ui/tabs.js +3 -3
package/dist/ui/tabs.js.map +1 -1
package/dist/ui/textarea.js +1 -1
package/dist/ui/textarea.js.map +1 -1
package/dist/ui/toast.js +8 -8
package/dist/ui/toast.js.map +1 -1
package/dist/ui/toggle.js +1 -1
package/dist/ui/toggle.js.map +1 -1
package/dist/ui/tooltip.js +1 -1
package/dist/ui/tooltip.js.map +1 -1
package/docs/components/_header.md +90 -1
package/docs/recipes/customize-brand.md +85 -4
package/docs/recipes/index.md +1 -1
package/llms-full.txt +91 -2
package/llms.txt +9 -1
package/package.json +2 -1
package/skill/README.md +99 -0
package/skill/SKILL.md +144 -0
package/skill/install.sh +59 -0
package/skill/references/components-full.md +6997 -0
package/skill/references/components.md +673 -0
package/skill/references/customize-brand.md +299 -0
package/skill/references/server-components.md +211 -0
package/skill/references/setup-astro.md +180 -0
package/skill/references/setup-next-app-router.md +232 -0
package/skill/references/setup-next-pages.md +125 -0
package/skill/references/setup-remix.md +173 -0
package/skill/references/setup-tanstack-start.md +145 -0
package/skill/references/setup-vite.md +172 -0
package/skill/references/troubleshoot.md +219 -0
/package/{LICENSE → skill/LICENSE} +0 -0

package/docs/recipes/customize-brand.md CHANGED Viewed

@@ -56,19 +56,100 @@ To swap to teal:
 For a quick swap without redoing the full scale, only override step 9 (background) and step 11 (foreground). Other steps will still reference the original chroma — visually mismatched but functional.
-### Change the radius scale
+### Shape presets (`[data-shape]`)
+The simplest way to change roundness for the whole UI is to set a `data-shape` attribute on the document (or any subtree). Three presets ship by default — `sharp`, `slightly-rounded` (the default if no attribute), and `rounded`. Pill shapes (Badge, Switch, Slider, Avatar circle) stay pill in every preset.
+```html
+<!-- Whole-app, sharp/technical feel -->
+<html data-shape="sharp">
+<!-- Whole-app, soft/consumer feel -->
+<html data-shape="rounded">
+```
+You can scope it to a subtree if a particular section wants different shape language than the rest:
+```tsx
+<div data-shape="sharp">
+  <DeveloperConsole />
+</div>
+```
+Visual feel:
+| Preset | Identity | Comparable to |
+|---|---|---|
+| `sharp` | Technical, precise, "serious software" | Vercel, Linear, terminal UIs |
+| `slightly-rounded` (default) | Modern SaaS neutral | shadcn default, Stripe, Notion sidebar |
+| `rounded` | Friendly, soft, consumer | iOS, Notion content, modern startup landings |
+### Custom radius — override a role token
+If a preset doesn't fit, you can override any semantic radius role token directly. Components reference these role tokens (not the primitive scale), so a single override propagates everywhere.
+```css
+/* Tighten controls only; leave overlays / surfaces alone */
+:root {
+  --radius-control: 4px;
+}
+/* Or scoped to a subtree */
+.checkout {
+  --radius-control: 8px;
+  --radius-surface: 20px;
+}
+```
+The role tokens (defaults shown — the "slightly-rounded" preset):
+| Token                    | Default | Used by |
+|--------------------------|---------|---------|
+| `--radius-control`       | 6px     | Button, Input, Select, Tabs trigger, Toggle, Code block |
+| `--radius-control-inner` | 2px     | Checkbox box, ±/close buttons, inline Code |
+| `--radius-surface`       | 10px    | Card, Alert, Accordion |
+| `--radius-overlay-sm`    | 6px     | Tooltip, Toast |
+| `--radius-overlay`       | 10px    | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, listboxes |
+| `--radius-overlay-lg`    | 16px    | Dialog, AlertDialog, Sheet, BottomSheet, ColorInput picker |
+| `--radius-pill`          | 9999px  | Badge, StatusDot, Radio, Switch, Slider, Progress, Avatar circle |
+| `--radius-bubble`        | 24px    | ChatMessage bubble |
+### Build your own preset
+Define your own `[data-shape="…"]` block and swap to it whenever you want:
+```css
+[data-shape="brand-soft"] {
+  --radius-control:        8px;
+  --radius-control-inner:  3px;
+  --radius-surface:        14px;
+  --radius-overlay-sm:     8px;
+  --radius-overlay:        14px;
+  --radius-overlay-lg:     20px;
+  --radius-pill:           9999px;
+  --radius-bubble:         28px;
+}
+```
+```html
+<html data-shape="brand-soft">
+```
+### Change the primitive radius scale (advanced)
+If you're rebuilding the entire system rather than just rebranding, you can also override the primitive scale that the role tokens reference:
 ```css
 @theme {
-  --radius-ds-sm: 0.25rem;   /* small */
-  --radius-ds-md: 0.5rem;    /* default */
+  --radius-ds-sm: 0.25rem;
+  --radius-ds-md: 0.5rem;
   --radius-ds-lg: 0.75rem;
   --radius-ds-xl: 1rem;
   --radius: 0.5rem;          /* unsuffixed — generates bare `rounded` */
 }
 ```
-For a flat, sharp brand, set everything to `0`. For a heavily rounded brand, scale up.
+Most consumers should NOT touch this — overriding the role tokens above is the cleaner path.
 ### Change fonts

package/docs/recipes/index.md CHANGED Viewed

@@ -29,7 +29,7 @@ If the framework is not listed, start with [install-vite.md](./install-vite.md)
 | Recipe | What it covers |
 |---|---|
-| [customize-brand.md](./customize-brand.md) | Token override cookbook — change colors, radius, fonts, spacing scale, dark-mode mapping |
+| [customize-brand.md](./customize-brand.md) | Token override cookbook — colors, radius role tokens, `[data-shape]` presets, fonts, spacing scale, dark-mode mapping |
 | [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
 ## Diagnostics

package/llms-full.txt CHANGED Viewed

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.38.0
+> Version: 0.39.0
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a
@@ -67,7 +67,8 @@ transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
 | `--leading-ds-*` | `leading-ds-tight`, `leading-ds-normal` | ds-namespaced |
 | `--tracking-*` | `tracking-tight`, `tracking-normal` | standard TW namespace |
 | `--font-*`, `--font-weight-*` | `font-sans`, `font-semibold` | standard TW namespace |
-| `--radius`, `--radius-ds-*` | `rounded` (bare), `rounded-ds-lg` | unprefixed + ds-namespaced |
+| `--radius`, `--radius-ds-*` | `rounded` (bare), `rounded-ds-lg` | unprefixed + ds-namespaced primitive scale |
+| `--radius-control`, `--radius-surface`, `--radius-overlay-*`, `--radius-pill`, `--radius-bubble` | `rounded-control`, `rounded-surface`, `rounded-overlay`, `rounded-pill`, `rounded-bubble` | semantic roles (PUBLIC) — components reference these, `[data-shape]` presets remap them |
 | `--shadow-*` | `shadow-raised`, `shadow-overlay` | semantic names only; bare `shadow` is NOT generated (TW4 has no default scale and we don't define `--shadow`) |
 | `--ease-*` | `ease-productive-standard` | semantic names |
 | `--breakpoint-*` | `md:`, `lg:` | standard TW namespace |
@@ -105,6 +106,94 @@ See `MIGRATION.md#v0370--tailwind-4-css-first-migration` (root of this package).
 ---
+## Shape Presets & Radius Roles (v0.39+)
+Radius has TWO layers:
+1. **Primitive scale** — `--radius-ds-sm/md/lg/xl/2xl/full` (private; internal building blocks).
+2. **Semantic roles** — `--radius-control`, `--radius-control-inner`, `--radius-surface`, `--radius-overlay-sm/md/lg`, `--radius-pill`, `--radius-bubble`. Components reference roles. Consumers customize these.
+### Role token reference
+| Token                    | Default (px) | Utility class            | Used by |
+|--------------------------|--------------|--------------------------|---------|
+| `--radius-control`       | 6            | `rounded-control`        | Button, Input, Select, Combobox, Autocomplete, NumberInput, Toggle, ToggleGroup, Tabs trigger (contained), menu items, sidebar menu button, stepper, pagination, code block, InputOTP slot |
+| `--radius-control-inner` | 2            | `rounded-control-inner`  | Checkbox box, +/− buttons, close X buttons, focus rings on text links, small badges, color preset swatches, skeleton text bars, inline Code |
+| `--radius-surface`       | 10           | `rounded-surface`        | Card, StatCard, DataTableCard, Alert, Accordion trigger, FileUpload dropzone, Tabs list (contained) |
+| `--radius-overlay-sm`    | 6            | `rounded-overlay-sm`     | Tooltip, Toast, charts internal tooltip |
+| `--radius-overlay`       | 10           | `rounded-overlay`        | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, Select / Combobox / Autocomplete listbox, NavigationMenu viewport, DataTable bulk-actions toolbar, SplitButton dropdown |
+| `--radius-overlay-lg`    | 16           | `rounded-overlay-lg`     | Dialog, AlertDialog, Sheet (top corners), BottomSheet, ColorInput picker panel, ChatMessageInput wrapper, Sidebar inset variant |
+| `--radius-pill`          | 9999         | `rounded-pill`           | Badge, BadgeIndicator, StatusDot, Radio, Switch, Slider, Progress, Avatar circle, SegmentedControl item, ChatMessage reaction button, drag handles |
+| `--radius-bubble`        | 24           | `rounded-bubble`         | ChatMessage bubble |
+Bare `rounded-ds-*` and `rounded-full` are BANNED in components (enforced by pre-publish audit gate). Token-showcase stories (`forced-colors.stories.tsx`, `FoundationsShowcase.tsx`) are explicitly allowlisted.
+### Shape presets — `[data-shape]`
+Apply to `<html>`, app root, or any subtree. Three presets ship by default:
+| Preset | control / control-inner | surface | overlay-sm / overlay / overlay-lg | bubble | Feel |
+|---|---|---|---|---|---|
+| `sharp`              | 2 / 0   | 4   | 2 / 4 / 6     | 8  | Vercel / Linear / dev-tool |
+| `slightly-rounded` (default) | 6 / 2   | 10  | 6 / 10 / 16   | 24 | shadcn / Stripe / Notion sidebar |
+| `rounded`            | 10 / 4  | 16  | 10 / 16 / 24  | 32 | iOS / Notion content / consumer |
+```html
+<!-- Whole-app preset -->
+<html data-shape="sharp">
+<!-- Or scoped per subtree -->
+<div data-shape="rounded">...</div>
+```
+`--radius-pill` stays `9999px` in every preset by design — pill shapes are shape-by-meaning, not shape-by-style.
+### Per-token consumer overrides
+Override any role globally or scoped:
+```css
+:root { --radius-control: 4px; }                                /* tighten controls only */
+.checkout { --radius-control: 8px; --radius-surface: 20px; }    /* per-subtree */
+[data-shape="rounded"] .admin { --radius-control: 6px; }        /* extend a preset */
+```
+### Custom preset
+```css
+[data-shape="brand-soft"] {
+  --radius-control:        8px;
+  --radius-control-inner:  3px;
+  --radius-surface:        14px;
+  --radius-overlay-sm:     8px;
+  --radius-overlay:        14px;
+  --radius-overlay-lg:     20px;
+  --radius-pill:           9999px;
+  --radius-bubble:         28px;
+}
+```
+```html
+<html data-shape="brand-soft">
+```
+### Migration from `rounded-ds-*` / `rounded-full`
+```diff
+- className="rounded-ds-md ..."     → + className="rounded-control ..."
+- className="rounded-ds-lg ..."     → + className="rounded-surface ..."   /* card/panel context */
+- className="rounded-ds-lg ..."     → + className="rounded-overlay ..."   /* popover/dropdown context */
+- className="rounded-ds-xl ..."     → + className="rounded-overlay-lg ..."  /* dialog/sheet */
+- className="rounded-ds-2xl ..."    → + className="rounded-bubble ..."
+- className="rounded-ds-sm ..."     → + className="rounded-control-inner ..."
+- className="rounded-ds-full ..."   → + className="rounded-pill ..."
+- className="rounded-full ..."      → + className="rounded-pill ..."
+```
+Re-runnable codemod: `scripts/migrate-radius-roles.mjs` (dry-run by default, `--write` to apply).
+---
 ## Architecture Notes
 ### The Two-Axis Variant System

package/llms.txt CHANGED Viewed

@@ -28,6 +28,14 @@ Other recipes:
 The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/tree/main/packages/core/docs/recipes`. Consumer projects should also have an `AGENTS.md` at their root with the rules above pre-loaded — read that first if it exists.
+## NEW (v0.39.0)
+- **Shape presets (`[data-shape]`).** Set on `<html>` (or any subtree) to re-skin roundness across the whole UI. Three ship by default: `sharp` (technical, 2/4/6 px), `slightly-rounded` (default, 6/10/16 px), `rounded` (consumer, 10/16/24 px). Pill shapes (Badge, Switch, Radio, Avatar circle) stay pill regardless.
+- **Semantic radius role tokens.** New: `--radius-control`, `--radius-control-inner`, `--radius-surface`, `--radius-overlay-sm`, `--radius-overlay`, `--radius-overlay-lg`, `--radius-pill`, `--radius-bubble`. Consumers override any role globally or scoped — e.g. `:root { --radius-control: 4px; }`.
+- **Visual changes (no API breaks).** Button no longer scales radius with size (md/lg/xl/lg → all 6px); Input lg matches Button at same height; SegmentedControl items now actually pill; Tabs trigger (contained) matches Button; Tooltip belongs to its own `overlay-sm` tier with Toast; Menubar trigger matches DropdownMenu item; Autocomplete listbox matches Popover. If you preferred old chunky big controls, set `data-shape="rounded"` for v0.38-era feel.
+- **Pre-publish audit gate.** Components in `src/ui/` can no longer use `rounded-ds-*` or bare `rounded-full` — must use semantic roles. Composed/shell migration is v0.40.0 (gate scoped accordingly).
+- See `customize-brand.md` recipe for the full role token list and how to define your own preset.
 ## BREAKING CHANGES (v0.37.0 — Tailwind 4 CSS-first)
 **Setup migration only — component APIs unchanged.** See `MIGRATION.md` at the root of this package (or https://github.com/devalok-design/shilp-sutra/blob/main/MIGRATION.md#v0370--tailwind-4-css-first-migration) for the full guide.
@@ -45,7 +53,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 - **Node engines floor dropped.** No `engines.node` declared — use any Node 18+.
 - **New export `@devalok/shilp-sutra/css`** — primary consumer entry for TW4 setup.
 - **Source class hygiene:** `w-[--var]` → `w-(--var)`, `theme(spacing.N)` → literal, `bg-gradient-to-*` → `bg-linear-to-*`, bare `shadow` → explicit like `shadow-raised`. Codemod your own code; grep: `grep -rn 'w-\[--\|bg-gradient-to-\|theme(spacing' src/`.
-- **Tokens now expose TW4 namespaces.** Spacing is `--spacing-ds-*` (so `p-ds-03`, not `p-3`). Typography uses `--text-ds-*`, `--leading-ds-*`. Radius is unprefixed (`--radius`, `--radius-ds-*`). Z-layer utilities are custom-generated (`z-popover`, `z-dropdown`, etc.).
+- **Tokens now expose TW4 namespaces.** Spacing is `--spacing-ds-*` (so `p-ds-03`, not `p-3`). Typography uses `--text-ds-*`, `--leading-ds-*`. Radius has TWO layers: primitive scale (`--radius-ds-sm/md/lg/xl/2xl/full`) AND semantic roles (`--radius-control`, `--radius-surface`, `--radius-overlay-sm/md/lg`, `--radius-pill`, `--radius-bubble`). Components reference roles — consumers swap roles via `[data-shape]` presets or override individual tokens. Z-layer utilities are custom-generated (`z-popover`, `z-dropdown`, etc.).
 - **Dark mode variant:** `@custom-variant dark (&:where(.dark *))` — identical semantics to old `darkMode: 'class'`. `.dark` on `<html>` or `<body>` activates everything below.
 ## NEW (v0.36.0)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.38.0",
+  "version": "0.39.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>",
@@ -734,6 +734,7 @@
     "docs/recipes",
     "docs/rollback.md",
     "fonts",
+    "skill",
     "MIGRATION.md",
     "README.md",
     "llms.txt",

package/skill/README.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,144 @@
+---
+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 eight most common breakages.
+license: MIT
+metadata:
+  version: "0.38.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
+`references/customize-brand.md` covers token overrides — color ramps, radius, font swap, spacing scale, dark-mode mapping. 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 ADDED Viewed

@@ -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?'"