@devalok/shilp-sutra 0.40.1 → 0.42.0

package/make-kit/foundations/motion.md

@@ -0,0 +1,134 @@
+# Motion
+
+framer-motion is the kit's animation engine. **Don't write CSS keyframes** — use motion primitives.
+
+## Required setup
+
+```tsx
+import { MotionProvider } from '@devalok/shilp-sutra/motion'
+
+<MotionProvider reducedMotion="user">
+  <App />
+</MotionProvider>
+```
+
+`reducedMotion="user"` respects the OS's "reduce motion" preference. Without `MotionProvider`, the primitives still work but reduced-motion is ignored — accessibility regression.
+
+## Primitives
+
+```tsx
+import {
+  MotionFade,
+  MotionCollapse,
+  MotionSlide,
+  MotionPop,
+  MotionScale,
+  MotionStagger,
+} from '@devalok/shilp-sutra/motion/primitives'
+```
+
+| Primitive | Use |
+|---|---|
+| `MotionFade` | Mount/unmount with opacity fade. |
+| `MotionCollapse` | Height-based expand/collapse. |
+| `MotionSlide` | Slide in from a direction (`from="top"|"bottom"|"left"|"right"`). |
+| `MotionPop` | Scale + fade pop. Good for tooltips, badges entering. |
+| `MotionScale` | Scale only. |
+| `MotionStagger` | Stagger children with a configurable delay. |
+
+```tsx
+<MotionFade>
+  <Card>This card fades in on mount.</Card>
+</MotionFade>
+
+<MotionStagger gap={0.05}>
+  {items.map((item) => (
+    <ListItem key={item.id}>{item.name}</ListItem>
+  ))}
+</MotionStagger>
+```
+
+## Springs & tweens
+
+```tsx
+import { springs, tweens } from '@devalok/shilp-sutra/motion'
+```
+
+| Spring | Feel |
+|---|---|
+| `springs.snappy` | Decisive, quick. Default for controls. |
+| `springs.smooth` | Smooth, no overshoot. Default for layout. |
+| `springs.bouncy` | Playful overshoot. Use sparingly — only for delight moments. |
+| `springs.gentle` | Soft, slow. For ambient motion. |
+
+| Tween | Duration |
+|---|---|
+| `tweens.fade` | 0.11s — color/opacity. |
+| `tweens.colorShift` | 0.07s — hover color changes. |
+
+Apply via framer's `transition` prop:
+
+```tsx
+import { motion } from 'framer-motion'
+import { springs } from '@devalok/shilp-sutra/motion'
+
+<motion.div animate={{ y: open ? 0 : -8 }} transition={springs.snappy}>
+  …
+</motion.div>
+```
+
+## Duration tokens (CSS, when motion primitives aren't right)
+
+| Token | Duration |
+|---|---|
+| `--duration-fast-01` | 70 ms |
+| `--duration-fast-02` | 110 ms |
+| `--duration-moderate-01` | 150 ms |
+| `--duration-moderate-02` | 240 ms |
+| `--duration-slow-01` | 400 ms |
+| `--duration-slow-02` | 700 ms |
+
+Tailwind utilities: `duration-fast-01`, `duration-moderate-01`, etc. CSS variables: `var(--duration-moderate-01)`.
+
+The system easing is `ease-productive-standard` — apply via `transition` shorthand:
+
+```tsx
+<div className="transition-colors duration-fast-02">…</div>
+```
+
+## Patterns
+
+**Drawer / Sheet slide-in:** already built into `<Sheet>`. Don't reimplement.
+
+**Dialog backdrop fade + content scale:** already built into `<Dialog>`. Don't reimplement.
+
+**List item enter (e.g. new card appears):**
+
+```tsx
+<MotionFade>
+  <Card>New item</Card>
+</MotionFade>
+```
+
+**Staggered table rows:**
+
+```tsx
+<MotionStagger gap={0.03}>
+  {rows.map((row) => <TableRow key={row.id}>{row.cells}</TableRow>)}
+</MotionStagger>
+```
+
+**Async button feedback:** use `<Button onClickAsync>` — it auto-animates idle → loading → success/error → idle. Don't hand-roll spinner toggling.
+
+```tsx
+<Button onClickAsync={async () => { await save() }}>Save</Button>
+```
+
+## Rules
+
+- **Wrap the app in `<MotionProvider reducedMotion="user">` once.** Without it, OS reduce-motion preference is ignored.
+- **Never** write CSS `@keyframes` for app animations — use framer primitives.
+- **Use motion primitives** before reaching for raw `motion.*` — they bundle the right spring + reduced-motion respect.
+- **Don't animate layout** (height, width, top, left) — animate `transform` and `opacity`. The primitives do this for you.
+- **Don't overuse `bouncy`** — bouncy works for one delight moment per session, not for every hover.
+- For async button states, use `onClickAsync` + `asyncFeedbackDuration`, not manual `loading` toggling.

