@devalok/shilp-sutra 0.39.0 → 0.40.0

package/docs/recipes/customize-brand.md

@@ -2,6 +2,21 @@
 
 Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
 
+## The fast path: use the Themer
+
+Before hand-writing variables, try **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)**. It is one funnel with four entry doors:
+
+- **Pick an archetype** — Linear, Stripe, Apple, Material, Notion, Vercel, or Devalok. Click → result page.
+- **Use my brand color** — paste a hex or dial OKLCH. Auto-generates the 12-step ramp and suggests an archetype.
+- **Walk me through it** — five-question wizard composes the answers into a theme.
+- **Just exploring** — land on a sample result page to see what you ship away with.
+
+Every door drops you at the same result screen: a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp), install commands for your package manager, and a share URL that encodes the theme.
+
+Paste the snippet into your global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's the whole flow — no `tailwind.config.ts`, no theme provider, no JS bundle.
+
+The rest of this doc covers what to do if the Themer doesn't expose a token you need to override (font stack, spacing scale, focus ring) — fall through to the hand-written cases below.
+
 ## How tokens layer
 
 Shilp Sutra's tokens are organized in three tiers:

package/docs/recipes/index.md

@@ -29,9 +29,13 @@ 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 — colors, radius role tokens, `[data-shape]` presets, 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. **Start here**, or skip ahead to the Themer ↓ |
 | [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
 
+### The fast path: Themer
+
+Don't want to write CSS variables by hand? Use **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)** — one funnel, four doors (pick an archetype, paste your brand color, take a wizard, or just explore). Every door drops you at a result page with a CSS snippet to paste, install commands, and a share URL.
+
 ## Diagnostics
 
 | Recipe | What it covers |

package/docs/recipes/install-astro.md

@@ -29,6 +29,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Astro's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `astro.config`
 
 Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):

package/docs/recipes/install-next-app-router.md

@@ -8,10 +8,9 @@ You are in this recipe if **all** of these are true:
 
 - `package.json` lists `"next"` at version `^13.0.0` or higher
 - An `app/` directory exists at the project root or under `src/`
-- An `app/layout.tsx` (or `.jsx`) file exists
-- No `pages/` directory at the project root, OR `pages/` exists but only contains `_app.{js,tsx}` and `_document.{js,tsx}` (legacy artifacts)
+- An `app/layout.{tsx,jsx}` file exists
 
-If `pages/` is the primary router, use [install-next-pages.md](./install-next-pages.md).
+If a `pages/` directory exists at the project root AND contains route files (not just `_app`/`_document` legacy artifacts from older `create-next-app` versions), use [install-next-pages.md](./install-next-pages.md). `create-next-app@16+` no longer scaffolds `pages/` for App Router projects.
 
 ## 2. Install dependencies
 
@@ -47,6 +46,23 @@ Add brand assets package if you need Devalok or Karm logos:
 pnpm add @devalok/shilp-sutra-brand
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*` (BarChart, LineChart, …)| `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` use with Tabler icons            | `pnpm add @tabler/icons-react`                                                                          |
+
+> These aren't in core deps so consumers who never render a chart, OTP input, or rich-text editor don't pay the install / bundle cost. One-time decision at install.
+
 ## 3. Configure PostCSS
 
 Create or update `postcss.config.mjs` at the project root:
@@ -211,8 +227,8 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   }
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
-- **Server Component imports.** Use per-component imports (`@devalok/shilp-sutra/ui/text`) inside Server Components. The barrel import `@devalok/shilp-sutra/ui` pulls client-only code and breaks RSC. See [server-components.md](./server-components.md).
-- **`p-3` vs `p-ds-03`.** Our spacing namespace is `--spacing-ds-*` to avoid collision with consumer numeric spacing. Use `p-ds-04`, not `p-4`.
+- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/docs/recipes/install-next-pages.md

@@ -16,6 +16,8 @@ If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install
 
 Same dependencies as the App Router recipe — see [install-next-app-router.md § 2](./install-next-app-router.md#2-install-dependencies). Replace `next-themes`'s `attribute="class"` setup with the same on Pages Router (it works identically).
 
+**Optional peer dependencies** — if you'll render `<DataTable>`, any chart, `<DatePicker>`, `<RichTextEditor>`, `<InputOTP>`, `<FilePreview>`, `<MarkdownViewer>`, or use Tabler icons, install the matching peers BEFORE first import. Full table at [install-next-app-router.md § 2a](./install-next-app-router.md#2a-optional-peer-dependencies-install-only-when-importing-the-matching-subpath) — identical for Pages Router.
+
 ## 3. PostCSS
 
 Same as App Router — see [§ 3](./install-next-app-router.md#3-configure-postcss).

package/docs/recipes/install-remix.md

@@ -25,6 +25,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Remix's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 ```ts

