@devalok/shilp-sutra 0.37.1 → 0.39.0

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.37.1
+> 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
@@ -39,7 +39,7 @@ pnpm add sonner
 transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
 ```
 
-**Do NOT** import `@devalok/shilp-sutra/tailwind` in a `tailwind.config.ts`. That export is a deprecated no-op stub and logs a dev-mode `console.warn`. It is scheduled for removal in 0.38.
+**Do NOT** import `@devalok/shilp-sutra/tailwind`. That export was removed in 0.38.0. Use the CSS-first setup (`@import "tailwindcss"; @import "@devalok/shilp-sutra/css";`) — no `tailwind.config.ts` is required.
 
 ### Peer dependencies (0.37.0)
 
@@ -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
@@ -256,7 +345,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Category: ui
 
 ## Props
-    variant: "subtle" | "solid" | "outline" | "filled" (deprecated alias for "solid")
+    variant: "subtle" | "solid" | "outline"
     color: "info" | "success" | "warning" | "error" | "neutral"
     size: "sm" | "md" | "lg"
     title: string (optional)
@@ -287,6 +376,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) `variant="filled"` deprecated alias. Use `variant="solid"`.
+
 ### v0.31.0
 - **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
 
@@ -722,7 +814,6 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Props
     color: "info" | "success" | "warning" | "error" | "neutral"
     actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
-    action: ReactNode (DEPRECATED — use `actions` instead)
     onDismiss: () => void (optional, shows X button)
     children: ReactNode (message text)
 
@@ -749,6 +840,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated singular `action` prop. Use `actions={[...]}` (plural).
+
 ### v0.20.0
 - **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
 - **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)
@@ -2576,8 +2670,6 @@ const { size, stroke } = useIconContext()
     startSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
     endSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
     wrapperClassName: string (classes for the wrapper div — border, bg, ring)
-    startIcon: ReactNode (@deprecated — use startSection)
-    endIcon: ReactNode (@deprecated — use endSection)
     (plus all standard HTML input attributes except native "size")
 
 ## Types
@@ -2612,6 +2704,10 @@ const { size, stroke } = useIconContext()
 - Section type is auto-inferred: strings default to `'label'` (tinted bg + border), React elements default to `'icon'` (fixed-width centered). Override with `startSectionType`/`endSectionType`.
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated `startIcon` / `endIcon` props. Use `startSection` / `endSection`.
+- **Removed** (BREAKING) deprecated `inputVariants` export. Use `inputWrapperVariants`.
+
 ### v0.29.0
 - **Changed** v2 rewrite: container-first architecture with wrapper div holding focus ring
 - **Added** `xs` size (28px height)
@@ -3239,8 +3335,8 @@ const { size, stroke } = useIconContext()
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg" (REQUIRED) — also accepts legacy "small" | "medium" | "big"
-    variant: "filled" | "tonal" (REQUIRED)
+    size: "sm" | "md" | "lg"
+    variant: "default" | "solid"
     options: SegmentedControlOption[] (REQUIRED)
     selectedId: string (REQUIRED)
     onSelect: (id: string) => void (REQUIRED)
@@ -3248,14 +3344,18 @@ const { size, stroke } = useIconContext()
 
 ## Types
     SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
-    SegmentedControlSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'big' (legacy aliases)
-    SegmentedControlVariant = 'filled' | 'tonal'
+    SegmentedControlSize = 'sm' | 'md' | 'lg'
+    SegmentedControlVariant = 'default' | 'solid'
+
+## Defaults
+    size: "md"
+    variant: "default"
 
 ## Example
 ```jsx
 <SegmentedControl
   size="md"