package/make-kit/foundations/radius.md

@@ -0,0 +1,78 @@
+# Radius
+
+Two layers: a primitive scale and semantic role tokens. **Components reference roles. Override roles, not individual components.**
+
+## Two-layer model
+
+**Primitive scale** (size buckets):
+
+| Token | Pixels |
+|---|---|
+| `radius-ds-none` | 0 |
+| `radius-ds-sm` | 2 |
+| `radius-ds-md` | 6 |
+| `radius-ds-lg` | 10 |
+| `radius-ds-xl` | 16 |
+| `radius-ds-2xl` | 24 |
+| `radius-ds-full` | 9999 (pill) |
+
+**Semantic roles** (mapped to scale at the default preset):
+
+| Role | Default | Where it applies |
+|---|---|---|
+| `radius-control` | 6 | Button, Input, Select, IconButton, segmented item, Tab trigger. |
+| `radius-control-inner` | 2 | Inner elements inside a control (e.g. selected segment indicator). |
+| `radius-surface` | 10 | Cards, widgets, panels. |
+| `radius-overlay-sm` | 6 | Tooltip, Toast. |
+| `radius-overlay` | 10 | Popover, Dropdown, Menubar. |
+| `radius-overlay-lg` | 16 | Dialog, Sheet. |
+| `radius-pill` | 9999 | Badge, Switch, Radio dot, Avatar circle. Pill always wins. |
+| `radius-bubble` | 24 | Chat bubbles. |
+
+## How to apply
+
+In components: never — they apply the right role automatically.
+
+In your own elements (rare):
+
+```tsx
+<div className="bg-surface-raised rounded-(--radius-surface) p-ds-05">…</div>
+```
+
+TW4 shorthand `rounded-(--radius-surface)` is the right way. **Do not** use `rounded-ds-lg` directly — it's not a semantic role, and the pre-publish audit rejects it in `src/ui/`.
+
+## Shape presets
+
+The kit ships three shape presets, switchable via `[data-shape]` on `<html>`:
+
+| Preset | Roles |
+|---|---|
+| `sharp` | control 2 / control-inner 0 / surface 4 / overlay 4–6 |
+| `slightly-rounded` (default) | control 6 / control-inner 2 / surface 10 / overlay 6–16 |
+| `rounded` | control 10 / control-inner 4 / surface 16 / overlay 10–24 |
+
+Toggle by setting `data-shape="rounded"` on `<html>` (or any subtree) — every component re-skins instantly. Pill shapes (Badge, Switch, Radio dot, Avatar circle) stay pill regardless of preset.
+
+```html
+<html data-shape="rounded">
+```
+
+## Custom override
+
+Consumers can swap any role in their global CSS:
+
+```css
+:root {
+  --radius-control: 4px;     /* sharper buttons + inputs */
+  --radius-surface: 12px;    /* gentler cards */
+}
+```
+
+Override the role, not individual components. That way one declaration re-skins the whole system.
+
+## Rules
+
+- **Never** hand-pick a pixel radius (`rounded-[12px]`). Use a role.
+- **Never** use `rounded-ds-*` directly in component-level code — that's the primitive scale, not the role.
+- **Never** override `<Card>`, `<Button>` etc. radius via className. Override the role instead.
+- **Pill shapes** are uncontested — Badge, Switch, Radio dot, Avatar circle stay pill no matter the preset.

package/make-kit/foundations/spacing.md