package/docs/recipes/install-tanstack-start.md

@@ -23,6 +23,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or the TanStack Start dev/build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `app.config.ts`
 
 ```ts

package/docs/recipes/install-vite.md

@@ -40,6 +40,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or `vite dev` / `vite build` will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 Use the official Tailwind 4 Vite plugin (faster than PostCSS for Vite):

package/docs/recipes/troubleshoot.md

@@ -97,6 +97,28 @@ transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
 
 If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
 
+## Symptom: Build error `Cannot find module 'sonner' / 'input-otp' / 'date-fns' / '@tiptap/react' / 'react-pdf' / 'react-markdown' / '@emoji-mart/react'`
+
+**Diagnosis:** an optional peer dependency is missing. Each component below has a peer it pulls only when imported. Install the matching peer (always BEFORE the first import):
+
+| You imported (per-component subpath) | Install                                                                                       |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|
+| `…/ui/toaster` or `…/ui/toast`       | `pnpm add sonner`                                                                             |
+| `…/ui/input-otp`                     | `pnpm add input-otp`                                                                          |
+| `…/composed/date-picker`             | `pnpm add date-fns`                                                                           |
+| `…/composed/emoji-picker`            | `pnpm add @emoji-mart/data @emoji-mart/react`                                                 |
+| `…/composed/extensions/emoji-node` or `…/extensions/emoji-suggestion` | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-text-editor`        | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-chat-input`         | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/file-preview`            | `pnpm add react-pdf react-zoom-pan-pinch`                                                     |
+| `…/composed/markdown-viewer`         | `pnpm add react-markdown react-syntax-highlighter remark-gfm`                                 |
+| `…/ai/block-renderer`, `…/ai/blocks/text`, `…/ai/blocks/error` | `pnpm add react-markdown remark-gfm`                                                          |
+| Any `…/ui/charts/*`                  | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+
+These ship as **optional** peers so consumers who never render the matching component don't pay the install cost. Once you import the component, the peer becomes required. Each affected component's JSDoc carries the same install hint — hover the import in your editor to see it inline.
+
+For the full table in your framework's install recipe, see `install-<framework>.md → §2a. Optional peer dependencies`.
+
 ## Symptom: Hydration warning on every page load (Next.js)
 
 **Diagnosis:** `next-themes` writes the `class` attribute on `<html>` before React hydrates, causing a server/client class mismatch.

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.39.0
+> Version: 0.40.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
@@ -3032,6 +3032,92 @@ const { size, stroke } = useIconContext()
 
 ### v0.1.0
 - **Added** Initial release