-  variant="tonal"
+  variant="default"
   options={[
     { id: 'list', text: 'List' },
     { id: 'grid', text: 'Grid' },
@@ -3278,11 +3378,14 @@ const { size, stroke } = useIconContext()
 - Use Tabs (not SegmentedControl) when you need associated content panels per option
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated `variant="accent"` alias. Use `variant="solid"`.
+
 ### v0.18.0
 - **Fixed** `bg-interactive` changed to `bg-accent-9`, `bg-field` changed to `bg-surface-3` (OKLCH migration)
 
 ### v0.4.2
-- **Changed** (BREAKING) `color` prop renamed to `variant` (values `filled`/`tonal` unchanged)
+- **Changed** (BREAKING) `color` prop renamed to `variant`
 
 ### v0.1.1
 - **Fixed** `tabIndex={0}` changed to `tabIndex={-1}` on tablist wrapper — fixes double-focus keyboard navigation bug
@@ -5932,47 +6035,6 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
 
 ### v0.1.0
 - **Added** Initial release
-# ResponsiveOverlay
-
-- Import: @devalok/shilp-sutra/composed/responsive-overlay
-- Server-safe: No
-- Category: composed
-
-## Props
-    open: boolean
-    onOpenChange: (open: boolean) => void
-    title: string
-    description: string
-    breakpoint: "sm" | "md" (below this renders as bottom Sheet; above as Dialog)
-    children: ReactNode
-    className: string
-
-## Defaults
-    breakpoint="md"
-
-## Example
-```jsx
-<ResponsiveOverlay
-  open={open}
-  onOpenChange={setOpen}
-  title="Edit task"
-  description="Update the task details"
->
-  <TaskForm />
-</ResponsiveOverlay>
-```
-
-## Composability
-- **One component, two containers.** Above `breakpoint`: centered Dialog. Below: bottom-anchored Sheet. Same content slot, different surface treatment per viewport.
-- **Standard controlled model** — `open` + `onOpenChange` (same shape as Dialog/Sheet).
-- **title + description pattern** — matches Dialog/Sheet's requirement for an accessible heading. Omit both only when the surrounding context makes the purpose obvious (rare).
-- **SSR caveat:** `window.matchMedia` reads on mount — initial SSR render defaults to desktop (Dialog). Hydration flips to Sheet on mobile. Acceptable for most flows; visible layout shift on low-spec devices.
-- **When to use:** Any modal that needs to behave differently on mobile (edit dialogs, filter panels, quick-action menus). For always-the-same behavior, use Dialog or Sheet directly.
-
-## Gotchas
-- Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
-- Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration
-- Title and description are optional; if omitted, no header is rendered in either mode
 # RichChatInput
 
 - Import: @devalok/shilp-sutra/composed/rich-chat-input

package/llms.txt

@@ -4,6 +4,38 @@
 > Built on the same primitives as shadcn/ui but with key API differences.
 > Read this file BEFORE writing any UI code. Do NOT guess from shadcn/ui knowledge.
 
+## QUICK SETUP (AI agents — start here)
+
+If you are setting up shilp-sutra in a consumer project for the first time, **do not improvise**. Use a recipe.
+
+When the package is installed, recipes ship at `node_modules/@devalok/shilp-sutra/docs/recipes/`. Pick one based on the consumer's framework:
+
+| Framework | Recipe file |
+|---|---|
+| Next.js (App Router) | `install-next-app-router.md` |
+| Next.js (Pages Router) | `install-next-pages.md` |
+| Vite + React | `install-vite.md` |
+| Astro | `install-astro.md` |
+| Remix | `install-remix.md` |
+| TanStack Start | `install-tanstack-start.md` |
+| Other React + Tailwind | start from `install-vite.md` and adapt |
+
+Other recipes:
+
+- `customize-brand.md` — token override cookbook (color, radius, font, spacing)
+- `server-components.md` — RSC-safety matrix and import patterns
+- `troubleshoot.md` — decision tree for the 8 most common breakages
+
+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.
@@ -13,7 +45,7 @@
   @import "tailwindcss";
   @import "@devalok/shilp-sutra/css";
   ```
-  The old `./tailwind` export is a deprecated no-op stub; importing it logs a dev-mode `console.warn` and is scheduled for removal in 0.38.
+  The `./tailwind` export has been removed in 0.38. Delete any `tailwind.config.ts` that referenced the preset and switch to the CSS import above.
 - **framer-motion is now a required peer dep.** Previously bundled. Install: `pnpm add framer-motion`. Module-scoped React contexts (MotionConfig, LayoutGroup, AnimatePresence) must be single-copy — the peer declaration forces pnpm to dedupe against the consumer's version.
 - **sonner is now an optional peer dep.** Install only if you render `<Toaster />`: `pnpm add sonner`.
 - **tailwindcss peer tightened to `^4.0.0`.** No more `^3.4.0 || ^4.0.0`.
@@ -21,7 +53,7 @@
 - **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)
@@ -48,8 +80,6 @@
 - **MessageList:** `isLoadingMore` renamed to `loadingMore`.
 - **AppCommandPalette:** Default Karm routes removed. Use `CommandRegistryProvider` for page registration. `SearchResult` type adds optional `href` field.
 - **NumberInput:** Shape changed from pill to rounded rectangle.
-- **Alert:** `variant="filled"` deprecated → use `"solid"` (alias still works).
-- **SegmentedControl:** `variant="accent"` deprecated → use `"solid"` (alias still works).
 - **Dependencies:** `@floating-ui/dom`, `@tiptap/*`, `prosemirror-state` moved to devDeps (bundled; consumers no longer install them).
 
 ## NEW (v0.35.0)
@@ -100,14 +130,13 @@
 
 - **Button:** `variant="default"` removed (use `"solid"`), `variant="destructive"` removed (use `variant="solid" color="error"`), `color="default"` removed (use `"accent"`).
 - **Chip:** Removed. Use `Badge` instead.
-- **SegmentedControl:** Rewritten. `variant="filled"` → `"accent"`, `variant="tonal"` → `"default"`. `SegmentedControlItem` no longer exported. Legacy sizes `small`/`medium`/`big` removed.
+- **SegmentedControl:** Rewritten. Variants are `"default"` (white pill) and `"solid"` (brand pill). `SegmentedControlItem` no longer exported.
 - **TopBar:** Now renders as `<header>` (was `<div>`).
 - **Sidebar:** Now renders as `<aside>` (was `<div>`).
 - **InfoBlock:** `role="status"` (was `role="alert"`).
 - **Border tokens:** One step darker system-wide.
 - **Dark mode button text:** Pure white `neutral-0` (#fff) on brand-colored buttons.
 - **BottomNavbar:** Bottom padding is now `pb-safe` (safe-area-inset).
-- **ResponsiveOverlay:** Deprecated. Use Dialog or Sheet directly.
 - **iOS inputs:** Forced to `font-size: max(16px, 1em)` on mobile via preset.
 
 ## CHANGES (v0.32.0)
@@ -124,7 +153,7 @@
 - **DataTable `mobileView="card"`** — Rows render as stacked cards below 640px. First column = card title, rest = label-value pairs.
 - **DataTable `aria-sort`** — Sortable column headers include `aria-sort`.
 - **Charts `ariaLabel` prop** — Configurable screen reader label on all chart components.
-- **SegmentedControl** — Redesigned: `variant="default"` (white pill + shadow-sm) | `variant="accent"` (brand pill). Inset radius, snappy spring animation.
+- **SegmentedControl** — Redesigned: `variant="default"` (white pill + shadow-raised) | `variant="solid"` (brand pill). Inset radius, snappy spring animation.
 - **`--shadow-kbd` token** — Keyboard shortcut badge shadow. Use `shadow-kbd` utility.
 - **Checkbox/Radio `size` prop** — `sm | md (default) | lg`.
 
@@ -409,11 +438,8 @@ import { toast } from '@devalok/shilp-sutra/ui/toast'
 // Hooks:
 import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
 
-// CSS tokens (import once at app root):
-import '@devalok/shilp-sutra/tokens'
-
-// Tailwind preset (in tailwind.config):
-import shilpSutra from '@devalok/shilp-sutra/tailwind'
+// CSS tokens (import once at app root — already included in /css):
+import '@devalok/shilp-sutra/css'
 
 ## CRITICAL: Differences from shadcn/ui
 
@@ -456,7 +482,7 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
 - SplitButton: [Action | ▼] button with dropdown. Props: variant(solid|soft|outline), color, size(xs|sm|md|icon-xs|icon-sm|icon-md), triggerSide(left|right, default right), triggerWidth?(number|string), placement?(Floating UI Placement, default top-end), dropdownContent(ReactNode), open?, onOpenChange?, dropdownLabel?, dropdownIcon?. ARIA: role="group", aria-haspopup="menu", aria-expanded.
 - ButtonGroup: Visually merges adjacent Buttons. Props: variant, color, size, disabled (propagates), orientation(horizontal|vertical), attached(true|false, default true), fullWidth. Compound pattern: Button reads position from context, applies radius + border-removal inline. Tonal dividers for solid/soft/ghost. Focus z-index isolation.
 - Icon: `<Icon icon={IconPlus} />` — context-aware wrapper for Tabler icons. Size tiers: xs(14px) sm(16px) md(18px) lg(20px) xl(24px) 2xl(32px). Default: md. Stroke: light(1.5) regular(2) bold(2.5). Default: regular. Scales per size tier. Reads size from parent Button/IconGroup via IconContext. Explicit props override. Accessibility: aria-hidden by default. Pass label="Add item" for accessible icons. Animation: animate="spin|pulse|bounce|draw". `draw` renders SVG path-draw animation (check/X icons draw progressively via pathLength; other icons fall back to static). State machine: state="idle|loading|success|error". Button integration: startIcon={<Icon icon={IconPlus} />} (NOT raw <IconPlus />). IconGroup: <IconGroup size="sm" gap="tight"> for toolbar patterns.
-- Input: size(xs|sm|md|lg) state(InputState) + startSection(ReactNode), endSection(ReactNode), startSectionClickable(bool), endSectionClickable(bool), startSectionType('icon'|'label'), endSectionType('icon'|'label'), wrapperClassName(string). Container-level focus ring wraps input + sections as one unit. Sections are pointer-events-none by default; use *SectionClickable for interactive content (clear buttons, toggles). Section type auto-inferred: strings→'label' (tinted bg + border separator), React elements→'icon' (fixed-width centered). Override with *SectionType. Flexbox section layout. Icons auto-size via IconProvider per input size. className targets <input>, wrapperClassName targets wrapper div. Deprecated aliases: startIcon→startSection, endIcon→endSection, inputVariants→inputWrapperVariants. Type: InputState = 'default' | 'error' | 'warning' | 'success'
+- Input: size(xs|sm|md|lg) state(InputState) + startSection(ReactNode), endSection(ReactNode), startSectionClickable(bool), endSectionClickable(bool), startSectionType('icon'|'label'), endSectionType('icon'|'label'), wrapperClassName(string). Container-level focus ring wraps input + sections as one unit. Sections are pointer-events-none by default; use *SectionClickable for interactive content (clear buttons, toggles). Section type auto-inferred: strings→'label' (tinted bg + border separator), React elements→'icon' (fixed-width centered). Override with *SectionType. Flexbox section layout. Icons auto-size via IconProvider per input size. className targets <input>, wrapperClassName targets wrapper div. Type: InputState = 'default' | 'error' | 'warning' | 'success'
 - SearchInput: size(xs|sm|md|lg) + loading, onClear. Delegates to Input v2 sections internally.
 - NumberInput: value + onValueChange, min, max, step (controlled only)
 - Textarea: size(xs|sm|md|lg) state(default|error|warning|success)
@@ -467,12 +493,12 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
 - Select > SelectTrigger(size: xs|sm|md|lg) > SelectValue; SelectContent > SelectItem(value)
 - Toggle: variant(default|outline) size(sm|md|lg)
 - ToggleGroup > ToggleGroupItem (variant/size propagate from root)
-- SegmentedControl > SegmentedControlItem: variant(filled|tonal) size(sm|md|lg). Types: SegmentedControlOption = { id, text, icon? }, SegmentedControlSize = 'sm' | 'md' | 'lg', SegmentedControlVariant = 'filled' | 'tonal'
+- SegmentedControl: variant(default|solid) size(sm|md|lg) options selectedId onSelect. Types: SegmentedControlOption = { id, text, icon? }, SegmentedControlSize = 'sm' | 'md' | 'lg', SegmentedControlVariant = 'default' | 'solid'
 - Slider: standard Radix slider
 
 ### Feedback & Notifications
-- Alert: variant(subtle|filled|outline) color(info|success|warning|error|neutral) + title, onDismiss
-- Banner: color(info|success|warning|error|neutral) + actions?(ReactNode), onDismiss. `action` (singular) deprecated, use `actions`. Mobile flex-wrap for multiple buttons.
+- Alert: variant(subtle|solid|outline) color(info|success|warning|error|neutral) size(sm|md|lg) + title, onDismiss
+- Banner: color(info|success|warning|error|neutral) + actions?(ReactNode), onDismiss. Mobile flex-wrap for multiple buttons.
 - Toast: imperative API via toast.success/error/warning/info/loading/message/undo/promise/upload/custom — REQUIRES <Toaster> at layout root
 - Spinner: size(sm|md|lg) — renders with role="status"
 - Progress: track size(sm|md|lg), indicator color(default|success|warning|error), autoColor(boolean, auto-shifts color by value: 0-59=default, 60-84=warning, 85-100=success, >100=error)
@@ -568,7 +594,6 @@ Import: `@devalok/shilp-sutra/ui/chat`
 - BulkActionBar: show, count, onClearSelection, actions[{label,icon?,onClick,color?,disabled?}]. Fixed bottom floating bar for multi-select contexts.
 - DeadlineIndicator: deadline(Date|string), warningThreshold?(1440min), criticalThreshold?(240min), format(relative|absolute), showIcon. Color transitions: green→yellow→red→overdue.
 - MasterDetail: selected, onBack, masterWidth, breakpoint(sm|md|lg). Compound: MasterDetail.List, MasterDetail.Detail, MasterDetail.ListItem(active). Desktop=grid, mobile=stacked with back button.
-- ResponsiveOverlay: open, onOpenChange, title, description, breakpoint(sm|md). Dialog on desktop, bottom Sheet on mobile.
 - MarkdownViewer: content(string), compact?, allowHtml?(false), linkTarget?('_blank'). Renders markdown with design system tokens.
 - EmojiPicker: onSelect(emoji), set?(native|apple|google|twitter|facebook), theme(auto|light|dark). EmojiPickerPopover wraps in Popover. Lazy-loads emoji-mart with set-specific data.
 - EmojiNode: TipTap inline atom node for spritesheet emoji rendering. Attrs: id, native, set, x, y. Use createEmojiSuggestion(set) to wire :shortcode: autocomplete. Export: EmojiNode, EmojiNodeAttrs, createEmojiSuggestion.

package/package.json

@@ -1,13 +1,44 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.37.1",
-  "description": "Devalok Design System — tokens, components, and patterns for Next.js",
+  "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>",
+  "homepage": "https://devalok-design.github.io/shilp-sutra/",
   "repository": {
     "type": "git",
     "url": "https://github.com/devalok-design/shilp-sutra",
     "directory": "packages/core"
   },
+  "bugs": {
+    "url": "https://github.com/devalok-design/shilp-sutra/issues"
+  },
+  "keywords": [
+    "react",
+    "design-system",
+    "components",
+    "ui",
+    "ui-library",
+    "tailwindcss",
+    "tailwind-v4",
+    "typescript",
+    "accessible",
+    "a11y",
+    "wcag",
+    "radix-ui",
+    "headless",
+    "cva",
+    "design-tokens",
+    "oklch",
+    "framer-motion",
+    "dark-mode",
+    "nextjs",
+    "vite",
+    "astro",
+    "remix",
+    "ai-agent",
+    "llms-txt"
+  ],
   "type": "module",
   "main": "./dist/ui/index.js",
   "module": "./dist/ui/index.js",
@@ -554,11 +585,6 @@
       "import": "./dist/composed/status-badge.js",
       "default": "./dist/composed/status-badge.js"
     },
-    "./composed/responsive-overlay": {
-      "types": "./dist/composed/responsive-overlay.d.ts",
-      "import": "./dist/composed/responsive-overlay.js",
-      "default": "./dist/composed/responsive-overlay.js"
-    },
     "./composed/schedule-view": {
       "types": "./dist/composed/schedule-view.d.ts",
       "import": "./dist/composed/schedule-view.js",
@@ -629,23 +655,6 @@
       "import": "./dist/hooks/use-mobile.js",
       "default": "./dist/hooks/use-mobile.js"
     },
-    "./hooks/use-toast": {
-      "types": "./dist/hooks/use-toast.d.ts",
-      "import": "./dist/hooks/use-toast.js",
-      "default": "./dist/hooks/use-toast.js"
-    },
-    "./tailwind": {
-      "types": "./dist/tailwind/index.d.ts",
-      "require": "./dist/tailwind/index.cjs",
-      "import": "./dist/tailwind/index.js",
-      "default": "./dist/tailwind/index.js"
-    },
-    "./tailwind/preset": {
-      "types": "./dist/tailwind/preset.d.ts",
-      "require": "./dist/tailwind/index.cjs",
-      "import": "./dist/tailwind/preset.js",
-      "default": "./dist/tailwind/preset.js"
-    },
     "./utils": {
       "types": "./dist/ui/lib/utils.d.ts",
       "import": "./dist/ui/lib/utils.js",
@@ -722,8 +731,10 @@
   "files": [
     "dist",
     "docs/components",
+    "docs/recipes",
     "docs/rollback.md",
     "fonts",
+    "skill",
     "MIGRATION.md",
     "README.md",
     "llms.txt",
@@ -830,19 +841,19 @@
     "@emoji-mart/react": "^1.1.1",
     "@floating-ui/dom": "^1.7.6",
     "@floating-ui/react-dom": "^2.1.8",
-    "@tabler/icons-react": "^3.41.1",
+    "@tabler/icons-react": "^3.42.0",
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.13.23",
-    "@tiptap/core": "^3.22.3",
-    "@tiptap/extension-highlight": "^3.22.3",
-    "@tiptap/extension-image": "^3.22.3",
-    "@tiptap/extension-list": "^3.22.3",
-    "@tiptap/extension-mention": "^3.22.3",
-    "@tiptap/extension-text-align": "^3.22.3",
-    "@tiptap/extensions": "^3.22.3",
-    "@tiptap/react": "^3.22.3",
-    "@tiptap/starter-kit": "^3.22.3",
-    "@tiptap/suggestion": "^3.22.3",
+    "@tiptap/core": "^3.22.5",
+    "@tiptap/extension-highlight": "^3.22.5",
+    "@tiptap/extension-image": "^3.22.5",
+    "@tiptap/extension-list": "^3.22.5",
+    "@tiptap/extension-mention": "^3.22.5",
+    "@tiptap/extension-text-align": "^3.22.5",
+    "@tiptap/extensions": "^3.22.5",
+    "@tiptap/react": "^3.22.5",
+    "@tiptap/starter-kit": "^3.22.5",
+    "@tiptap/suggestion": "^3.22.5",
     "@types/react-syntax-highlighter": "^15.5.13",
     "aria-hidden": "^1.2.6",
     "class-variance-authority": "^0.7.1",

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>