@@ -0,0 +1,110 @@
+# Spacing
+
+The kit uses a `ds-*` spacing scale (2 → 160 px) so utilities never collide with consumer values. **Default to a three-tier cadence — `ds-03` / `ds-05` / `ds-07` — not every adjacent token.**
+
+## Three-tier cadence (the rule)
+
+| Tier | Token | Pixels | Use |
+|---|---|---|---|
+| Related | `ds-03` | 8 | Items that read as one chunk — icon + label, label + input, badges in a row. |
+| Grouped | `ds-05` | 16 | Sections within a card — heading group, controls group, body. |
+| Section | `ds-07` | 32 | Distinct page sections, big breaks. |
+
+**Do not** reach for `ds-04` (12 px) or `ds-06` (24 px) just because they exist. Three tiers create rhythm; five create noise.
+
+If you need a *fourth* tier (e.g. between heading and body inside one group), use `ds-02` (4 px) — that's the "tight pair" tier (caption to value, hint to input).
+
+## Full scale
+
+| Token | Pixels | Typical use |
+|---|---|---|
+| `ds-01` | 2 | Hairline gap. Rare. |
+| `ds-02` | 4 | Tight pair (caption under value, icon to text inside dense control). |
+| `ds-02b` | 6 | Off-cadence; use sparingly. |
+| `ds-03` | 8 | **Related** (default). |
+| `ds-04` | 12 | Use only when 8 is too tight and 16 is too loose. |
+| `ds-05` | 16 | **Grouped** (default). |
+| `ds-05b` | 20 | Off-cadence; rare. |
+| `ds-06` | 24 | Comfortable section gap; prefer `ds-07` unless 32 is too much. |
+| `ds-06b` | 28 | Off-cadence. |
+| `ds-07` | 32 | **Section** (default). |
+| `ds-08` | 40 | Big section. |
+| `ds-09` | 48 | Hero spacing. |
+| `ds-10` | 64 | Marketing. |
+| `ds-11+` | 80 / 96 / 160 | Marketing only. |
+
+## How to apply
+
+```tsx
+// Padding
+<Card className="p-ds-05">…</Card>          // inside-card spacing
+<div className="px-ds-07 py-ds-09">…</div>  // page region
+
+// Gaps
+<Stack gap="ds-03">…</Stack>                // related items
+<Stack gap="ds-05">…</Stack>                // grouped items
+<Stack gap="ds-07">…</Stack>                // sections
+
+// Margins (rare — prefer gap)
+<Text className="mt-ds-02">helper</Text>    // tight pair
+```
+
+## `<Stack>` over flex divs
+
+Don't write `<div className="flex flex-col gap-ds-05">`. Use `<Stack>`:
+
+```tsx
+<Stack gap="ds-05">
+  <Text variant="heading-md">Heading</Text>
+  <Text variant="body-md">Body</Text>
+  <Button>CTA</Button>
+</Stack>
+
+<Stack direction="row" gap="ds-03" align="center">
+  <Icon icon={IconUser} />
+  <Text>Username</Text>
+</Stack>
+```
+
+`<Stack>` ships with `direction` (row | col, default col), `gap` (ds-* token), `align`, `justify`, `wrap`, `as` (polymorphic).
+
+## Component sizing (separate from spacing)
+
+Heights for controls use `ds-{size}` aliases:
+
+| Token | Pixels | Component sizes |
+|---|---|---|
+| `ds-xs` | 24 | n/a (rare) |
+| `ds-xs-plus` | 28 | Button/Input/Select **xs** |
+| `ds-sm` | 32 | Button/Input/Select **sm** |
+| `ds-md` | 40 | Button/Input/Select **md** (default) |
+| `ds-lg` | 48 | Button/Input/Select **lg** |
+| `ds-xl` | 56 | Button **xl** |
+
+Apply via component `size` prop, not className.
+
+## Page layout tokens
+
+| Token | Use |
+|---|---|
+| `--spacing-page-x` | Horizontal page padding. Responsive: 16 → 24 → 40 px. |
+| `--spacing-section-gap` | Vertical gap between major page sections. |
+| `--spacing-card-gap` | Vertical gap between adjacent cards. |
+
+Apply via:
+
+```tsx
+<main className="px-(--spacing-page-x) py-ds-09">
+  <Stack gap="(--spacing-section-gap)">
+    …
+  </Stack>
+</main>
+```
+
+## Rules
+
+- **Default** to `ds-03 / ds-05 / ds-07`. Justify any deviation.
+- **Never** use raw Tailwind spacing (`p-4`, `gap-6`). The kit's spacing is `ds-*` namespaced.
+- **Never** mix arbitrary pixel values (`p-[14px]`). Pick a scale token.
+- **Prefer `<Stack gap>` over `flex … gap-*`**. Cleaner semantics, polymorphic via `as`.
+- Component sizes (xs / sm / md / lg / xl) come from the size prop, not from manual height utilities.