+# OAuthButton
+
+- Import: @devalok/shilp-sutra/ui/oauth-button
+- Server-safe: No
+- Category: ui
+
+## Exports
+- `OAuthButton` — primary brand-aware sign-in button
+- `OAuthGroup` — stacked layout wrapper with consistent spacing
+- `OAuthDivider` — `or`-style horizontal rule between OAuth row and email form
+- `OAuthConnectionRow` — settings-page row for a linked provider (Disconnect / Connect action)
+
+## OAuthButton props
+    provider: "google" | "apple" | "github" | "microsoft" | "x" | "linkedin" | "facebook" | "discord" | "slack" | "gitlab" | "sso" | "email" | "passkey" (required)
+    intent: "continue" | "signin" | "signup" (default "continue") — drives the verb in the label
+    appearance: "brand" | "outline" | "dark" (default "brand") — visual treatment
+    icon: ReactNode — override the default Tabler glyph with a brand-multicolour SVG
+    iconOnly: boolean — compact icon-only button; provider name preserved in aria-label
+    compact: boolean — short label ("Google" not "Continue with Google"); aria-label keeps long form
+    lastUsed: boolean — inline right-edge pill inside the button (a stronger pattern is reorder, below)
+    helperText: ReactNode — reassurance copy rendered below the button
+    children: ReactNode — override the default label entirely (i18n / custom copy)
+    size: inherited from Button ("xs" | "sm" | "md" | "lg" | compact + icon variants)
+    fullWidth, loading, onClick, onClickAsync, asyncFeedbackDuration, disabled — inherited from Button
+
+## Data attributes
+- `data-provider="<provider>"` — useful for analytics filtering
+- `data-oauth-appearance="<appearance>"`
+
+## OAuthGroup props
+    orientation: "vertical" | "horizontal" (default "vertical")
+    gap: "ds-02" | "ds-03" | "ds-04" (default "ds-03")
+    fullWidth: boolean (default true) — stretches children to fill width when vertical
+    reorderLastUsedFirst: boolean (default false) — pull the child with lastUsed to position 0
+        (Stripe-style — a stronger conversion lever than a visual badge alone)
+
+## OAuthDivider props
+    label: ReactNode (default "or")
+
+## OAuthConnectionRow props
+    provider: OAuthProvider (required)
+    connected: boolean (required)
+    accountLabel: ReactNode — account identifier shown next to the provider name (e.g. email)
+    onAction: (e) => void — synchronous click handler
+    onActionAsync: (e) => Promise<void> — uses Button's async state machine
+    actionLabel: ReactNode — override the "Disconnect" / "Connect <name>" copy
+    icon: ReactNode — override the default glyph
+    disabled: boolean
+
+## Defaults
+    intent="continue", appearance="brand", iconOnly=false, lastUsed=false
+
+## Example
+```jsx
+// Typical signup flow
+<OAuthGroup>
+  <OAuthButton provider="google" lastUsed />
+  <OAuthButton provider="apple" />
+  <OAuthButton provider="github" />
+</OAuthGroup>
+<OAuthDivider />
+<OAuthGroup>
+  <OAuthButton provider="passkey" appearance="outline" />
+  <OAuthButton provider="email" appearance="outline" />
+</OAuthGroup>
+
+// Async loading + success/error feedback
+<OAuthButton provider="google" fullWidth onClickAsync={signInWithGoogle} />
+
+// True brand-multicolour glyph from the provider's brand page
+<OAuthButton provider="google" icon={<GoogleGSvg />} />
+
+// Settings page — linked state
+<OAuthConnectionRow
+  provider="google"
+  connected
+  accountLabel="namaskar@devalok.in"
+  onAction={disconnectGoogle}
+/>
+```
+
+## Composability
+- **Built on Button.** Async state machine, loading/processing, sizes, and `fullWidth` are inherited. `variant` and `color` are managed internally — pass `appearance` instead.
+- **Tabler peer dep.** Default glyphs come from `@tabler/icons-react`. To match a provider's official multicolour mark, pass `icon={<YourSvg />}`.
+- **Brand-colour backgrounds.** `appearance="brand"` uses each provider's published button colour. `appearance="outline"` falls back to DS-neutral. `appearance="dark"` unifies every provider into an Apple-style black-on-white (light) / white-on-black (dark) treatment — useful when you want a row to feel visually consistent across providers.
+- **Last-used hint.** Storage is the consumer's responsibility — pass `lastUsed={user.lastProvider === 'google'}`.
 # Pagination
 
 - Import: @devalok/shilp-sutra/ui/pagination

package/llms-quick.txt

