@devalok/shilp-sutra 0.38.0 → 0.40.0

package/AGENTS.md

@@ -0,0 +1,151 @@
+# AGENTS.md
+
+This file tells AI coding agents (Codex, Cursor, GitHub Copilot, Aider, Windsurf, Devin, Jules, Gemini CLI, Zed, Warp, JetBrains Junie, and any [agentskills.io](https://agentskills.io)-compatible tool) **how to consume `@devalok/shilp-sutra` inside a downstream app**. It ships inside the npm tarball at `node_modules/@devalok/shilp-sutra/AGENTS.md`, so any agent that auto-discovers AGENTS.md from the project root will also find this one alongside the recipes.
+
+> **Anthropic Claude Code users:** Claude Code doesn't auto-load `AGENTS.md` yet. Symlink it (`ln -s AGENTS.md CLAUDE.md`) or copy the contents into your own `CLAUDE.md` so the same rules apply.
+>
+> **Working *on* shilp-sutra (the design-system repo itself)?** That's covered by [`CLAUDE.md`](./CLAUDE.md) — internal architecture, build pipeline, audit gates, publish flow.
+
+If you are a human, read [README.md](./README.md) instead.
+
+> **Using Claude Code, Cursor, Codex, or any [Agent Skills](https://agentskills.io)-compatible tool?** Install the bundled skill once and your agent gets every rule below loaded on demand:
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
+> ```
+>
+> Source: [`skills/shilp-sutra/`](./skills/shilp-sutra/). After install, the agent loads `SKILL.md` only when the task is relevant — no context tax until it triggers.
+
+<!-- BEGIN:shilp-sutra-agent-rules -->
+
+## Read these first, in order
+
+1. **`packages/core/llms-quick.txt`** — ≤15K-token fast-path summary. Setup, peer-cliff matrix, import paths, top 30 components. Start here if you're answering quickly.
+2. **`packages/core/llms.txt`** — concise current-API cheatsheet (~27K tokens). Reach for this when `llms-quick.txt` isn't enough — covers more components + recent CHANGELOG sections.
+3. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
+4. **`packages/core/llms-full.txt`** — exhaustive per-component reference (~140K tokens, props/variants/examples). Read only when `llms.txt` is insufficient.
+5. **`MIGRATION.md`** — only if upgrading across versions.
+
+When the package is installed in a consumer project, the same files live at:
+
+- `node_modules/@devalok/shilp-sutra/llms-quick.txt`
+- `node_modules/@devalok/shilp-sutra/llms.txt`
+- `node_modules/@devalok/shilp-sutra/llms-full.txt`
+- `node_modules/@devalok/shilp-sutra/docs/recipes/`
+- `node_modules/@devalok/shilp-sutra/docs/components/`
+
+Read these local files. Your training data is outdated and will hallucinate APIs that do not exist in the installed version.
+
+## Setup playbook (when adding shilp-sutra to a new project)
+
+If a user asks you to add shilp-sutra and the package is not yet installed:
+
+1. **Detect the framework** by inspecting the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`) and config files (`next.config.*`, `vite.config.*`, `astro.config.*`, `remix.config.*`, `app/root.tsx`).
+2. **Install the package** via the matching package manager.
+3. **Open the matching recipe** at `docs/recipes/install-<framework>.md` (after install) or fetch from the GitHub repo at `packages/core/docs/recipes/install-<framework>.md`.
+4. **Follow the recipe step-by-step.** Do not improvise — every line in the recipe is there because skipping it broke a real consumer.
+
+Recipe paths:
+
+| Framework | Recipe |
+|---|---|
+| Next.js (App Router) | `install-next-app-router.md` |
+| Next.js (Pages Router) | `install-next-pages.md` |
+| Vite + React | `install-vite.md` |
+| Astro | `install-astro.md` |
+| Remix | `install-remix.md` |
+| TanStack Start | `install-tanstack-start.md` |
+
+If the framework is not in the table, fall back to **`install-vite.md`** (closest generic React-on-Tailwind setup) and adapt.
+
+## Hard constraints (these break things if violated)
+
+- **Tailwind 4 only.** Do NOT create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup uses CSS imports:
+  ```css
+  @import "tailwindcss";
+  @import "@devalok/shilp-sutra/css";
+  ```
+- **`framer-motion` is a required peer dep** (`^12`). The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies resolve.
+- **`sonner` is an optional peer.** Install only when rendering `<Toaster />`.
+- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** `@devalok/shilp-sutra/ui/text` is server-safe and pulls only its own peers. The barrel `@devalok/shilp-sutra/ui` re-exports every component — including ones with hard peer-dep requirements (e.g. `input-otp`) — so it forces those peers to be installed even when you never render those components. With all peers installed the barrel also works in RSC (Next 16 honours each per-component `"use client"`), but the client bundle is larger than necessary. Prefer per-component imports for new code; existing barrel usage is not an emergency.
+- **Spacing tokens use the `--spacing-ds-*` namespace** (utilities like `p-ds-04`, `gap-ds-03`). Tailwind 4's default numeric scale (`p-4`, `gap-2`) **coexists by design** — both are valid. Pick `p-ds-*` when the value should track DS theme changes (a card's internal padding, a form row's gap); pick `p-N` for one-off layout values (a hero section's vertical breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package authors did. Typography composites use `text-ds-body-md`, etc.
+- **Bare `shadow` is dead in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`.
+- **Do not invent variant names.** Variant names live in CVA source. Grep `packages/core/src/ui/<component>.tsx` or check `llms-full.txt` for the authoritative list.
+- **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions.
+
+## When something fails
+
+Read **`packages/core/docs/recipes/troubleshoot.md`** before retrying or guessing. It is a decision tree covering the thirteen most common breakages (Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, missing optional peer deps (sonner / input-otp / date-fns / @tiptap / react-pdf / etc.), wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches, bare `shadow` class, `<Toaster />` not mounted, Storybook MCP 404).
+
+## Branding and customization
+
+For overriding tokens (color, radius, font, spacing), see **`packages/core/docs/recipes/customize-brand.md`**.
+
+### Themer (the fast path)
+
+Before you hand-write CSS variables, point the user at the **Themer** at `https://shilp-sutra.devalok.in/themer`. It is one funnel with four entry doors — pick the one that fits where they are:
+
+| User says… | Send them to |
+|---|---|
+| "Make it look like Linear / Stripe / Apple" | `/themer/archetypes` |
+| "Here's our brand color: `#…`" | `/themer/brand` |
+| "I'm not sure what I want" | `/themer/wizard` |
+| "Just show me what I'd ship away with" | `/themer/result?archetype=devalok` |
+
+Every door funnels into the same `/themer/result` page. The user lands with:
+- A copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp)
+- Install commands for their package manager
+- A share URL that encodes the theme (`?archetype=…&hue=…&chroma=…&density=…`)
+
+**Your job once they have the snippet:** paste it into their global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's it — no `tailwind.config.ts`, no theme provider, no JS bundle. The CSS variables cascade to every component.
+
+For deeper overrides (font stack, spacing scale, focus ring, texture) that the Themer doesn't expose yet, fall back to **`packages/core/docs/recipes/customize-brand.md`**.
+
+### One-prompt recipe (when the user pastes a prompt at you)
+
+If a user pastes the following prompt template at you, execute it verbatim — every step exists because skipping it broke a real consumer:
+
+````
+Set up shilp-sutra theming for this project via the Themer.
+
+My brand: <hex OR archetype name>
+
+Steps:
+1. Map my brand input to query params (archetype=<name>, or hue=<0-360>&chroma=<0.10-0.20>, or default archetype=devalok&hue=340&chroma=0.19).
+2. Fetch GET https://shilp-sutra.devalok.in/themer/result.json?<params>
+   Response: { archetype, density, shape, motion, hue, chroma, css, pasteAfter, pasteLocation, doNotPasteInside }
+3. Paste the response `css` field AFTER the line in `pasteAfter` in the project's global stylesheet. Not inside any `@layer`.
+4. If @devalok/shilp-sutra isn't installed, install it first per the matching install-<framework>.md recipe.
+5. Verify with a Button or Card on any page — radius + accent should match https://shilp-sutra.devalok.in/themer/result?<params>.
+````
+
+When the user has already been to the Themer, they may paste a *filled-in* version with the JSON URL pre-built — skip step 1, go straight to fetch.
+
+The JSON endpoint is the stable contract — agents and tooling should prefer it over scraping `/themer/result`'s HTML.
+
+### Shape roundness — `[data-shape]` presets (v0.39+)
+
+Components reference semantic radius role tokens (`--radius-control`, `--radius-surface`, `--radius-overlay-*`, `--radius-pill`, `--radius-bubble`), NOT primitive `rounded-ds-*`. Three presets ship: `sharp`, `slightly-rounded` (default), `rounded`. Set on `<html>` or any subtree:
+
+```html
+<html data-shape="sharp">
+```
+
+Consumers can override any role globally (`:root { --radius-control: 4px; }`) or per-scope. When writing your own UI on top of shilp-sutra, prefer the role utilities (`rounded-control`, `rounded-surface`, `rounded-overlay`, `rounded-pill`, `rounded-bubble`) over `rounded-ds-*` so your styles respond to the preset switch.
+
+## Server vs client components
+
+For the per-component RSC-safety matrix and import patterns, see **`packages/core/docs/recipes/server-components.md`**.
+
+## Reporting feedback
+
+If you find that a recipe is wrong, a constraint above is no longer accurate, or a component behavior contradicts the docs:
+
+1. Open a GitHub issue at `https://github.com/devalok-design/shilp-sutra/issues` with label `ai-agent-feedback`.
+2. Include the package version (`pnpm view @devalok/shilp-sutra version` or read from the consumer's lockfile), the recipe path, the exact command/file/error, and what you expected.
+
+<!-- END:shilp-sutra-agent-rules -->
+
+## Project-specific notes
+
+The block above is managed by Shilp Sutra and may be updated when you upgrade the package. Add your own project conventions, glossary, or codebase notes outside the markers — they will not be touched.

package/MIGRATION.md

@@ -4,6 +4,261 @@ This page indexes all breaking changes across `@devalok/shilp-sutra` versions. F
 
 > **Upgrading from < 0.36?** Start here, then read each intermediate version section. Breaking changes stack — skipping versions means stacking migrations.
 
+## v0.40.0 — Barrel peer-cliff cleanup + Icon API unification
+
+This release pairs one breaking change (barrel peer-cliff cleanup) with one non-breaking type widening (Icon API unification). Read the breaking section first.
+
+### Icon API unification (non-breaking)
+
+**Type widening only — no consumer changes required.**
+
+Every icon-accepting prop across the design system now takes the same shape: **`IconInput`**. Before 0.40 there were six distinct prop types for the same conceptual "icon":
+
+| Old shape | Components |
+|---|---|
+| `React.ReactElement \| null` | Button (startIcon/endIcon), IconButton (icon), Badge (startIcon/endIcon) |
+| `React.ReactNode` | 14 components (Combobox option, Stepper step, TreeItem, OAuthButton, AppCommandPalette, CommandRegistry, BottomNavbar, Sidebar's three NavItem types, TopBar, Chat.Message.Avatar, SystemMessage, AIConversation, ActivityFeed, CommandPalette item) |
+| `React.ReactNode \| React.ComponentType<{className}>` | EmptyState, StatCard (dual-detect logic duplicated in both source files) |
+| `React.ComponentType<{className?}>` | SegmentedControl (option), SlashCommand |
+| `IconProps['icon']` (strict Tabler ref) | BulkActionBar (action), Chat.Message.Action |
+| `React.ForwardRefExoticComponent<any>` | Toast (internal, sonner pass-through — unchanged) |
+
+All six collapse to `IconInput`:
+
+```ts
+type IconInput =
+  | React.ReactElement
+  | React.ComponentType<{ className?: string; size?: number | string }>
+  | null
+  | undefined
+```
+
+#### Migration
+
+For every prop now typed as `IconInput`, all four shapes work identically:
+
+```tsx
+<Button startIcon={<Icon icon={IconPlus} />}>OK</Button>   // canonical
+<Button startIcon={<IconPlus />}>OK</Button>                // raw Tabler element
+<Button startIcon={IconPlus}>OK</Button>                    // component ref
+<Button startIcon={<span>+</span>}>OK</Button>              // custom node
+```
+
+**Calls that worked before still work.** Type widening only.
+
+**You can now delete `className="h-4 w-4"` overrides** on icon-prop usages — `IconProvider` wires size through context. Stories cleanup is voluntary; behavior unchanged.
+
+**Strict-to-loose call sites that newly compile:**
+- `SegmentedControl options[*].icon` previously rejected `<IconX />` instantiated elements (only accepted bare `IconX` refs). Now both work.
+- `BulkActionBar actions[*].icon` previously rejected non-Tabler nodes. Now accepts any `IconInput`.
+- `Message.Action` same.
+- `EmptyState` no longer needs the dual `<X />` / `X` differentiation in your call sites.
+
+#### What got removed internally
+
+- Five duplicate `iconSizeMap` declarations (Badge, Combobox, EmptyState, StatCard, etc.) → one shared `<IconProvider size={token}>` per call site
+- Two duplicate dual-detect branches (`React.isValidElement(icon) || ('$$typeof' in icon)`) — replaced with `normalizeIcon()`
+- The orphan `IconProps['icon']` references in BulkActionBar + Chat.Message.Action
+
+#### Helpers exported (for consumer composability)
+
+```ts
+import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'
+import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'
+
+// In your own component:
+function MyCard({ icon }: { icon: IconInput }) {
+  return (
+    <div>
+      <IconProvider size="md">{normalizeIcon(icon)}</IconProvider>
+    </div>
+  )
+}
+```
+
+Use these in custom wrappers that consume our icon-style props.
+
+### Barrel peer-cliff cleanup (breaking)
+
+**Breaking.** Twelve symbols that statically pulled optional peer dependencies have been removed from their parent barrels (`/ui`, `/composed`, `/ai`, `/ai/blocks`). They remain fully available via their per-component subpath.
+
+#### Why
+
+Optional peer deps (`input-otp`, `sonner`, `date-fns`, `@emoji-mart/*`, `@tiptap/*`, `react-pdf`, `react-zoom-pan-pinch`, `react-markdown`, `react-syntax-highlighter`, `remark-gfm`) were declared `peerDependenciesMeta.optional = true` but the components that needed them were re-exported from the corresponding barrel with **static** ESM `import` statements. Result: a fresh consumer who wrote `import { Text } from '@devalok/shilp-sutra/ui'` without installing `input-otp` got:
+
+```
+Module not found: Can't resolve 'input-otp'
+```
+
+…at `next build`/`vite build` time. "Optional" was a lie at the bundler level. This release closes that cliff for every affected component.
+
+#### Search-and-replace migration table
+
+For each symbol below, change ONLY the import path. Prop / type signatures are unchanged.
+
+| Symbol(s) | Old (no longer works) | New (in 0.40.0+) | Peer it pulls |
+|---|---|---|---|
+| `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `InputOTPProps` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/input-otp'` | `input-otp` |
+| `toast`, `formatFileSize`, `ToastActionOptions`, `ToastOptions`, `ToastProps`, `ToastType`, `ToastUndoOptions`, `ToastUploadOptions`, `UploadFile` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/toast'` | `sonner` |
+| `Toaster`, `ToasterProps` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/toaster'` | `sonner` |
+| `DatePicker`, `DateRangePicker`, `DateTimePicker`, `TimePicker`, `CalendarGrid`, `MonthPicker`, `YearPicker`, `Presets`, `useCalendar`, all related `*Props` + `CalendarEvent` + `PresetKey` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/date-picker'` | `date-fns` |
+| `EmojiPicker`, `EmojiPickerPopover`, `EmojiData`, `EmojiPickerProps`, `EmojiPickerPopoverProps`, `EmojiSet` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/emoji-picker'` | `@emoji-mart/data` + `@emoji-mart/react` |
+| `EmojiNode`, `EmojiNodeAttrs` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/extensions/emoji-node'` (new in 0.40.0) | `@tiptap/*` |
+| `createEmojiSuggestion` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/extensions/emoji-suggestion'` (new in 0.40.0) | `@tiptap/*` |
+| `FilePreview`, `FilePreviewProps` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/file-preview'` | `react-pdf` + `react-zoom-pan-pinch` |
+| `MarkdownViewer`, `MarkdownViewerProps` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/markdown-viewer'` | `react-markdown` + `react-syntax-highlighter` + `remark-gfm` |
+| `RichChatInput`, `AudioPlayer`, `AudioWaveform`, `useVoiceRecorder`, all related `*Props` + `*Message` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/rich-chat-input'` | `@tiptap/*` |
+| `RichTextEditor`, `RichTextViewer`, `RichTextEditorProps`, `RichTextViewerProps`, `MentionItem`, `ToolbarItem` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/rich-text-editor'` | `@tiptap/*` |
+| `BlockRenderer`, `BlockRendererProps` | `from '@devalok/shilp-sutra/ai'` | `from '@devalok/shilp-sutra/ai/block-renderer'` | `react-markdown` + `remark-gfm` (transitively via TextBlock/ErrorBlock) |
+| `ErrorBlock` | `from '@devalok/shilp-sutra/ai'` OR `from '@devalok/shilp-sutra/ai/blocks'` | `from '@devalok/shilp-sutra/ai/blocks/error'` (new in 0.40.0) | `react-markdown` + `remark-gfm` |
+| `TextBlock` | `from '@devalok/shilp-sutra/ai'` OR `from '@devalok/shilp-sutra/ai/blocks'` | `from '@devalok/shilp-sutra/ai/blocks/text'` (new in 0.40.0) | `react-markdown` + `remark-gfm` |
+
+The seven other AI blocks (`BlockTable`, `ConfirmBlock`, `DividerBlock`, `InfoBlock`, `LoadingBlock`, `StatRowBlock`, `SuccessBlock`) have no peer-dep imports and remain available via `from '@devalok/shilp-sutra/ai/blocks'` (the sub-barrel) or `from '@devalok/shilp-sutra/ai'` (the main barrel).
+
+#### Codemod helper
+
+Most consumers can do this with a single `sed` per symbol family. Example for the toast family:
+
+```bash
+# Replace barrel imports of toast / Toaster with per-component imports
+grep -rl "from '@devalok/shilp-sutra/ui'" src/ | xargs sed -i.bak \
+  -e "s|import { \\(.*\\)toast\\(.*\\)} from '@devalok/shilp-sutra/ui'|import { toast } from '@devalok/shilp-sutra/ui/toast'\\nimport { \\1\\2} from '@devalok/shilp-sutra/ui'|"
+```
+
+(Adjust per project — the regex assumes a single `toast` import on the line. For multi-symbol lines, splitting by hand is faster than perfecting the regex.)
+
+#### Per-chart subpaths added (non-breaking)
+
+`/ui/charts/<chart>` subpaths are now exported for `area-chart`, `bar-chart`, `chart-container`, `gauge-chart`, `line-chart`, `pie-chart`, `radar-chart`, `sparkline`. The `/ui/charts` barrel still works and still pulls all 9 d3-\* peers — but if you only need `BarChart`, `import { BarChart } from '@devalok/shilp-sutra/ui/charts/bar-chart'` pulls only the d3-\* peers it actually needs (`d3-scale`, `d3-axis`, `d3-selection`).
+
+#### What didn't change
+
+- All per-component subpaths existed before 0.40.0 (except the 4 new ones noted above). Consumers already importing per-component need zero changes.
+- Component APIs, prop signatures, types, runtime behavior, default styles: all unchanged.
+- Storybook stories, tests, internal imports inside the DS itself: all use relative paths and were never affected.
+
+#### Why this isn't behind a flag
+
+There is no good additive solution. Tree-shaking can't drop a static `import 'sonner'` if `sonner` isn't on disk — the resolver fails before tree-shaking runs. Lazy-imports (`import('sonner')`) move the failure from build-time to runtime, which is worse. Removing the barrel re-export is the only fix.
+
+## v0.39.0 — Shape presets & semantic radius role tokens
+
+No API breaks. Component prop signatures unchanged. But the visual output of several components shifts because radius is now role-driven, not per-size ad-hoc.
+
+### What changed under the hood
+
+Radius now has TWO layers:
+
+- **Primitive scale** (private, unchanged): `--radius-ds-sm/md/lg/xl/2xl/full`
+- **Semantic roles** (new, public): `--radius-control`, `--radius-control-inner`, `--radius-surface`, `--radius-overlay-sm`, `--radius-overlay`, `--radius-overlay-lg`, `--radius-pill`, `--radius-bubble`
+
+Components reference roles. A new `[data-shape]` attribute on `<html>` (or any subtree) remaps all roles at once. Three presets ship: `sharp`, `slightly-rounded` (default), `rounded`.
+
+### Visual changes consumers see
+
+| Component | Was (px) | Now (px) | Why |
+|---|---|---|---|
+| Button md | 10 | 6 | Per-size radius scaling removed — same role, same radius |
+| Button lg | 16 | 6 | Same |
+| Button icon-lg | 10 | 6 | Same |
+| Input lg | 10 | 6 | Now matches Button at same height |
+| Tabs trigger (contained) | 10 | 6 | Now matches Button |
+| SegmentedControl item | 10 | 9999 | Renamed `pill` is now actually pill |
+| Menubar trigger | 2 | 6 | Now matches DropdownMenu item |
+| Autocomplete listbox | 6 | 10 | Now matches Popover / DropdownMenu |
+| ChatMessage bubble | 24 | 24 (preset-aware) | Now `rounded-bubble` — shifts with preset |
+| Everything else | unchanged | | |
+
+### If you liked the old "chunky big controls" look
+
+Either set the `rounded` preset on `<html>`:
+
+```diff
+- <html lang="en">
++ <html lang="en" data-shape="rounded">
+```
+
+Or override just `--radius-control` to keep the previous v0.38 default:
+
+```css
+:root { --radius-control: 10px; }
+```
+
+### Opting into the preset system
+
+To set the default (slightly-rounded) preset on your app explicitly:
+
+```diff
+- <html lang="en">
++ <html lang="en" data-shape="slightly-rounded">
+```
+
+Scoped overrides also work — apply `data-shape` to any subtree:
+
+```tsx
+<div data-shape="sharp">
+  <DeveloperConsole />
+</div>
+```
+
+### Migrating your own code from `rounded-ds-*` / `rounded-full`
+
+Your existing classes still render (primitive tokens are unchanged), but they're pinned to fixed values and won't respond to `[data-shape]` presets. To opt in, swap to role tokens:
+
+```diff
+- className="rounded-ds-md ..."       /* control-sized, 6px */
++ className="rounded-control ..."
+
+- className="rounded-ds-lg ..."       /* surface context — Card, Alert, panel */
++ className="rounded-surface ..."
+
+- className="rounded-ds-lg ..."       /* overlay context — Popover, Dropdown, listbox */
++ className="rounded-overlay ..."
+
+- className="rounded-ds-xl ..."       /* Dialog, Sheet, picker panel */
++ className="rounded-overlay-lg ..."
+
+- className="rounded-ds-2xl ..."      /* chat bubble */
++ className="rounded-bubble ..."
+
+- className="rounded-ds-sm ..."       /* checkbox box, focus ring, small chip */
++ className="rounded-control-inner ..."
+
+- className="rounded-ds-full ..."     /* and bare rounded-full */
++ className="rounded-pill ..."
+```
+
+A re-runnable codemod lives at `scripts/migrate-radius-roles.mjs` in this repo. Dry-run by default — pass `--write` to apply.
+
+### Custom presets
+
+Define your own `[data-shape="..."]` block:
+
+```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">
+```
+
+### Reference
+
+- Role token map: `packages/core/llms-full.txt` → "Shape Presets & Radius Roles" section
+- Recipe: `packages/core/docs/recipes/customize-brand.md` → "Shape presets" section
+- Storybook: `Foundations / Shape Presets` story — interactive switcher + custom-preset demo
+
+---
+
 ## v0.38.0 — Deprecation sweep
 
 0.38 removes 8 deprecated APIs that were soft-deprecated in earlier minor releases. All were available as aliases alongside their replacements; this release drops the aliases.

package/README.md

@@ -4,10 +4,13 @@ Devalok Design System -- tokens, components, and patterns for React & Next.js.
 
 [![npm](https://img.shields.io/npm/v/@devalok/shilp-sutra)](https://www.npmjs.com/package/@devalok/shilp-sutra)
 [![Storybook](https://img.shields.io/badge/Storybook-ff4785?logo=storybook&logoColor=white)](https://devalok-design.github.io/shilp-sutra/)
+[![Themer](https://img.shields.io/badge/Themer-shilp--sutra.devalok.in%2Fthemer-d946a6)](https://shilp-sutra.devalok.in/themer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 For full documentation, setup guides, and architecture details, see the [monorepo README](https://github.com/devalok-design/shilp-sutra#readme).
 
+> **Want to brand it?** Skip the CSS cookbook — open **[the Themer](https://shilp-sutra.devalok.in/themer)**. Pick an archetype (Linear / Stripe / Apple / Material / Notion / Vercel / Devalok), or paste your brand hex, or take a 5-question wizard. Lands you at a result page with install commands + a CSS block to paste.
+
 ## Install
 
 ```bash