package/make-kit/foundations/surfaces.md

@@ -0,0 +1,121 @@
+# Surfaces & Shadows
+
+The kit ships five semantic surface tiers and a paired shadow system. **Picking the right surface is mandatory** — the wrong one breaks elevation hierarchy and dark mode adaptation. There is a hard rule about never combining surfaces with borders.
+
+## The five surface tiers
+
+| Tier | Token | What sits here |
+|---|---|---|
+| **Base** | `surface-base` | Page background. The "back wall." |
+| **Raised** | `surface-raised` | Cards, widgets, panels — anything that floats **on** the page. |
+| **Sunken** | `surface-sunken` | Shell chrome (Sidebar, TopBar), board columns, segmented-control tracks. |
+| **Overlay** | `surface-overlay` | Floating layers — Dialog, Sheet, Popover, Dropdown, Toast, Tooltip-when-light, Input field. |
+| **Inverted** | `surface-inverted` | Tooltips, inverted badges. Pair with `text-surface-inverted-fg`. |
+
+Each tier has hover / active variants:
+
+- `surface-raised-hover` — hover on a raised element.
+- `surface-raised-active` — pressed / selected raised element.
+
+And a disabled state:
+
+- `surface-disabled` + `text-surface-fg-disabled`.
+
+## Decision matrix
+
+| Building… | Surface | Shadow |
+|---|---|---|
+| Page / layout shell | `surface-base` | none |
+| Sidebar / TopBar (shell) | `surface-sunken` | `shadow-raised` |
+| Card / widget / panel | `surface-raised` | `shadow-raised` |
+| Card on hover | `surface-raised` | `shadow-raised-hover` |
+| Board column / well / track | `surface-sunken` | none |
+| Popover / dropdown / menu | `surface-overlay` | `shadow-floating` |
+| Dialog / modal / sheet | `surface-overlay` | `shadow-overlay` |
+| Tooltip | `surface-inverted` | `shadow-floating` |
+| Toast | `surface-overlay` | `shadow-floating` |
+| Input (rest) | `surface-overlay` | none |
+| Input (focus) | `surface-overlay` | `shadow-ring` |
+| Button (solid) | accent colors | `shadow-raised` |
+| Button (disabled) | `surface-disabled` | none |
+| Segmented track | `surface-sunken` | `shadow-inset` |
+| Selected item | current surface | `shadow-glow` |
+| Backdrop (under modal) | `bg-backdrop` | none |
+
+## Shadow tokens
+
+| Token | When |
+|---|---|
+| `shadow-raised` | Cards, panels, shell chrome at rest. |
+| `shadow-raised-hover` | Cards on hover. Subtle lift. |
+| `shadow-floating` | Popovers, dropdowns, menus, tooltips. |
+| `shadow-overlay` | Dialogs, sheets. Deepest. |
+| `shadow-brand` | Optional brand-tinted glow. Use on hero CTA. |
+| `shadow-glow` | Selection / focus accent. |
+| `shadow-inset` | Toggle / segmented track deboss. |
+| `shadow-ring` | Focus ring (2px accent). |
+| `shadow-ring-sm` | Subtle separator (1px border-color). |
+| `shadow-kbd` | Inset for keyboard shortcut badges. |
+| `shadow-success` / `shadow-error` / `shadow-warning` | Status glow. Use on status notifications. |
+
+## The hard rule: never combine `border-*` with `shadow-*`
+
+Shadow tokens include a 1-px ring layer (inset hairline + drop shadow). Adding an explicit `border-surface-border` on top creates a 2-px edge that looks broken.
+
+❌ **Wrong:**
+```tsx
+<div className="bg-surface-raised border border-surface-border shadow-raised rounded-(--radius-surface)">
+```
+
+✅ **Right (shadow only):**
+```tsx
+<div className="bg-surface-raised shadow-raised rounded-(--radius-surface)">
+```
+
+✅ **Right (border only — when shadow is unwanted, e.g. dense lists):**
+```tsx
+<div className="bg-surface-raised border border-surface-border rounded-(--radius-surface)">
+```
+
+`<Card>` already follows this rule. Don't override with extra border classes.
+
+## Elevation reasoning
+
+Surfaces describe **what kind of layer** something is, not **how high** it is. Two cards next to each other are both `raised`. A dialog over them isn't `raised-more` — it's `overlay`. A sidebar isn't `raised-but-lower` — it's `sunken`.
+
+This means: **don't stack `raised` on `raised`**. If you'd reach for that, the inner element is probably `overlay` or wants a `surface-sunken` recess instead.
+
+## Dark mode
+
+In dark mode the kit lightens surfaces with elevation (so `surface-overlay` is *brighter* than `surface-base`). This is the inverse of light mode and is intentional — it's how Stripe / Linear / Material 3 model elevation in dark. Don't fight it.
+
+## Page composition example
+
+```tsx
+<div className="min-h-screen bg-surface-base">
+  <aside className="bg-surface-sunken">  {/* Sidebar */}
+    …
+  </aside>
+  <main className="bg-surface-base p-ds-07">
+    <Card className="bg-surface-raised shadow-raised p-ds-05">  {/* Card */}
+      …
+      <Dialog>
+        <DialogContent className="bg-surface-overlay shadow-overlay">
+          …  {/* Modal */}
+        </DialogContent>
+      </Dialog>
+    </Card>
+  </main>
+</div>
+```
+
+(In practice you wouldn't write the `bg-*` / `shadow-*` directly — `<Card>`, `<DialogContent>`, `<AppSidebar>` apply them. This is just the layer model.)
+
+## Rules
+
+- **Card-like elements** (anything that reads as a panel on the page) → `surface-raised`, never `surface-base`.
+- **Overlay-like elements** → `surface-overlay`, always.
+- **Never** combine an explicit border with a shadow token.
+- **Never** invent a sixth tier. Five is the system.
+- **Don't** override `<Card>`, `<DialogContent>`, `<PopoverContent>` surface — they pick the right one for you.
+- For Storybook authors and pre-publish audit: components in `src/ui/` that render as cards must NOT use `bg-surface-base`. The audit script will reject it.

package/make-kit/foundations/typography.md

@@ -0,0 +1,120 @@
+# Typography
+
+The kit ships an 11-step type scale (`text-ds-xs` through `text-ds-6xl`) with paired line-heights. **Use the scale, not arbitrary pixel values.**
+
+## Philosophy
+
+- One scale, applied with intent. A page should land on 3–4 text sizes max — heading + body + caption.
+- Larger headings (3xl and up) use `clamp()` to scale fluidly between mobile and desktop. Smaller sizes are fixed.
+- Default font is Inter Variable (sans). `Ranade` Variable is the accent display face for marketing-heavy treatments. SF Mono is the monospace.
+- Letter spacing on body sizes is tuned per-size (`body-lg: -0.01em`, `body-md: 0`, `body-sm: +0.01em`, `body-xs: +0.02em`).
+
+## Size scale
+
+| Token | Size | Use |
+|---|---|---|
+| `text-ds-xs` | 10px | Footnotes, fine print, only when space is at premium. Never for primary content. |
+| `text-ds-sm` | 12px | Captions, table labels, helper text, badges. |
+| `text-ds-md` | 14px | Default UI body. All input fields. Default Button label. |
+| `text-ds-base` | 16px | Body copy in marketing / docs. Mobile input minimum. |
+| `text-ds-lg` | 18px | Lead paragraphs, large body. |
+| `text-ds-xl` | 20px | Small heading (h4). |
+| `text-ds-2xl` | 24px | Section heading (h3). |
+| `text-ds-3xl` | clamp 24→32 | Page heading (h2). Fluid. |
+| `text-ds-4xl` | clamp 28→36 | Large page heading (h1 in product). |
+| `text-ds-5xl` | clamp 32→48 | Marketing hero. |
+| `text-ds-6xl` | clamp 36→60 | Marketing display. |
+
+Pair each size with a line-height: `leading-ds-{none|tight|snug|normal|relaxed|loose}`. Default for body: `leading-ds-normal` (1.4). For headings: `leading-ds-tight` (1.15) or `leading-ds-snug` (1.25).
+
+## Composite typography utilities
+
+Prefer these — they bundle size + leading + weight + tracking:
+
+| Utility | Use |
+|---|---|
+| `text-heading-xl` | Page hero heading. |
+| `text-heading-lg` | Section heading. |
+| `text-heading-md` | Card / panel heading. |
+| `text-heading-sm` | Sub-heading. |
+| `text-body-lg` | Lead body. |
+| `text-body-md` | Default body. |
+| `text-body-sm` | Secondary body. |
+| `text-body-xs` | Caption, footnote. |
+| `text-code` | Inline / block code. |
+| `text-label-plain-lg` / `-md` / `-sm` | Form labels (non-tab). |
+
+These are what `<Text>` applies internally. When generating raw text, prefer using `<Text variant="heading-md">` (or similar) over manually composing utilities.
+
+## Font families
+
+| Token | Family | Use |
+|---|---|---|
+| `font-sans` | Inter | Default. UI body + headings. |
+| `font-display` | Inter | Marketing headings (same family by default, separate token for theming). |
+| `font-accent` | Ranade | Optional display accent. Only for marketing hero / brand moments. |
+| `font-mono` | SF Mono / Fira Code | Code blocks, keyboard shortcuts, tabular data. |
+
+## Weights
+
+`font-weight-{light|regular|medium|semibold|bold}` = 300 / 400 / 500 / 600 / 700.
+
+Apply via Tailwind's `font-light` / `font-medium` / `font-semibold` / `font-bold`. Default is regular (400). Headings default to `font-medium` (500). **Avoid bold (700)** for headings — the kit uses medium for refined feel. Use semibold for emphasized labels.
+
+## Hierarchy patterns
+
+**Card heading + body:**
+
+```tsx
+<Card className="p-ds-05">
+  <Text variant="heading-md">Project</Text>
+  <Text variant="body-md" className="text-fg-muted mt-ds-02">
+    Sub-description with metadata.
+  </Text>
+</Card>
+```
+
+**Page header:**
+
+```tsx
+<Stack gap="ds-03" className="mb-ds-07">
+  <Text variant="heading-xl">Dashboard</Text>
+  <Text variant="body-lg" className="text-fg-muted">
+    Overview of every active project.
+  </Text>
+</Stack>
+```
+
+**Form label + input:**
+
+```tsx
+<FormField>
+  <Label>Email</Label>
+  <Input type="email" placeholder="you@company.com" />
+  <FormHelperText>We'll never share this.</FormHelperText>
+</FormField>
+```
+
+`<Label>` already applies `text-label-plain-md`. Don't override with size utilities.
+
+## Polymorphic `<Text>`
+
+`<Text>` is polymorphic via `as` prop:
+
+```tsx
+<Text as="h1" variant="heading-xl">Page title</Text>
+<Text as="p" variant="body-md">Body copy.</Text>
+<Text as="label" htmlFor="email">Email</Text>
+<Text as="a" href="/x">A link</Text>
+```
+
+The `as` prop widens accepted HTML attributes to the rendered element — `htmlFor` / `href` typecheck correctly.
+
+## Rules
+
+- **Never** hand-pick a pixel font-size (`text-[15px]`, `text-[18px]`). Use the scale.
+- **Never** use `font-bold` on headings. Use `font-medium` or `font-semibold`.
+- **Never** apply two size utilities at once (`text-ds-md text-ds-lg`). Use composite variants.
+- **Never** use small text (`text-ds-xs`) for anything except captions and footnotes.
+- **Prefer `<Text variant="...">` over raw `<p>` / `<span>`** when typographic semantics matter.
+- Inputs must be at least `text-ds-md` (14px) on desktop and `16px` on mobile (the kit enforces the iOS-zoom-safe minimum automatically).

package/make-kit/setup.md

@@ -0,0 +1,130 @@
+# Setup
+
+Required to use this kit. Every generated app needs all of these.
+
+## Install
+
+```bash
+npm i @devalok/shilp-sutra @tabler/icons-react framer-motion tailwindcss @tailwindcss/vite
+# optional, only if you render toasts:
+npm i sonner
+```
+
+`framer-motion` and `tailwindcss` are **required peer dependencies.** Without them, motion contexts split and tokens don't compile.
+
+## Vite config
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})
+```
+
+## Single CSS entry
+
+In `src/index.css` (or your global stylesheet):
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+Import that CSS file once at the app root (`main.tsx`):
+
+```tsx
+import './index.css'
+```
+
+**Do not add `tailwind.config.ts`.** This kit is Tailwind 4 CSS-first. There is no JS preset. All tokens come from the CSS import via `@theme` blocks.
+
+## Provider tree
+
+Wrap the app once at the root:
+
+```tsx
+import { MotionProvider } from '@devalok/shilp-sutra/motion'
+import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
+import { IconProvider } from '@devalok/shilp-sutra/ui/icon-context'
+
+export default function App({ children }) {
+  return (
+    <MotionProvider reducedMotion="user">
+      <IconProvider size={16}>
+        {children}
+        <Toaster />
+      </IconProvider>
+    </MotionProvider>
+  )
+}
+```
+
+- `MotionProvider` — required. `reducedMotion="user"` respects OS preference. Without this provider, motion primitives still work but reduced-motion is ignored.
+- `IconProvider` — optional but recommended. Sets default icon size for all `<Icon>` children. Override per-call with `<Icon size={20} />`.
+- `Toaster` — only needed if the app calls `toast(...)`. Mount exactly once.
+
+## Dark mode toggle
+
+Add the `.dark` class on `<html>` or `<body>` to flip the entire token system to dark. The kit ships `useColorMode()`:
+
+```tsx
+import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
+
+function ThemeToggle() {
+  const { mode, setMode } = useColorMode() // 'light' | 'dark' | 'system'
+  return (
+    <Button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
+      Toggle theme
+    </Button>
+  )
+}
+```
+
+The hook persists choice to `localStorage`, syncs across tabs, and respects `prefers-color-scheme` when set to `'system'`.
+
+## Import paths
+
+Two valid styles:
+
+```tsx
+// Per-component (preferred — smaller bundle, server-component safe):
+import { Button } from '@devalok/shilp-sutra/ui/button'
+import { Card } from '@devalok/shilp-sutra/ui/card'
+
+// Barrel (fine for client-only apps):
+import { Button, Card, Dialog } from '@devalok/shilp-sutra'
+```
+
+A few components are **per-component only** (their barrel was removed in v0.40 because they statically import optional peer deps). These must use the subpath:
+
+- `Toaster`, `toast` → `@devalok/shilp-sutra/ui/toaster`, `/ui/toast`
+- `DatePicker*` → `@devalok/shilp-sutra/composed/date-picker`
+- `EmojiPicker*` → `@devalok/shilp-sutra/composed/emoji-picker`
+- `FilePreview` → `@devalok/shilp-sutra/composed/file-preview`
+- `MarkdownViewer` → `@devalok/shilp-sutra/composed/markdown-viewer`
+- `RichTextEditor*` → `@devalok/shilp-sutra/composed/rich-text-editor`
+- `InputOTP*` → `@devalok/shilp-sutra/ui/input-otp`
+
+## Verify
+
+After install, this should render without errors:
+
+```tsx
+import { Button } from '@devalok/shilp-sutra/ui/button'
+import { Card } from '@devalok/shilp-sutra/ui/card'
+
+export default function Page() {
+  return (
+    <div className="min-h-screen bg-surface-base p-ds-07">
+      <Card className="max-w-md mx-auto p-ds-05">
+        <Button>Hello</Button>
+      </Card>
+    </div>
+  )
+}
+```
+
+If `bg-surface-base` doesn't apply, the CSS import is missing or out of order. The kit's CSS must come **after** `@import "tailwindcss"`.