@@ -0,0 +1,247 @@
+# @devalok/shilp-sutra — quick reference for AI agents
+
+> Tailwind 4 + React 19 + CVA design system. 110+ components, OKLCH tokens, framer-motion. **Not shadcn/ui** — APIs diverge in ways noted below.
+>
+> This file is the ≤15K-token fast-path summary. Reach for `llms.txt` (~27K tokens) or `llms-full.txt` (~140K tokens) only when this isn't enough.
+
+## SETUP (consumer install, ~5 min)
+
+```bash
+pnpm add @devalok/shilp-sutra framer-motion next-themes
+pnpm add -D tailwindcss@^4 @tailwindcss/postcss   # or @tailwindcss/vite
+```
+
+Then 4 files:
+
+```css
+/* globals.css — order matters */
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+```ts
+// next.config.ts — only if Next.js
+transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
+```
+
+```tsx
+// app/layout.tsx — Next App Router
+<html lang="en" suppressHydrationWarning>   {/* required for next-themes */}
+  <body><Providers>{children}</Providers></body>
+</html>
+```
+
+```tsx
+// app/providers.tsx
+'use client'
+import { ThemeProvider } from 'next-themes'
+import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
+export function Providers({ children }) {
+  return <ThemeProvider attribute="class" defaultTheme="system" enableSystem>{children}<Toaster /></ThemeProvider>
+}
+```
+
+Per-framework recipes: `node_modules/@devalok/shilp-sutra/docs/recipes/install-<framework>.md` (six recipes — Next App Router, Next Pages, Vite, Astro, Remix, TanStack Start).
+
+**Theme it in 30 seconds:** https://shilp-sutra.devalok.in/themer — outputs a copy-pasteable CSS block (12-step OKLCH ramp + role tokens). Paste *after* the `@devalok/shilp-sutra/css` import.
+
+## OPTIONAL PEER DEPENDENCIES (install BEFORE first import)
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter remark-gfm`                                           |
+| `@devalok/shilp-sutra/ui/toaster` or `…/ui/toast`          | `pnpm add sonner`                                                                                       |
+| Tabler icons in `<Icon>`, `<Button startIcon>`, etc.       | `pnpm add @tabler/icons-react`                                                                          |
+
+## HARD CONSTRAINTS
+
+1. **Tailwind 4 only.** No `tailwind.config.ts presets: [shilpSutra]` — that was removed in 0.38. CSS-only setup as above.
+2. **`framer-motion@^12` required peer.** Single copy — configure pnpm/yarn overrides if you see duplicates.
+3. **`sonner@^2`** required only when you render `<Toaster />` or call `toast.*`. Optional otherwise.
+4. **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Barrel `@devalok/shilp-sutra/ui` works in client contexts but inflates client bundle and forces optional peers to be installed. Prefer `…/ui/text`, `…/ui/dialog`, etc. The barrel **no longer** re-exports peer-cliff symbols (`Toaster`, `toast`, `InputOTP`, `DatePicker`, `RichTextEditor`, `EmojiPicker`, `FilePreview`, `MarkdownViewer`, `BlockRenderer`, `ErrorBlock`, `TextBlock`) as of 0.40.0 — import per-component.
+5. **Spacing namespace is `--spacing-ds-*`.** `p-ds-04`, `gap-ds-03` — these DO NOT replace TW4 default `p-4`, `gap-2`. Both coexist by design. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout values.
+6. **Bare `shadow` class renders no shadow in TW4.** Use `shadow-raised` (cards), `shadow-floating` (dropdowns), `shadow-overlay` (dialogs), `shadow-ring` (focus).
+7. **Variant names must match CVA source exactly** — invented variant names silently no-op (CVA falls back to defaults). Grep `packages/core/src/ui/<component>.tsx` if in doubt.
+8. **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions. Outline only on colored backgrounds or where primary/secondary hierarchy needs a hard border.
+
+## ICON API (one shape across every component, v0.40.0+)
+
+Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, …) takes `IconInput`:
+
+```tsx
+import { IconPlus } from '@tabler/icons-react'
+import { Icon } from '@devalok/shilp-sutra/ui/icon'
+
+<Button startIcon={<Icon icon={IconPlus} />}>Add</Button>   // canonical
+<Button startIcon={<IconPlus />}>Add</Button>                // raw Tabler element
+<Button startIcon={IconPlus}>Add</Button>                    // component ref
+<Button startIcon={<span>+</span>}>Add</Button>              // custom node
+```
+
+All four work. Size flows from `<IconProvider>` context — don't pass `className="h-4 w-4"`. On 22 components: Button, IconButton, Badge, Combobox, SegmentedControl, Stepper, StatCard, TreeItem, OAuthButton, Chat.Message.*, AIConversation, EmptyState, BulkActionBar, ActivityFeed, CommandPalette, TopBar, Sidebar, BottomNavbar, AppCommandPalette, CommandRegistry.
+
+## IMPORT PATH CHEATSHEET (don't guess)
+
+| Component / API                                | Exact import path |
+|------------------------------------------------|----|
+| `FormField`, `FormHelperText`, `useFormField`  | `@devalok/shilp-sutra/ui/form` (NOT `ui/form-field`)|
+| `Label`                                        | `@devalok/shilp-sutra/ui/label`|
+| `AppSidebar`                                   | `@devalok/shilp-sutra/shell/sidebar` (NOT `shell/app-sidebar`)|
+| `TopBar`, `TopBar.*`                           | `@devalok/shilp-sutra/shell/top-bar`|
+| `BottomNavbar`                                 | `@devalok/shilp-sutra/shell/bottom-navbar`|
+| `AppCommandPalette`                            | `@devalok/shilp-sutra/shell/app-command-palette`|
+| `NotificationCenter`                           | `@devalok/shilp-sutra/shell/notification-center`|
+| `CommandPalette` (lower-level)                 | `@devalok/shilp-sutra/composed/command-palette`|
+| `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `GaugeChart`, `Sparkline`, `ChartContainer`, `Legend` | `@devalok/shilp-sutra/ui/charts` (or per-chart subpath `…/ui/charts/bar-chart`) |
+| `DataTable`                                    | `@devalok/shilp-sutra/ui/data-table`|
+| **`DatePicker`** family                        | `@devalok/shilp-sutra/composed/date-picker` **(per-component required since 0.40)** |
+| **`Toaster`**                                  | `@devalok/shilp-sutra/ui/toaster` **(per-component required since 0.40, pulls `sonner`)** |
+| **`toast`**                                    | `@devalok/shilp-sutra/ui/toast` **(per-component required since 0.40)** |
+| **`InputOTP`** family                          | `@devalok/shilp-sutra/ui/input-otp` **(per-component required since 0.40)** |
+| **`EmojiPicker`**                              | `@devalok/shilp-sutra/composed/emoji-picker` **(per-component since 0.40)** |
+| **`FilePreview`**                              | `@devalok/shilp-sutra/composed/file-preview` **(per-component since 0.40)** |
+| **`MarkdownViewer`**                           | `@devalok/shilp-sutra/composed/markdown-viewer` **(per-component since 0.40)** |
+| **`RichTextEditor`** / **`RichChatInput`**     | `@devalok/shilp-sutra/composed/rich-{text-editor,chat-input}` **(per-component since 0.40)** |
+| **`BlockRenderer`**, **`ErrorBlock`**, **`TextBlock`** | `@devalok/shilp-sutra/ai/{block-renderer,blocks/error,blocks/text}` **(per-component since 0.40)** |
+| `useColorMode`                                 | `@devalok/shilp-sutra/hooks/use-color-mode`|
+| `MotionProvider`, `springs`, `tweens`          | `@devalok/shilp-sutra/motion`|
+
+Components whose import path is the kebab-case of their name (`Button` → `ui/button`, `Card` → `ui/card`, `Avatar` → `ui/avatar`, `Stack` → `ui/stack`, `Text` → `ui/text`) follow the obvious rule. The table above lists the ones that DON'T.
+
+## TWO-AXIS VARIANT SYSTEM (vs shadcn's one-axis)
+
+Many components take BOTH `variant` (shape/surface) AND `color` (intent/semantics):
+
+```tsx
+<Button variant="solid"   color="error">Delete</Button>     // red solid
+<Button variant="soft"    color="warning">Pending</Button>  // amber tinted
+<Button variant="outline" color="accent">Cancel</Button>    // bordered
+<Badge  variant="solid"   color="success">Active</Badge>    // green solid
+<Alert  variant="subtle"  color="info" title="Note" />      // tinted blue
+```
+
+Components with the two-axis system: **Button, Badge, Alert, Banner, Progress, StatusBadge**.
+
+## TOP DIFFERENCES FROM SHADCN/UI (will trip you up)
+
+| shadcn pattern | shilp-sutra equivalent |
+|---|---|
+| `variant="destructive"` | `color="error"` |
+| `size="default"` | `size="md"` (always — never "default") |
+| `<Select size="lg">` | `<SelectTrigger size="lg">` (size on trigger, NOT root) |
+| `<Chip>` | `<Badge onClick={...}>` (Chip removed 0.32) |
+| `useToast() + toast({variant})` | `import { toast }`, then `toast.success('msg')` |
+| `Badge variant="destructive"` | `Badge variant="solid" color="error"` |
+| `Alert + AlertTitle + AlertDescription` | `<Alert title="..." color="error">` (single component) |
+| `Form + FormField + FormItem + FormLabel + FormControl + …` | `<FormField>` + `<Label>` + `<Input>` + `<FormHelperText>` + `useFormField()` hook |
+
+## COMMON MISTAKES — DO NOT
+
+- DO NOT use `variant="destructive"` — use `color="error"`
+- DO NOT use `variant="default"` on Button — use `variant="solid"`
+- DO NOT use `size="default"` — use `size="md"`
+- DO NOT put `size` on `<Select>` — put it on `<SelectTrigger size="md">`
+- DO NOT use `<Chip>` — use `<Badge onClick={...}>`
+- DO NOT call `useToast()` hook — use `import { toast } from '@devalok/shilp-sutra/ui/toast'`
+- DO NOT call `toast({title, color})` object form — use `toast.success('message', { description })`
+- DO NOT call `toast()` without `<Toaster />` mounted
+- DO NOT use `<Alert><AlertTitle>...</AlertTitle></Alert>` — use `<Alert title="..." />`
+- DO NOT codemod `p-4` → `p-ds-04` — both coexist by design
+- DO NOT use bare `shadow` class — pick `shadow-raised` / `shadow-floating` / `shadow-overlay`
+- DO NOT use `tailwind.config.ts presets: [shilpSutra]` — JS preset removed 0.38
+- DO NOT use `bg-surface-1..4` — renamed to `bg-surface-{base,raised,raised-hover,raised-active}` in 0.23
+- DO NOT use `shadow-01..05` — renamed to `shadow-{raised,raised-hover,floating,overlay}` in 0.23
+- DO NOT use TW3 `bg-gradient-to-*` — use TW4 `bg-linear-to-*` (since 0.37)
+- DO NOT use TW3 `w-[--var]` — use TW4 `w-(--var)` (since 0.37)
+- DO NOT pass `children` to `<IconButton>` — use the `icon` prop
+
+## TOP 30 COMPONENTS QUICK-REF
+
+### Inputs & buttons
+- **Button**: variant(solid|soft|outline|ghost|link) color(accent|error|success|warning|neutral) size(xs|sm|md|lg|compact-xs|compact-sm|compact-md|icon-xs|icon-sm|icon-md|icon-lg) shape(default|pill) + loading, startIcon, endIcon, asChild, processing, onClickAsync
+- **IconButton**: icon(IconInput, required) shape(square|circle) size(sm|md|lg) + aria-label required. Children rejected by type.
+- **SplitButton**: `[Action | ▼]` with dropdown. triggerSide, dropdownContent.
+- **Input**: size(xs|sm|md|lg) state(default|error|warning|success) + startSection, endSection (auto-typed icon vs label).
+- **NumberInput**: value + onValueChange + min/max/step.
+- **Textarea**, **SearchInput**, **ColorInput**.
+- **Checkbox**: checked, onCheckedChange, indeterminate, error, size.
+- **Switch**: checked, onCheckedChange, error, size, color, thumbIcon.
+- **RadioGroup > RadioGroupItem**.
+- **Select > SelectTrigger(size) > SelectValue; SelectContent > SelectItem**.
+- **Combobox**: discriminated union — `multiple?: false` (value: string) | `multiple: true` (value: string[]).
+- **Autocomplete**, **Slider**, **Toggle**, **ToggleGroup**, **SegmentedControl**.
+- **FormField + Label + Input + FormHelperText + useFormField()** — replaces shadcn's Form + FormItem + FormControl + FormDescription + FormMessage.
+
+### Display
+- **Text**: variant(heading-2xl..xs, body-lg..xs, label-lg..xs, caption, overline, code). Polymorphic `as` prop.
+- **Stack**: direction(vertical|horizontal) gap(SpacingToken) align/justify/wrap.
+- **Container**, **Separator**.
+- **Card**: variant(default|elevated|outline|flat) accent(left|top|right|bottom). Compound: CardHeader > CardTitle, CardDescription; CardContent; CardFooter.
+- **Badge**: variant(subtle|solid|outline|soft) color(default|accent|error|success|warning|info|neutral + 7 categories + custom) size(xs|sm|md|lg) + onClick, onDismiss, dot, startIcon, endIcon, truncate. Compound: Badge.Indicator, Badge.Group.
+- **Avatar**: size(xs|sm|md|lg|xl) shape(circle|square|rounded) status, ring, badge.
+- **Spinner**, **Progress** (autoColor!), **Skeleton**, **StatCard**, **StatusDot**, **ColorSwatch**.
+- **Alert**: variant(subtle|solid|outline) color(info|success|warning|error|neutral) + title, onDismiss. Single component, not compound.
+- **Banner**: color(...) + actions, onDismiss. Mobile-responsive.
+- **Toast**: imperative `toast.success('msg')` / `.error/.warning/.info/.loading/.message/.promise/.upload/.custom`. Requires `<Toaster />`.
+
+### Overlays
+- **Dialog**: compound (DialogTrigger; DialogContent > DialogHeader > DialogTitle; …; DialogFooter). Mobile auto-fullscreens.
+- **AlertDialog**: same compound, mobile bottom-sheet via `responsive` prop.
+- **Sheet**: side(top|bottom|left|right). Mobile auto-bottom + swipe-to-dismiss.
+- **Popover**, **Tooltip** (auto-wraps Provider), **HoverCard**, **Collapsible**.
+
+### Navigation
+- **Tabs**: TabsList(variant: line|contained) > TabsTrigger; TabsContent. color, size, orientation.
+- **Accordion**: AccordionItem > AccordionTrigger; AccordionContent.
+- **Breadcrumb**, **PaginationRoot**, **DropdownMenu**, **ContextMenu**, **Menubar**, **NavigationMenu**.
+
+### Composed (per-component subpaths)
+- **DatePicker**, **DateRangePicker**, **DateTimePicker**, **TimePicker**, **CalendarGrid** — `@devalok/shilp-sutra/composed/date-picker`. Needs `date-fns` peer.
+- **EmptyState**: icon(IconInput) + title, description, action, compact, iconSize.
+- **CommandPalette**, **AppCommandPalette**, **MultiSelectPopover**, **MemberPicker**, **MasterDetail**, **ActivityFeed**, **PageHeader**, **InlineEdit**, **FormSection**, **BulkActionBar**, **DeadlineIndicator**.
+- **RichTextEditor**, **RichTextViewer**, **RichChatInput** — needs `@tiptap/*` peers.
+- **FilePreview**, **MarkdownViewer**, **EmojiPicker**.
+
+### Shell
+- **TopBar**: Composition-based. `TopBar.Left/Center/Right/Section/IconButton/Title/UserMenu`.
+- **AppSidebar**: `NavItem[]` + `NavGroup[]` + `footer.{links,version,promo,slot}`.
+- **BottomNavbar**: mobile.
+- **NotificationCenter**, **NotificationPreferences**, **LinkProvider**.
+
+### AI module
+- **CommandBar**, **AIConversation**, **BlockRenderer** (per-component, pulls `react-markdown`), **AICommandProvider**, **DevadootIcon**.
+- AI blocks (barrel-safe): BlockTable, ConfirmBlock, DividerBlock, InfoBlock, LoadingBlock, StatRowBlock, SuccessBlock.
+- AI blocks (per-component required): ErrorBlock (`/ai/blocks/error`), TextBlock (`/ai/blocks/text`).
+
+## SERVER-SAFE COMPONENTS (`@server-safe` annotation in source)
+
+UI: `Text`, `Skeleton`, `Stack`, `Container`, `Table` (+ sub), `Code`, `VisuallyHidden`.
+Composed: `ContentCard`, `PageHeader`, `LoadingSkeleton`, `PageSkeletons`, `PriorityIndicator`.
+
+Use per-component subpaths in Server Components: `import { Text } from '@devalok/shilp-sutra/ui/text'`.
+
+## TROUBLESHOOTING
+
+13 symptoms with diagnosis + fix at `node_modules/@devalok/shilp-sutra/docs/recipes/troubleshoot.md`. Most common:
+
+- **`Cannot find module 'sonner'` / `'input-otp'` / `'date-fns'`** → missing optional peer; install per the matrix above.
+- **Spacing utilities don't apply** → Tailwind not seeing `node_modules/@devalok/shilp-sutra/dist`; ensure `transpilePackages` in `next.config` OR Tailwind 4 auto-discovery.
+- **`<Toaster />` mounted but `toast()` silent** → check sonner peer installed + Toaster mounted ONCE at layout root.
+- **Hydration warning on every page** → add `suppressHydrationWarning` to `<html>` (needed for next-themes).
+- **Bare `shadow` produces no shadow** → TW4 has no `--shadow-DEFAULT`; pick `shadow-raised`/`-floating`/`-overlay`.
+
+## NEED MORE?
+
+- `llms.txt` — full ~27K-token reference (this file is the slice)
+- `llms-full.txt` — exhaustive per-component prop tables (~140K tokens)
+- `docs/recipes/install-<framework>.md` — per-framework setup with edge cases
+- `docs/recipes/customize-brand.md` — token override cookbook
+- `MIGRATION.md` — every breaking change since 0.18
+
+This file regenerates from `llms.txt` when component APIs change; expect it to track v0.40+ closely.