@devalok/shilp-sutra 0.37.0 → 0.38.0

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.37.0
+> Version: 0.38.0
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a
@@ -39,7 +39,7 @@ pnpm add sonner
 transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
 ```
 
-**Do NOT** import `@devalok/shilp-sutra/tailwind` in a `tailwind.config.ts`. That export is a deprecated no-op stub and logs a dev-mode `console.warn`. It is scheduled for removal in 0.38.
+**Do NOT** import `@devalok/shilp-sutra/tailwind`. That export was removed in 0.38.0. Use the CSS-first setup (`@import "tailwindcss"; @import "@devalok/shilp-sutra/css";`) — no `tailwind.config.ts` is required.
 
 ### Peer dependencies (0.37.0)
 
@@ -220,9 +220,19 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Accordion>
 ```
 
+## Composability
+- Built on Radix Accordion — accepts `value`/`defaultValue`/`onValueChange` matching the `type` discriminated union.
+- **`type="single"`** — value is a string (which item is open). Only one item open at a time. Pair with `collapsible` to allow closing the current item by re-clicking it.
+- **`type="multiple"`** — value is a string[] (which items are open). Multiple can be open at once.
+- **AccordionTrigger chevron:** Inline SVG that auto-rotates via the `data-state` attribute Radix sets (`open` / `closed`). The `chevronPosition` prop controls render order inside the trigger (left / right) — rotation still works from either position.
+- **AccordionContent:** Uses Radix CSS custom properties (`--radix-accordion-content-height`) for open/close height animation. Framer Motion handles the fade. Don't wrap AccordionContent children in additional motion components — doubles the animation.
+- **Inline, not portalled** — parent `overflow: hidden` WILL clip an open accordion. Keep accordions out of tight overflow contexts or use `overflow-visible` on the container.
+
 ## Gotchas
 - type is REQUIRED — omitting it causes runtime error
 - collapsible only works with type="single"
+- Each AccordionItem needs a unique `value` — duplicates silently break toggling
+- Don't put focusable elements inside AccordionTrigger — the trigger IS the focusable button, nested focusables break screen reader navigation
 
 ## Changes
 ### v0.29.0
@@ -246,14 +256,15 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Category: ui
 
 ## Props
-    variant: "subtle" | "filled" | "outline"
+    variant: "subtle" | "solid" | "outline"
     color: "info" | "success" | "warning" | "error" | "neutral"
+    size: "sm" | "md" | "lg"
     title: string (optional)
     onDismiss: () => void (optional, shows X button when provided)
     children: ReactNode (body text)
 
 ## Defaults
-    variant="subtle", color="info"
+    variant="subtle", color="info", size="md"
 
 ## Example
 ```jsx
@@ -262,6 +273,13 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Alert>
 ```
 
+## Composability
+- **Flat, not compound** — unlike Dialog/Card, there's no `<AlertTitle>` / `<AlertDescription>`. Use the `title` prop for the heading and `children` for the body text. This simplifies the API and prevents composition traps (missing title, out-of-order header parts).
+- **Auto-icon by color:** Icon is selected automatically from color (info→circle, success→check, warning→triangle, error→alert). Pass a custom `icon` prop to override.
+- **Role=alert:** Announces assertively to screen readers. Don't stack multiple Alerts in a row — the last one wins.
+- **Dismissal pattern:** Pass `onDismiss` for user-dismissable alerts; the library tracks the exit animation before calling back. For persistent alerts (system state), omit `onDismiss`.
+- **Not for transient messages** — use Toast for transient/time-limited notifications and Banner for page-level announcements. Alert is inline, in-flow, block-level.
+
 ## Gotchas
 - NOT a compound component — use title prop, NOT <AlertTitle>
 - DO NOT use variant="destructive" — use color="error"
@@ -269,6 +287,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) `variant="filled"` deprecated alias. Use `variant="solid"`.
+
 ### v0.31.0
 - **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
 
@@ -329,8 +350,17 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </AlertDialog>
 ```
 
+## Composability
+- Built on Radix AlertDialog — like Dialog but **non-dismissible** by clicking outside or pressing Escape. The user must choose Cancel or Action.
+- Same portal + trigger + asChild pattern as Dialog.
+- `AlertDialogAction` and `AlertDialogCancel` are semantically distinct from generic buttons: they auto-close the dialog on click. Use them even if you wrap them around a styled Button via `asChild` so the close behavior stays wired.
+- **Focus management:** Initial focus lands on `AlertDialogCancel` (the safe default) — destructive confirmation is always one tab away.
+- Use AlertDialog for destructive / irreversible actions; use Dialog for everything else.
+
 ## Gotchas
-- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button
+- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button with `asChild`
+- Do NOT add a close-on-outside-click handler — the non-dismissible behavior is the whole point
+- AlertDialogCancel receives initial focus; don't flip the convention
 
 ## Changes
 ### v0.19.1
@@ -365,8 +395,15 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </AspectRatio>
 ```
 
+## Composability
+- Radix AspectRatio primitive — pure layout wrapper, no context, no cascade.
+- **Child fill pattern:** Its child is absolutely positioned to fill. Pair with `object-cover` / `object-contain` on `<img>`/`<video>` and `w-full h-full` for anything else.
+- Useful as a responsive-image container, a chart area (pair with Chart components), or a placeholder frame for media skeletons.
+- Works inside Card, any layout component, or flex/grid containers — nothing to configure.
+
 ## Gotchas
 - ratio is a number, not a string — use `16/9` not `"16/9"`
+- The child must be size-fluid (`w-full h-full` or absolutely positioned) — elements with intrinsic size escape the aspect-ratio box
 
 ## Changes
 ### v0.1.0
@@ -400,6 +437,13 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 />
 ```
 
+## Composability
+- **Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether "off-list" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).
+- **Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.
+- **FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.
+- **Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.
+- **Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering.
+
 ## Gotchas
 - Allows free-text input (no forced selection) — use Combobox for forced selection
 - value is an object { value, label }, NOT just a string
@@ -452,10 +496,20 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Avatar>
 ```
 
+## Composability
+- **Two internal contexts cascade to AvatarFallback:**
+  - `AvatarSizeContext` — carries the Avatar's `size` so AvatarFallback's font size scales without re-specifying (xs → `text-[9px]`, sm → `text-ds-xs`, md → `text-ds-sm`, lg → `text-ds-md`, xl → `text-ds-lg`)
+  - `AvatarShapeContext` — carries `shape` so AvatarFallback inherits the same border-radius (critical for `shape="square"` / `shape="rounded"` — without context the fallback would always be `rounded-ds-full` regardless of parent)
+- **Status + Ring + Badge are independent** — you can stack all three on one Avatar. They render in separate layers so they don't conflict visually.
+- **Use with AvatarGroup:** AvatarGroup applies its own `size` to children. If your Avatar has an explicit `size`, it overrides AvatarGroup's default — keep it consistent across the group.
+- **AvatarFallback colorSeed:** Deterministic background color from the seed string — identical user IDs produce identical backgrounds across renders. Useful for user-identifying avatars without photos.
+- **Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-raised`. On other backgrounds, add a ring-offset className to compensate.
+
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)
 - Dot size scales automatically with avatar size
 - AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
+- AvatarFallback shape inherits from Avatar (via AvatarShapeContext) — setting `rounded-*` on AvatarFallback directly conflicts with the context
 - Ring offset color matches the surface context — ensure it sits on the expected background
 - Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
 - Online status dot pulses with a CSS animation
@@ -513,6 +567,18 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 <Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
 ```
 
+## Composability
+- **Badge.Group** (BadgeGroup) wraps a set of badges with overflow collapse (`max` + "+N" indicator) and gap control. Use it for filter chips, tag lists, user cluster avatars-equivalent.
+- **Badge.Indicator** (BadgeIndicator) attaches a count / dot overlay to ANY child (icons, avatars, buttons). It's positioning-only — doesn't style the child.
+- **Interactive modes:**
+  - `onClick` alone → renders as `<button>` (standard interactive badge)
+  - `onDismiss` alone → renders as `<span>` with an inner X button
+  - Both → renders as `<div role="button">` (avoids invalid nested buttons) — the X button inside handles its own click isolation
+- **asChild:** Use with router Links for nav-style badges (`<Badge asChild><Link href="/tags/react">React</Link></Badge>`).
+- **Custom colors via CSS variables:** Set `color="custom"` + inline style `style={{ '--badge-color': '#...' }}`. For solid variant, also set `--badge-fg-color` for the foreground.
+- **Icon slots auto-size via IconProvider** — same cascade as Button. Don't set explicit size on nested `<Icon>`.
+- **Chip (deprecated)** was merged into Badge — use Badge with `onClick` and `selected` for the old Chip use case.
+
 ## Gotchas
 - DO NOT use variant="destructive" — use variant="solid" color="error"
 - Badge is now interactive when `onClick` is provided (renders as `<button>`)
@@ -587,6 +653,13 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 {/* Renders: React, TypeScript, Tailwind, +2 */}
 ```
 
+## Composability
+- **Wrapper for Badge children** — doesn't style children, just lays them out and optionally collapses overflow into a "+N" indicator.
+- **Server-safe** — can render in RSC trees (children still need to be server-safe themselves).
+- **Overflow indicator is a Badge** — picks `variant="outline" color="neutral"` and the `size` prop on BadgeGroup. Child badges keep their own variant/color/size.
+- **Click-to-reveal pattern:** Pair `onOverflowClick` with a Popover / Sheet / Dialog that shows the full list. Without the handler, the overflow badge is inert (decorative count).
+- Doesn't accept arbitrary children — only Badges. Non-Badge children render but may look off (no gap rhythm matching).
+
 ## Gotchas
 - Overflow badge is always `variant="outline" color="neutral"`
 - `size` only applies to the overflow badge — child badges keep their own size
@@ -627,6 +700,13 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Badge.Indicator>
 ```
 
+## Composability
+- **Overlay wrapper** — takes any child and overlays a positioned count/dot at the specified corner. The child must be inline-friendly (anything that renders in a span-wrapped position: relative context).
+- **Common pairings:** IconButton (notification bell with count), Avatar (online presence dot), Button (cart with item count), tabs (unread indicator).
+- **Invisible for layout stability:** Use `invisible={true}` to keep the child's position consistent when the badge should disappear — avoids layout shift as counts appear/disappear.
+- **showZero vs hide-on-zero:** By default `count={0}` hides the indicator. Set `showZero={true}` for use cases where "zero" is meaningful (scores, pending items that should display 0 explicitly).
+- **Dot vs count:** `dot={true}` is a presence-only pulse indicator (online, new activity); count is a numeric badge. They're mutually exclusive — setting both uses dot.
+
 ## Gotchas
 - Wraps children in `position: relative` span — the indicator is absolutely positioned
 - Animation uses spring physics, respects `prefers-reduced-motion`
@@ -645,7 +725,6 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Props
     color: "info" | "success" | "warning" | "error" | "neutral"
     actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
-    action: ReactNode (DEPRECATED — use `actions` instead)
     onDismiss: () => void (optional, shows X button)
     children: ReactNode (message text)
 
@@ -659,12 +738,22 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Banner>
 ```
 
+## Composability
+- **Banner vs Alert vs Toast:** Banner is full-width, top-of-page / top-of-region announcements (maintenance, quota, trial-expiring). Alert is inline in-flow. Toast is transient floating notifications. Pick by where the message lives in the visual hierarchy.
+- **actions slot:** Pass one or more `<Button>` elements — the container flex-wraps on narrow viewports so actions drop below the message rather than squeezing horizontally.
+- **Role=alert** announces assertively. Same constraint as Alert — don't stack multiple Banners.
+- **Dismissal timing:** `onDismiss` fires AFTER the exit animation completes, not on click. Use it to remove the banner from state only after it's visually gone.
+- Works inside Shell layouts (TopBar / Sidebar / main content) — usually sits above main content, below the TopBar.
+
 ## Gotchas
 - Banner is full-width (spans container). Alert is inline.
 - Renders role="alert" automatically
 - `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated singular `action` prop. Use `actions={[...]}` (plural).
+
 ### v0.20.0
 - **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
 - **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)
@@ -706,8 +795,16 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 </Breadcrumb>
 ```
 
+## Composability
+- **Compound structure only** — no context cascade, each part is standalone. The semantic shape (`<nav>` → `<ol>` → `<li>`) is what matters for a11y, not any internal state.
+- **BreadcrumbLink vs BreadcrumbPage:** Use BreadcrumbLink for everything except the current page; BreadcrumbPage for the current page (not clickable, renders without href, announced as "current page" via aria-current).
+- **Router integration:** Use `<BreadcrumbLink asChild><NextLink href="/x">...</NextLink></BreadcrumbLink>` (Radix Slot pattern).
+- **Truncation:** For long paths, use BreadcrumbEllipsis between the first and last items instead of showing all. Pair with a DropdownMenu (open the ellipsis to show hidden intermediate items) if you need to expose them.
+- **PageHeader (composed) auto-builds Breadcrumb** from its `breadcrumbs` prop — use that higher-level component for page-top breadcrumbs and save this component for inline or custom positioning.
+
 ## Gotchas
 - Use BreadcrumbPage for the current (non-clickable) page, BreadcrumbLink for navigable items
+- Don't wrap BreadcrumbPage in a link — it's the current location by definition
 
 ## Changes
 ### v0.18.0
@@ -751,6 +848,15 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 <Button variant="soft" color="warning" size="compact-sm" shape="pill">Overdue</Button>
 ```
 
+## Composability
+- **ButtonGroup context consumption:** When nested inside `<ButtonGroup>`, Button auto-inherits variant/color/size/weight/shape/disabled. Explicit props on the individual Button override. The context also drives position-aware border-radius (first/middle/last within an attached group).
+- **IconProvider cascade:** Icons in `startIcon`/`endIcon` auto-size via IconProvider per the button size (xs→sm, sm→sm, md→md, lg→md, icon-xs→xs, icon-lg→lg). Don't pass explicit `size` to `<Icon>` inside Button.
+- **asChild for router links:** `<Button asChild><Link href="/foo">...</Link></Button>` transfers Button's styling to the Link while preserving navigation semantics. Required for Next.js `<Link>` / react-router `<Link>`.
+- **onClickAsync state machine:** Overrides onClick. Auto-cycles `idle → loading (aria-busy, spinner) → success (checkmark) → idle` on resolve; `loading → error (X mark) → idle` on reject. Duration controlled by `asyncFeedbackDuration` (1500ms default). Auto-activates `processing='working'` during loading — marching-ants border keeps users visually aware.
+- **Processing vs loading:** `loading` is a short async state (shows spinner, blocks clicks). `processing` is a longer-running state (marching ants border, may or may not block clicks based on `processingDisabled`). Use onClickAsync for simple request cases; use processing explicitly for long-running background operations.
+- **DevalokGrain children:** Grain elements are auto-extracted and rendered as direct button children for absolute positioning — lets you layer grain texture on solid-variant buttons without breaking layout.
+- **Prefer `variant="soft"` over `variant="outline"` for secondary actions** (see Gotchas for details). This is a design-system-wide convention.
+
 ## Gotchas
 - **Prefer `variant="soft"` over `variant="outline"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-raised bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.
 - DO NOT use variant="destructive" — use variant="solid" color="error"
@@ -816,24 +922,44 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 - Category: ui
 
 ## Props
-    variant: ButtonProps['variant'] (propagated to children)
+    variant: ButtonProps['variant'] (propagated to children via context)
     color: ButtonProps['color'] (propagated to children)
     size: ButtonProps['size'] (propagated to children)
-    orientation: "horizontal" | "vertical" (default: "horizontal")
+    weight: ButtonProps['weight'] (propagated to children)
+    shape: ButtonProps['shape'] (propagated to children)
+    disabled: boolean (propagates to all children)
+    orientation: "horizontal" | "vertical"
+    attached: boolean (true = buttons visually merge with shared borders; false = spaced apart via gap)
+    fullWidth: boolean (group stretches to parent width; children stretch equally)
 
 ## Defaults
-    orientation="horizontal"
+    orientation="horizontal", attached=true
 
 ## Example
 ```jsx
 <ButtonGroup variant="outline" size="sm">
   <Button>Bold</Button>
   <Button>Italic</Button>
+  <Button>Underline</Button>
+</ButtonGroup>
+
+{/* Spaced, not attached */}
+<ButtonGroup attached={false} variant="soft">
+  <Button>Save</Button>
+  <Button>Cancel</Button>
 </ButtonGroup>
 ```
 
+## Composability
+- Every Button child reads variant/color/size/weight/shape/disabled from ButtonGroup context. Explicit props on individual children override context.
+- **Position-aware border radius:** Child Buttons read their position in the group (first / middle / last) and apply appropriate corner radii inline. Works for both horizontal and vertical orientations.
+- **Focus z-index isolation:** The focused button rises above its siblings so the focus ring isn't clipped by adjacent borders.
+- **Tonal dividers:** For solid/soft/ghost variants without visible borders, ButtonGroup injects subtle divider elements between children.
+- **Works with SplitButton:** `<SplitButton>` inside a `<ButtonGroup>` inherits the same context and position rules.
+
 ## Gotchas
-- Children can override variant/size individually
+- Children can override variant/size individually — context is a default, not a lock
+- `attached={false}` disables the position-aware border radius (children use their default corners)
 
 ## Changes
 ### v0.33.0
@@ -862,6 +988,11 @@ Internal component that renders the processing animation overlay for Button. Con
 
 See `Button` docs for the public API.
 
+## Composability
+- **Internal only — do NOT import or use directly.** The Button component owns the lifecycle of this overlay.
+- Drives Button's `processing` prop rendering. If you're building a custom button and want similar marching-ants feedback, copy the SVG/animation pattern — don't reach into this component.
+- Listed here for reference so consumers grep'ing for "processing" find the behavior origin.
+
 ## Changes
 ### v0.29.0
 - **Added** Initial release — marching ants processing overlay (SVG dashed rect with animated stroke-dashoffset). Speed tiers: ambient (3s), working (2s), urgent (1s). Color maps to step-11 tokens for visibility on all variants.
@@ -873,18 +1004,22 @@ See `Button` docs for the public API.
 
 ## Props
     variant: "default" | "elevated" | "outline" | "flat"
+    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" (border accent color)
+    size: "sm" | "md" | "lg" (padding — propagated to CardHeader/CardContent/CardFooter via context)
     interactive: boolean (enables hover shadow lift + pointer cursor)
+    accent: "left" | "top" | "right" | "bottom" (render a colored accent bar on the specified edge)
+    accentColor: "default" | "accent" | "error" | "success" | "warning" | "info" (color of the accent bar; default maps to accent-9)
 
 ## Compound Components
     Card (root)
-      CardHeader
+      CardHeader      ← inherits size from Card context
         CardTitle
         CardDescription
-      CardContent
-      CardFooter
+      CardContent     ← inherits size from Card context
+      CardFooter      ← inherits size from Card context
 
 ## Defaults
-    variant="default"
+    variant="default", color="default", size="md"
 
 ## Example
 ```jsx
@@ -897,8 +1032,16 @@ See `Button` docs for the public API.
 </Card>
 ```
 
+## Composability
+- **Size cascades through context** — Card's `size` prop sets padding on CardHeader, CardContent, and CardFooter via `CardSizeContext`. Don't set padding classes on sub-components directly; override via `className` if needed.
+- **Not a compound state machine** — Card, CardHeader, CardTitle, etc. are purely structural. No open/close state.
+- **Accent bar is independent:** The `accent` / `accentColor` props render a decorative colored edge bar (absolutely positioned, `aria-hidden`). Works alongside `color` (which tints the border) — the two can stack for layered emphasis.
+- **Interactive cards:** Set `interactive={true}` + `onClick` for clickable cards (entire surface becomes the button). Add `aria-label` on the Card root when there's no visible heading. For complex multi-action cards, prefer standard Card with explicit buttons inside.
+- **ContentCard (composed)** is a higher-level wrapper with built-in header/footer slots and title/actions — use it for list-row-style cards; use Card directly for custom layouts.
+
 ## Gotchas
 - Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
+- Don't override CardHeader/CardContent/CardFooter padding via className if you want the size cascade to work — set size on Card instead
 
 ## Changes
 ### v0.31.0
@@ -947,9 +1090,18 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 <BarChart data={salesData} />
 ```
 
+## Composability
+- **ChartContainer wraps all chart primitives** — provides responsive sizing (fills parent width, configurable aspect ratio) and a consistent background/padding. Always render charts inside a ChartContainer unless you're building a custom container.
+- **Legend is a sibling, not a child** — render `<Legend items={...} />` next to your chart (above/below), not nested. Use `onHover` / `onClick` handlers in Legend + chart to sync hover highlights.
+- **Data shape is chart-specific** — BarChart wants `[{ label, value }]`, LineChart wants `[{ x, y, series }]`, etc. Each chart's props doc spells out the shape; don't assume cross-chart compatibility.
+- **Sparkline is the only chart safe to use inline** — it's a minimal 1-line SVG, no axes, no legend. Use it inside StatCard, tables, tight cells. For anything larger, reach for the full chart types.
+- **Entrance animations** — all charts use Framer Motion spring-based entry. Animations respect `prefers-reduced-motion`.
+- **Accessibility:** Charts render role="img" with aria-label from the chart title. For dense data, provide a hidden accessible table fallback manually (WCAG requirement for complex charts).
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/charts`, NOT the `ui` barrel
 - Requires D3 as an optional peer dependency
+- Chart components do NOT auto-generate accessible data tables — add one manually for WCAG compliance on complex charts
 
 ## Changes
 ### v0.18.0
@@ -1161,6 +1313,15 @@ Animated bouncing dots with a text description of who is typing.
 
 ---
 
+## Composability
+- **Chat is a kit of 7 primitives, not a monolithic ChatWindow.** Compose MessageList (scroll container) + Message/SystemMessage (row variants) + DateSeparator/UnreadSeparator (visual dividers) + MessageInput (composer) + TypingIndicator (presence).
+- **Message is a compound component** — `Message.Avatar`, `Message.Content`, `Message.Author`, `Message.Body`, `Message.Reactions`, `Message.Actions`, `Message.Action`. Arrange them to match your design; most layouts only need Avatar + Content (with Author + Body inside).
+- **Message.Actions reveal on hover** via `group-hover/message` — ONLY works when Actions is nested inside a Message root. If you want a custom action bar, do it differently.
+- **MessageList ARIA:** `role="log" + aria-live="polite"` — screen readers announce new messages automatically. Don't manually add aria-live to children.
+- **grouped mode:** For consecutive messages from the same user, set `grouped={true}` to hide the avatar and author (typical chat UI pattern). Logic for "same user as previous" is consumer-side.
+- **MessageInput is specifically for chat** — auto-resizing textarea (up to 160px), Enter-to-send, Shift+Enter-for-newline, streaming support. For richer composition (formatting, attachments), use RichChatInput from composed (built on top of this + TipTap).
+- **TypingIndicator** accepts multiple users — handles pluralization of the "is/are typing" label automatically.
+
 ## Gotchas
 - MessageList uses `role="log"` with `aria-live="polite"` — screen readers announce new messages
 - Message entrance animations use Framer Motion springs — AnimatePresence wraps children in MessageList
@@ -1183,20 +1344,34 @@ Animated bouncing dots with a text description of who is typing.
 ## Props
     checked: boolean | "indeterminate"
     onCheckedChange: (checked: boolean | "indeterminate") => void
+    size: "sm" | "md" | "lg"
     error: boolean (shows red border)
     indeterminate: boolean (overrides checked, shows dash icon)
     disabled: boolean
 
 ## Defaults
-    none
+    size="md"
 
 ## Example
 ```jsx
 <Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
+
+{/* With label */}
+<label htmlFor="terms" className="flex items-center gap-ds-02">
+  <Checkbox id="terms" checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
+  I agree to the terms
+</label>
 ```
 
+## Composability
+- **FormField integration:** Unlike Input/Textarea, Checkbox does NOT auto-consume FormField state — the `error` prop must be set explicitly. (Form-library convention differs for checkboxes since they often don't share the same visual grouping.)
+- **Labels:** Checkbox doesn't carry its own label — pair it with `<Label htmlFor="x" />` + `<Checkbox id="x" />`, or wrap both in a `<label>` element. Screen readers rely on that association.
+- **Controlled vs uncontrolled:** Pass `checked` + `onCheckedChange` for controlled, `defaultChecked` for uncontrolled. Don't mix.
+
 ## Gotchas
 - indeterminate overrides checked visually
+- Checkbox does NOT auto-consume FormField error state — pass `error` explicitly if using inside a FormField
+- WCAG 2.5.8 minimum target size met at md (24px); sm (20px) may fail if not paired with enough label hit area
 
 ## Changes
 ### v0.22.0
@@ -1229,8 +1404,15 @@ Animated bouncing dots with a text description of who is typing.
 <Code variant="block">{`const x = 1;\nconsole.log(x);`}</Code>
 ```
 
+## Composability
+- **Server-safe.** No context, no cascade.
+- Inline variant composes inside Text, paragraphs, list items, table cells — wherever body text goes.
+- Block variant is a `<pre><code>` pair with overflow-x scroll; pair with a dark background Card or MarkdownViewer for long snippets.
+- Not a syntax-highlighted code viewer — for that, use RichTextEditor's code block or a dedicated library. Code here is typographic emphasis, not lexer-aware rendering.
+
 ## Gotchas
 - "block" renders as `<pre><code>`, "inline" renders as `<code>`
+- Block variant doesn't syntax-highlight — it's a styled pre tag, nothing more
 
 ## Changes
 ### v0.1.1
@@ -1265,8 +1447,17 @@ Animated bouncing dots with a text description of who is typing.
 </Collapsible>
 ```
 
+## Composability
+- Radix Collapsible primitive — smaller than Accordion (no grouping/value matching, just open/close).
+- **When to use:** A single show/hide section where the state is local (e.g. "Advanced options" inside a form, expandable row detail, show-more). For multi-section with mutual exclusion, use Accordion.
+- **Inline rendering:** CollapsibleContent is NOT portalled — it expands inline and pushes sibling content down. Respects `overflow` rules of the parent.
+- **No built-in chevron** — unlike AccordionTrigger, CollapsibleTrigger is bare. Add your own icon + rotate via `data-state` attribute Radix sets (`[data-state=open]:rotate-180`).
+- **Animation:** Height transition via `animate-collapsible-down/up` keyframes + Radix `--radix-collapsible-content-height` CSS custom property.
+
 ## Gotchas
 - Standard Radix Collapsible API
+- No auto-chevron — add one manually if you want the affordance
+- Not portalled — clipped by parent `overflow: hidden`
 
 ## Changes
 ### v0.13.0
@@ -1341,6 +1532,14 @@ Animated bouncing dots with a text description of who is typing.
 <ColorInput value={color} onChange={setColor} showPicker={false} />
 ```
 
+## Composability
+- **Built on Popover internally** — trigger opens a portal-rendered picker panel. z-popover (1400) stacking.
+- **variant="default" vs "inline":** Default variant is an input-style trigger with gradient swatch + hex label (fits in forms). Inline variant IS the selected color — the entire trigger takes the color as its background with contrast-aware text. Use inline for color-tags in chat, lists, or tight toolbar UIs.
+- **Controlled or uncontrolled:** Works both ways — pass `value` + `onChange` for controlled, or omit and let internal state track.
+- **Presets are compositional:** Pass `{ hex, label }[]` for named brand colors (accessible, keyboard-navigable). Pass `false` to hide the preset strip entirely (picker-only mode).
+- **react-colorful** is bundled (2.8KB gzipped) — zero additional setup. Picker itself is pointer-based; keyboard users edit via the HEX/RGB/HSL format inputs below.
+- **FormField:** Not auto-consumed (no `state` prop). Wrap in FormField for label + helper text; style error visuals via className.
+
 ## Gotchas
 - Value must be a 6-character hex string (e.g. "#d33163")
 - Presets accept both `string[]` (backward-compatible) and `{ hex, label }[]` (recommended for accessibility)
@@ -1391,6 +1590,13 @@ Animated bouncing dots with a text description of who is typing.
 <ColorSwatch color="oklch(0.7 0.15 200)" shape="rounded" />
 ```
 
+## Composability
+- **Server-safe, decorative-only primitive.** Accepts any valid CSS color string — hex, rgb, oklch, hsl, named. Pure presentation, no context.
+- **Usage patterns:** Inline color marker next to a label, preview dot in lists, color-indicator in a category chip, legend swatch for charts.
+- **`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-raised backgrounds.
+- **Interactive color picking:** Use ColorInput (which opens a full picker). ColorSwatch is display-only.
+- No IconProvider cascade, no FormField consumption — composes freely with anything.
+
 ## Gotchas
 - Color is applied via inline `backgroundColor` style, not a token class — accepts any runtime CSS color string
 - Renders `role="presentation"` — purely decorative, not interactive
@@ -1402,6 +1608,7 @@ Animated bouncing dots with a text description of who is typing.
 
 ## Props
     options: ComboboxOption[] (REQUIRED) — { value: string, label: string, description?: string, icon?: ReactNode, disabled?: boolean }
+    size: "xs" | "sm" | "md" | "lg" (trigger height)
     DISCRIMINATED UNION — type depends on `multiple` flag:
     Single (default): multiple?: false, value?: string, onValueChange: (value: string) => void
     Multiple: multiple: true, value?: string[], onValueChange: (value: string[]) => void
@@ -1409,13 +1616,14 @@ Animated bouncing dots with a text description of who is typing.
     searchPlaceholder: string (default: "Search...")
     emptyMessage: string (default: "No results found")
     disabled: boolean
-    triggerClassName: string
+    className: string (wrapper div — the positioning container, NOT the trigger)
+    triggerClassName: string (the actual Popover trigger button)
     accessibleLabel: string (custom aria-label for trigger, falls back to placeholder)
     maxVisible: number (default: 6, max dropdown items before scroll)
     renderOption: (option, selected) => ReactNode
 
 ## Defaults
-    placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
+    size="md", placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
 
 ## Example
 ```jsx
@@ -1428,9 +1636,20 @@ Animated bouncing dots with a text description of who is typing.
 />
 ```
 
+## Composability
+- **Combobox vs Autocomplete vs Select:** Combobox = typeahead search + forced selection (the user picks from filtered options). Autocomplete = typeahead + free text allowed. Select = no typeahead, click-to-open with fixed options. Pick by user behavior, not visual style.
+- **Single vs multi mode** is a discriminated union — `multiple: true` changes the shape of value (`string[]`) and onValueChange. TypeScript enforces the pairing.
+- **Multi-select pills:** Capped at 2 visible + "+N more" overflow regardless of `maxVisible`. Clicking the +N opens a popover list of all selected items (handled by the component).
+- **className vs triggerClassName:** className lands on the wrapper (positioning); triggerClassName lands on the trigger button (styling the control). Know which you need.
+- **Portal + z-popover (1400):** content stacks above Dialog/Sheet; works inside scrolling containers without clipping.
+- **renderOption:** For complex option rendering (avatar + label + description), pass `renderOption: (option, selected) => <YourCustom />`. The selected state is a boolean flag.
+- **FormField:** Does NOT auto-consume FormField state. Wrap in FormField for label + helper text, but style error manually.
+
 ## Gotchas
 - Enforces selection from list (unlike Autocomplete which allows free text)
-- In multi mode, selected items appear as pills with "+N more" overflow
+- In multi mode, selected items appear as pills with "+N more" overflow (capped at 2 visible pills regardless of `maxVisible`)
+- `className` vs `triggerClassName`: `className` lands on the wrapper div (useful for width/positioning); `triggerClassName` lands on the actual Popover trigger button (useful for styling the control itself)
+- Dropdown content is portalled to document.body — parent styles like `overflow: hidden` don't clip it, and container-scoped test queries won't find it
 
 ## Changes
 ### v0.18.0
@@ -1468,8 +1687,19 @@ Animated bouncing dots with a text description of who is typing.
 </Container>
 ```
 
+## Composability
+- **Server-safe layout primitive.** Safe in RSC trees — no hooks, no context.
+- **maxWidth choices:**
+  - `"default"` (standard page container — matches the design system's layout grid)
+  - `"body"` (narrower reading width — use for article/blog content)
+  - `"full"` (no max — edge-to-edge, useful for full-bleed marketing sections)
+- **Polymorphic via `as`:** Change the rendered element for semantics (`as="main"` for page content, `as="section"` for major subdivisions, `as="article"` for standalone content).
+- **mx-auto centering is automatic** — Container handles horizontal centering; it does NOT add vertical spacing. Pair with `py-*` utility classes on the Container itself or inside it.
+- Nothing cascades — nesting Containers is fine but rarely useful (max-width constraints compound).
+
 ## Gotchas
 - Server-safe component — can be imported directly in Next.js Server Components
+- Container does NOT add vertical padding — add it explicitly via className if needed
 
 ## Changes
 ### v0.1.0
@@ -1505,8 +1735,16 @@ Animated bouncing dots with a text description of who is typing.
 </ContextMenu>
 ```
 
+## Composability
+- Radix ContextMenu — same item-variant surface as DropdownMenu (checkbox, radio group, sub-menus, label, separator) with the same keyboard model. Swap `Dropdown` → `Context` in imports and everything behaves the same.
+- **Trigger is not a button** — ContextMenuTrigger is a wrapper element (defaults to `<div>`) that listens for `contextmenu` events on itself and children. Use `asChild` to pass styling to your own element.
+- **Touch support:** Radix maps long-press to right-click. On mobile, hold-to-open just works without extra code.
+- **No visible trigger affordance** — unlike DropdownMenu/Popover, the user has to *know* the element is right-clickable. Pair with a visible hint (keyboard shortcut label, menu icon elsewhere) for discoverability.
+- **Portal + z-index:** z-popover (1400).
+
 ## Gotchas
 - Triggered by right-click (or long-press on touch devices)
+- ContextMenuTrigger doesn't auto-indicate it's interactive — add visual affordance elsewhere on the page
 
 ## Changes
 ### v0.18.0
@@ -1574,6 +1812,30 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 />
 ```
 
+## Composability
+**Server vs client mode is prop-driven, not explicit.**
+- Pass `onSort` → server-side sort (manual, rows stay in data order — you're responsible for re-fetching).
+- Pass `pagination` object → server-side pagination (manual, pass total count).
+- Omit both → client-side sort/pagination via TanStack react-table.
+- Mix-and-match: `onSort` + no pagination = server sort + client pagination.
+
+**Companion components:**
+- `DataTableToolbar` — enabled via `toolbar={true}`. Provides column visibility, density switcher, CSV export. Reads table state via `DataTableContext` (internal). Rendered ABOVE the table automatically.
+- `BulkActionBar` (floating) — appears when rows are selected AND `bulkActions` array is non-empty. Synced with `selectedIds`; shows count + action buttons.
+- `EmptyState` from `@devalok/shilp-sutra/composed` — pass to `emptyState` prop. Takes precedence over `noResultsText` string.
+
+**Controlled selection:**
+- Pass `selectedIds` (Set<string>) + `onSelectionChange` for controlled row selection.
+- Provide `getRowId: (row) => row.id` so selection survives data refetches (otherwise TanStack uses array index, which breaks on sort/filter).
+- `selectableFilter: (row) => boolean` disables selection on specific rows (e.g. archived items).
+
+**Row click model:**
+- `onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements.
+
+**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height.
+
+**Density integration:** `defaultDensity="compact"` is the Karm-style dense mode (h-9 rows). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only.
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table`, NOT the `ui` barrel
 - Requires @tanstack/react-table and @tanstack/react-virtual as peer dependencies
@@ -1582,6 +1844,7 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - selectedIds syncs via useEffect — provide getRowId for custom row IDs
 - onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
 - Use defaultDensity="compact" for Karm-style h-9 rows
+- `virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization
 
 ## Changes
 ### v0.29.0
@@ -1620,6 +1883,10 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the tbody + rows for DataTable. Consumes DataTableContext for row data, selection state, expandable state, loading skeletons.
+- Customization routes through DataTable props: `renderExpanded`, `onRowClick`, `getRowId`, `loading`, `emptyState`.
+
 ## Changes
 
 ### v0.32.0
@@ -1633,6 +1900,10 @@ See [DataTable](./data-table.md) for the public API.
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the floating bulk-action bar that appears when rows are selected. Reads selection state + bulkActions config from DataTableContext.
+- Customization goes through DataTable's `bulkActions` prop — `{ label, onClick, color?, disabled? }[]`.
+
 ## Changes
 
 ### v0.32.0
@@ -1646,6 +1917,10 @@ See [DataTable](./data-table.md) for the public API.
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the card wrapper around DataTable (border, shadow, rounded corners matching the Card primitive's surface treatment).
+- DataTable uses this automatically — no consumer-facing prop toggles it.
+
 ## Changes
 
 ### v0.32.0
@@ -1659,6 +1934,10 @@ See [DataTable](./data-table.md) for the public API.
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal React context** — binds DataTable's sub-components (header, body, pagination, toolbar, bulk-actions) to shared state: TanStack table instance, density, selection, loading.
+- Consumer code never reads this context — all interaction goes through DataTable's props.
+
 ## Changes
 
 ### v0.32.0
@@ -1672,6 +1951,10 @@ See [DataTable](./data-table.md) for the public API.
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the thead + column headers for DataTable. Reads sort state + column definitions from DataTableContext.
+- Customization goes through DataTable's `columns` prop (column definitions are TanStack ColumnDef<TData> — header, sortable, filter, etc. all declared there).
+
 ## Changes
 
 ### v0.32.0
@@ -1685,6 +1968,10 @@ See [DataTable](./data-table.md) for the public API.
 This component is used internally by `<DataTable>` and should not be imported directly.
 See [DataTable](./data-table.md) for the public API.
 
+## Composability
+- **Internal only.** Renders the pagination footer for DataTable. Reads pagination state from DataTableContext.
+- Customization goes through DataTable's `pagination` prop (server-side: pass `{ page, pageSize, total, onPageChange }`) or `pageSize` + `paginated` (client-side).
+
 ## Changes
 
 ### v0.32.0
@@ -1722,10 +2009,17 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 />
 ```
 
+## Composability
+- **Companion to DataTable** — typically enabled via DataTable's `toolbar={true}` prop (which auto-renders this internally). Use DataTableToolbar directly only if you're building a custom DataTable integration that needs the toolbar positioned/styled differently.
+- **Reads table state via the `table` instance** (TanStack react-table) — you must pass it. For the auto-rendered version inside DataTable, this wiring is automatic.
+- **Feature toggles:** `globalFilter` (search across all columns), density switcher (compact/standard/comfortable row heights), CSV export. Turn each on/off independently.
+- **Density changes are runtime** — the switcher writes to the same `defaultDensity` that DataTable's prop seeds. State lives in DataTable context.
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table-toolbar`, NOT the `ui` barrel
 - Companion to DataTable — provides column visibility, density toggle, and CSV export controls
 - Requires @tanstack/react-table as a peer dependency
+- Prefer DataTable's `toolbar={true}` prop over rendering this directly
 
 ## Changes
 ### v0.5.0
@@ -1776,6 +2070,14 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 </div>
 ```
 
+## Composability
+- **Brand texture overlay** — drops into any parent with `relative overflow-hidden isolate`. Auto-inherits the parent's border radius.
+- **Button auto-extracts Grain children** — if you nest `<DevalokGrain>` inside a `<Button>`, Button auto-separates it from the label slot and positions it correctly. No extra wrapping needed.
+- **Card, custom hero sections, landing-page tiles** — wrap in a positioned container (or add the `relative overflow-hidden isolate` classes to Card explicitly) and drop Grain in as a sibling to your content.
+- **z-layer contract:** Grain renders at `z-[1]`. Content on top needs `z-[2]+`. The component doesn't boost child z-index — that's consumer responsibility.
+- **`hoverIntensify` depends on parent** — the parent must have the Tailwind `group` class so `group-hover:` selectors apply. Forgetting this silently disables the effect.
+- **Tint composes with surface:** Pass an OKLCH color (or CSS variable reference like `var(--color-accent-9)`) to `tint` for a directional gradient on top of the noise. Without tint, just noise.
+
 ## Gotchas
 - Parent element MUST have `relative overflow-hidden isolate` for the grain to render correctly
 - The grain layers are absolute-positioned at `z-[1]` — content that should appear above must use `z-[2]` or higher
@@ -1825,8 +2127,18 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 </Dialog>
 ```
 
+## Composability
+- Built on Radix Dialog primitives — every standard Radix prop passes through (`open`, `onOpenChange`, `defaultOpen`, `modal`).
+- **Trigger composition:** `<DialogTrigger asChild>` renders the wrapped element as the trigger — typical pattern is `<DialogTrigger asChild><Button>...</Button></DialogTrigger>`. Without `asChild`, a default button is injected.
+- **Portal rendering:** DialogContent portals to `document.body`. CSS containers (`overflow: hidden`, `transform`, stacking contexts) on ancestors of the trigger don't clip it. Container-scoped test queries miss portalled content — use `screen` or the portal root.
+- **Focus management:** Radix traps focus inside Content while open and restores it to the trigger on close. First focusable element inside receives focus automatically.
+- **Imperative close** from deep children: use `<DialogClose asChild>` around your own button, or `useDialogContext` — no prop drilling.
+- **z-index:** DialogContent uses `z-dialog` (configured in Tailwind theme). Nested overlays (Popover inside Dialog) stack on top because Popover uses `z-popover` (1400) higher than `z-dialog`.
+
 ## Gotchas
 - DialogTitle is required for accessibility — screen readers announce it when the dialog opens
+- If your layout suppresses the title visually, use `<VisuallyHidden>` around DialogTitle — don't omit it
+- Focus returns to the trigger on close — if the trigger is conditionally unmounted, focus lands on body; handle manually if that matters
 
 ## Changes
 ### v0.19.1
@@ -1875,8 +2187,18 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 </DropdownMenu>
 ```
 
+## Composability
+- Radix DropdownMenu underneath — same prop surface (`open`, `onOpenChange`, `defaultOpen`, `modal`).
+- **Item variants** stack cleanly: `DropdownMenuCheckboxItem` for multi-select toggles, `DropdownMenuRadioGroup` + `DropdownMenuRadioItem` for single-select, `DropdownMenuSub` + `DropdownMenuSubTrigger/SubContent` for nested submenus. Each has its own keyboard model pre-wired.
+- **Keyboard:** Arrow keys navigate items, Enter/Space activates, Esc closes, typeahead jumps to first letter. All handled by Radix — don't re-implement.
+- **Trigger:** `<DropdownMenuTrigger asChild>` around any button. IconButton is the common pairing.
+- **Shortcut hints:** `<DropdownMenuShortcut>` inside an item renders a right-aligned `⌘K`-style kbd. Visual only — does NOT bind the shortcut globally.
+- **Closing from a handler:** Item onSelect auto-closes the menu by default. Pass `event.preventDefault()` inside the handler to keep it open (e.g. for checkbox items that shouldn't close on toggle).
+
 ## Gotchas
 - Use `asChild` on DropdownMenuTrigger to render your own button element
+- DropdownMenuShortcut is decorative — bind keyboard shortcuts separately (e.g. with `useHotkeys`)
+- Sub-menus need BOTH DropdownMenuSubTrigger (visible item) and DropdownMenuSubContent (the submenu panel) — missing either silently breaks the hover-open behavior
 
 ## Changes
 ### v0.22.0
@@ -1924,9 +2246,17 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 />
 ```
 
+## Composability
+- **Two modes, one component:** `compact={false}` (default) = drag-and-drop zone with visible affordance; `compact={true}` = inline "Upload" button. Swap by prop, same callback.
+- **Progress integration:** Drive `uploading` + `progress` from your upload logic. The component renders an embedded Progress bar when uploading=true.
+- **Validation is built-in:** `accept` (MIME types / extensions) + `maxSize` are enforced before `onFiles` fires. Invalid files produce `error` state instead of calling through. Your onFiles never has to re-validate.
+- **Multi-file:** `multiple={true}` accepts File[] (array always, even for single-file mode — use `files[0]`).
+- **Composes with Toast for feedback:** Pair with toast.success on upload complete, toast.error on failure.
+
 ## Gotchas
 - compact=true renders a small inline button; false (default) renders a large drag-and-drop zone
 - Client-side validation: invalid files are rejected before onFiles is called
+- `onFiles` always receives an array — use `files[0]` even when `multiple={false}`
 
 ## Changes
 ### v0.1.0
@@ -1964,10 +2294,31 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 </FormField>
 ```
 
+## Composability
+The FormField/useFormField pair is the central a11y wiring pattern. Components that consume it automatically become accessible inside a FormField without any explicit ARIA work on your end.
+
+**FormField cascades through context to:**
+- **Input, Textarea, NumberInput, InputOTP** — auto-receive `aria-describedby` (wired to FormHelperText's id), `aria-invalid` (when state="error"), and `aria-required` (when required=true).
+- **FormHelperText** — auto-reads `state` and `helperTextId` from context; renders `role="alert"` on error so screen readers interrupt.
+- **Label** — pair it with an Input via `htmlFor` / `id` in the normal way; FormField doesn't auto-wire labels (labels need the explicit association to satisfy screen readers reliably).
+
+**Explicit props always override context.** Setting `state="error"` on an Input inside a FormField with `state="helper"` makes only that Input look errored.
+
+**Nesting is NOT supported.** Don't nest FormField inside FormField — only the outermost context wins, and some a11y wiring silently breaks.
+
+**Consuming context in your own components:**
+```tsx
+const field = useFormField()  // returns { state, helperTextId, required } or undefined
+// Thread field?.state onto your control's state prop,
+// and field?.helperTextId onto aria-describedby.
+```
+
 ## Gotchas
 - getFormFieldA11y() was REMOVED — use useFormField() hook instead
 - FormHelperText auto-reads state and id from FormField context
 - FormHelperText renders role="alert" when state="error"
+- Don't nest FormField components — one FormField per field
+- FormField does NOT auto-wire Label→Input association; use `<Label htmlFor="x" />` + `<Input id="x" />` explicitly
 
 ## Changes
 ### v0.18.0
@@ -2001,8 +2352,17 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 </HoverCard>
 ```
 
+## Composability
+- Radix HoverCard — accepts `open`, `onOpenChange`, `defaultOpen`, `openDelay` (ms before show), `closeDelay` (ms before hide).
+- **Distinction from Tooltip:** HoverCardContent can contain interactive elements (links, buttons, form fields). Tooltip is for inert text labels. If you need a rich hover preview — user card, link preview, product card — use HoverCard.
+- **Distinction from Popover:** Popover opens on click/focus; HoverCard opens on hover/focus. Use HoverCard when the intent is a passive preview, Popover when the user must explicitly invoke the panel.
+- **Trigger:** `<HoverCardTrigger asChild>` wraps any element. Works on `<span>`, `<a>`, `<button>` — the trigger doesn't need to be interactive itself (unlike Popover where click matters).
+- **Accessibility:** Hover-only interactions are invisible on touch. Pair with a focus-visible state or use Popover instead for critical content.
+- **Portal + z-index:** z-popover (1400), same as DropdownMenu/Popover.
+
 ## Gotchas
 - Overlay component — uses Framer Motion for enter/exit animations (v0.18.0)
+- Don't nest another HoverCard inside one — both open on the same hover and conflict
 
 ## Changes
 ### v0.18.0
@@ -2046,6 +2406,13 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 <Icon icon={IconPlus} state="success" />
 ```
 
+## Composability
+- **IconContext consumption** — Icon auto-reads `size` and `stroke` from the nearest IconProvider. Button, IconButton, IconGroup, Input (startSection/endSection), Badge, NumberInput, and more all wrap their children in IconProvider so nested Icons auto-size. Explicit props always override context.
+- **Use Tabler icon components** — the `icon` prop expects a ForwardRef SVG component (the shape Tabler React exports). Any icon lib following that shape works, but Tabler is the standard.
+- **Label for a11y:** Without `label`, Icon is `aria-hidden="true"` (decorative — appropriate inside labeled buttons). With `label`, renders `role="img"` + aria-label + `<title>` for standalone icons.
+- **State overrides animate:** When both are set, state wins. `state="loading"` renders a bare Spinner; success/error render animated glyphs via Framer Motion.
+- **Reduced motion:** All animations respect `prefers-reduced-motion` — animate props fall back to static render.
+
 ## Gotchas
 - Without `label`, the icon renders `aria-hidden="true"` (decorative)
 - With `label`, the icon renders `role="img"` with `aria-label` and a `<title>` element
@@ -2088,6 +2455,13 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 <IconButton icon={<Icon icon={IconTrash} />} variant="solid" color="error" aria-label="Delete" />
 ```
 
+## Composability
+- **Built on Button internally** — inherits ALL Button features: variant, color, loading, onClickAsync, processing, ButtonGroup context consumption, asChild. Use IconButton when your button is icon-only; use Button for label-plus-icon.
+- **aria-label is TypeScript-enforced** — the library makes it impossible to forget. This is the key accessibility constraint for icon-only buttons.
+- **IconProvider cascade:** The `icon` prop expects `<Icon icon={...} />` — Icon auto-sizes based on IconButton's `size` via IconProvider context (no need to pass size to the nested Icon).
+- **Inside ButtonGroup:** Inherits variant/color/size/weight from ButtonGroup context just like Button does. Useful for icon-only toolbars.
+- **IconGroup vs ButtonGroup of IconButtons:** IconGroup is for static icon clusters (not interactive, or for decorative displays). ButtonGroup of IconButtons is for interactive toolbars where each icon is a button.
+
 ## Gotchas
 - aria-label is enforced by TypeScript — you MUST provide it
 - Prefer IconButton over Button with size="icon-*" for icon-only buttons
@@ -2131,6 +2505,13 @@ import { IconProvider, useIconContext } from '@devalok/shilp-sutra/ui'
 const { size, stroke } = useIconContext()
 ```
 
+## Composability
+- **Low-level context primitive** — rarely used directly. Most consumers want IconGroup (which wraps IconProvider + layout) or just nest Icons inside Button/Input/Badge (which provide their own IconProvider).
+- **When to reach for IconProvider manually:** Building a custom container that hosts many Icons (a dashboard tile row, a custom toolbar, a nav rail) and you want consistent icon sizing without repeating props. IconProvider is the escape hatch for that.
+- **Consumer contract:** `useIconContext()` returns `{}` (empty) when no provider is present — your consumer code MUST handle that (fall back to a default size/stroke). Don't assume a provider exists.
+- **Memoization:** The provider memoizes its value, so consumers don't re-render unless size or stroke actually change. Safe to use in tight loops / frequently-re-rendering trees.
+- **Composes down:** IconProvider nests — inner providers override outer ones. A `<Button size="lg"><IconProvider size="xs">...</IconProvider></Button>` overrides the button's icon sizing.
+
 ## Gotchas
 - Used internally by IconGroup and Button to propagate icon sizing to children
 - If no provider is present, `useIconContext()` returns `{}` (empty object) — consumers should fall back to defaults
@@ -2167,6 +2548,15 @@ const { size, stroke } = useIconContext()
 </IconGroup>
 ```
 
+## Composability
+- **IconProvider wrapper + layout** — IconGroup is IconProvider plus a flex container. All child `<Icon>` elements auto-size via the provider. Don't pass size to nested Icons.
+- **IconGroup vs ButtonGroup-of-IconButtons:**
+  - IconGroup = static icon displays (legend rows, feature lists, decorative clusters). Not interactive.
+  - ButtonGroup of IconButtons = interactive toolbar where each icon is a button.
+  - If you want a formatting toolbar (interactive), use ButtonGroup or ToggleGroup, not IconGroup.
+- **Toolbar mode:** Set `role="toolbar"` + provide `label` to give the group a semantic role. Only then does `label` become `aria-label` on the container.
+- **Gap semantics:** tight=2px, default=4px, loose=8px — smaller values than ButtonGroup or Stack because icons are visually dense.
+
 ## Gotchas
 - Wraps children in an IconProvider — all child Icons inherit size/stroke from the group
 - `label` is only applied as `aria-label` when `role="toolbar"` is set
@@ -2191,8 +2581,6 @@ const { size, stroke } = useIconContext()
     startSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
     endSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
     wrapperClassName: string (classes for the wrapper div — border, bg, ring)
-    startIcon: ReactNode (@deprecated — use startSection)
-    endIcon: ReactNode (@deprecated — use endSection)
     (plus all standard HTML input attributes except native "size")
 
 ## Types
@@ -2209,6 +2597,13 @@ const { size, stroke } = useIconContext()
 <Input endSection=".00" endSectionType="label" startSection={<Icon icon={IconCurrencyDollar} />} placeholder="0" />
 ```
 
+## Composability
+- **FormField auto-consumption:** Inside a `<FormField>`, Input auto-inherits `state`, `aria-describedby` (linked to FormHelperText), `aria-invalid` (when state="error"), `aria-required`. Explicit props on Input override context.
+- **IconProvider cascade:** Icons in `startSection` / `endSection` are auto-sized via IconProvider per the input's `size` (xs → sm icon, sm → sm icon, md → md icon, lg → md icon). Don't pass explicit size to nested `<Icon>`.
+- **Container-first architecture (v0.29.0+):** Border, background, focus ring all live on the wrapper div (accessed via `wrapperClassName`). The raw `<input>` inside is transparent. `className` goes to the input element; `wrapperClassName` goes to the wrapper.
+- **Section types:** Strings in startSection/endSection auto-render as `label` (tinted bg + border separator); React elements auto-render as `icon` (fixed-width centered cell). Override via `startSectionType` / `endSectionType`.
+- **Label pairing:** Always pair with `<Label htmlFor="x" />` + `<Input id="x" />` or wrap both in a `<label>` — FormField doesn't auto-wire the visual label to the input.
+
 ## Gotchas
 - HTML native "size" attribute is excluded — use CSS width instead
 - state="error" sets aria-invalid automatically
@@ -2220,6 +2615,10 @@ const { size, stroke } = useIconContext()
 - Section type is auto-inferred: strings default to `'label'` (tinted bg + border), React elements default to `'icon'` (fixed-width centered). Override with `startSectionType`/`endSectionType`.
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated `startIcon` / `endIcon` props. Use `startSection` / `endSection`.
+- **Removed** (BREAKING) deprecated `inputVariants` export. Use `inputWrapperVariants`.
+
 ### v0.29.0
 - **Changed** v2 rewrite: container-first architecture with wrapper div holding focus ring
 - **Added** `xs` size (28px height)
@@ -2256,17 +2655,32 @@ const { size, stroke } = useIconContext()
 - Category: ui
 
 ## Props
-    Standard input-otp props (maxLength, pattern, etc.)
+### InputOTP
+    maxLength: number (REQUIRED) — total number of slots
+    value: string (controlled value; defaults to empty string)
+    onChange: (value: string) => void
+    onComplete: (value: string) => void — fires when all slots filled
+    pattern: string | RegExp — restrict input (e.g. `REGEXP_ONLY_DIGITS`)
+    state: "default" | "error" (error adds red border; auto-inherits from FormField)
+    size: "sm" | "md" | "lg" (slot dimensions — propagates to InputOTPSlot via context)
+    disabled: boolean
+    containerClassName: string (on the outer group container — separate from inner input's className)
+
+### InputOTPSlot
+    index: number (REQUIRED, 0-based) — which position this slot renders
 
 ## Compound Components
-    InputOTP (root)
-      InputOTPGroup
-        InputOTPSlot (index: number, REQUIRED)
-      InputOTPSeparator
+    InputOTP (root — maxLength, value, onChange, size propagated via context)
+      InputOTPGroup (visual group of slots)
+        InputOTPSlot (index: number, REQUIRED — reads size from context)
+      InputOTPSeparator (visual separator, e.g. between two groups of 3)
+
+## Defaults
+    size="md", state="default"
 
 ## Example
 ```jsx
-<InputOTP maxLength={6}>
+<InputOTP maxLength={6} onComplete={verifyCode}>
   <InputOTPGroup>
     <InputOTPSlot index={0} />
     <InputOTPSlot index={1} />
@@ -2281,8 +2695,15 @@ const { size, stroke } = useIconContext()
 </InputOTP>
 ```
 
+## Composability
+- Size propagates from InputOTP → InputOTPSlot via `InputOTPSizeContext` — don't set size on individual slots.
+- Inside `<FormField>`: auto-inherits state, aria-describedby, aria-required from context. Explicit `state="error"` overrides.
+- Underlying library is `input-otp` (OTPInput) — all standard library props (pattern, inputMode, autoFocus, etc.) pass through.
+
 ## Gotchas
-- Each InputOTPSlot requires an `index` prop (0-based)
+- Each InputOTPSlot requires an `index` prop (0-based) matching its position
+- `onComplete` only fires when ALL slots are filled — use `onChange` for per-character reactivity
+- `containerClassName` (outer visual group) is distinct from `className` (the hidden input element itself)
 
 ## Changes
 ### v0.18.0
@@ -2309,8 +2730,14 @@ const { size, stroke } = useIconContext()
 <Label htmlFor="email" required>Email Address</Label>
 ```
 
+## Composability
+- **Label is NOT auto-wired by FormField** — you must explicitly pair `<Label htmlFor="x" />` with the matching `<Input id="x" />` (or Checkbox/Radio/Switch/Select). Screen-reader label association depends on this.
+- Radix Label primitive underneath — clicking the Label focuses its associated control, which is why the `htmlFor`/`id` pairing matters.
+- `required={true}` only renders the red asterisk; it does NOT set `aria-required` on the associated control (that comes from FormField context on the control itself).
+- Works with any input-like component in the library — pair with Input, Textarea, NumberInput, Checkbox, Radio, Switch, Select, Combobox, Autocomplete.
+
 ## Gotchas
-- Use with FormField for automatic aria wiring
+- Use with FormField for automatic aria wiring on the control (but the Label-to-control association is always manual)
 
 ## Changes
 ### v0.2.0
@@ -2338,8 +2765,15 @@ const { size, stroke } = useIconContext()
 <Link asChild><NextLink href="/about">About</NextLink></Link>
 ```
 
+## Composability
+- **Framework router integration via `asChild`:** `<Link asChild><NextLink href="/foo">...</NextLink></Link>` — Link's styling transfers to the child (NextLink/react-router Link/any `<a>`-like component) while preserving the child's navigation semantics. Don't use `asChild` for plain anchors — it's unnecessary and adds a layer.
+- **inline vs block:** Default `inline` (display: inline) so Link composes naturally inside paragraphs and mixed text. Set `inline={false}` for full-width link regions (card wrappers, list items).
+- No context, no cascade. Safe to use anywhere.
+- For icon + text links, nest Icon inside — Link doesn't auto-size via IconProvider (unlike Button), so pass an explicit `size` to the Icon.
+
 ## Gotchas
 - Use asChild with framework-specific Link components (e.g. Next.js Link)
+- Don't nest interactive elements (buttons, form controls) inside a Link — that's invalid HTML and breaks screen-reader navigation
 
 ## Changes
 ### v0.18.0
@@ -2379,8 +2813,17 @@ const { size, stroke } = useIconContext()
 </Menubar>
 ```
 
+## Composability
+- Radix Menubar — shares the item-variant vocabulary with DropdownMenu and ContextMenu (checkbox items, radio groups, sub-menus, labels, separators, shortcuts).
+- **Key difference from DropdownMenu:** Menubar is the horizontal top-bar-menu pattern (File / Edit / View / Help). Multiple MenubarMenu children sit side-by-side at the root; opening one closes the others, and arrow keys move between them.
+- **Typical use:** Desktop app-like UIs where the menu is always visible at the top (code editors, design tools). For a single collapsed trigger, use DropdownMenu instead.
+- **Controlled open:** Pass `value` + `onValueChange` to Menubar root to control which MenubarMenu is open (value = menu's `value` prop or falsy for none).
+- **Portal + z-index:** z-popover (1400).
+
 ## Gotchas
 - Follows the standard Radix Menubar compound pattern
+- Don't use Menubar for a single dropdown — use DropdownMenu instead
+- MenubarShortcut is decorative (same as DropdownMenuShortcut) — bind shortcuts separately
 
 ## Changes
 ### v0.18.0
@@ -2424,8 +2867,17 @@ const { size, stroke } = useIconContext()
 </NavigationMenu>
 ```
 
+## Composability
+- **Radix NavigationMenu** underneath — keyboard model (Tab between items, Arrow for panel navigation, Esc to close) is pre-wired.
+- **NavigationMenuLink vs NavigationMenuTrigger:** Use Link for simple nav items (no dropdown); use Trigger + Content for items with a panel of sub-links.
+- **NavigationMenuViewport** is the animated container that holds the active Content panel — it auto-positions below the triggers. NavigationMenuIndicator is the small arrow/caret pointing from trigger to viewport.
+- **Purpose:** Top-level site navigation (Products, Solutions, Resources) with rich dropdowns containing links grouped by category. Don't use for context menus (use DropdownMenu) or action toolbars (use ButtonGroup).
+- **Router integration:** Use `<NavigationMenuLink asChild><NextLink href="/...">...</NextLink></NavigationMenuLink>` for framework-specific Link components.
+- **Portal + z-popover (1400)** — content panels portal to body and stack above Dialog/Sheet.
+
 ## Gotchas
 - Uses Framer Motion for enter/exit animations (v0.18.0)
+- NavigationMenu is NOT for sidebar nav — use Sidebar; NOT for mobile nav — use Sheet or BottomNavbar
 
 ## Changes
 ### v0.18.0
@@ -2446,6 +2898,8 @@ const { size, stroke } = useIconContext()
 ## Props
     value: number (default: 0)
     onValueChange: (value: number) => void
+    size: "xs" | "sm" | "md" | "lg"
+    state: "default" | "error" | "warning" | "success" (border color)
     min: number
     max: number
     step: number (default: 1)
@@ -2453,6 +2907,8 @@ const { size, stroke } = useIconContext()
 
 ## Defaults
     value: 0
+    size: "md"
+    state: "default"
     step: 1
     min: Number.MIN_SAFE_INTEGER
     max: Number.MAX_SAFE_INTEGER
@@ -2462,6 +2918,12 @@ const { size, stroke } = useIconContext()
 <NumberInput value={qty} onValueChange={setQty} min={1} max={99} />
 ```
 
+## Composability
+- **FormField auto-consumption:** Inside `<FormField>`, inherits `aria-describedby`, `aria-invalid`, `aria-required`. `state` from FormField context drives the border color unless overridden.
+- **IconProvider cascade:** The `+` and `−` stepper icons auto-size via IconProvider per the input size (xs/sm/md/lg → xs/sm/sm/md icons).
+- **Controlled only** (design choice): no `defaultValue` — pair `value` + `onValueChange` every time. The min/max bounds disable the stepper buttons automatically when reached.
+- **Label pairing:** Manual via `<Label htmlFor="x" />` + `<NumberInput id="x" />`.
+
 ## Gotchas
 - Controlled only — buttons won't work without onValueChange
 
@@ -2519,8 +2981,18 @@ const { size, stroke } = useIconContext()
 </PaginationRoot>
 ```
 
+## Composability
+- **Two APIs in one component:**
+  - Low-level compound (PaginationRoot + Content + Item + Link + Previous/Next/Ellipsis) — full control over rendering
+  - High-level `PaginationNav` — pass `totalPages` + `currentPage` + `onPageChange` and it renders the whole thing using `generatePagination`
+- **Use PaginationNav for 95% of cases.** Reach for the compound API when you need custom page-button rendering (e.g. pagination with input "jump to page" or custom ellipsis handling).
+- **generatePagination** utility — pass `current`, `total`, `siblingCount` to get the `[1, ..., 5, 6, 7, ..., 20]` structure. Use it standalone if rendering pagination elsewhere (e.g. in a DataTable's footer).
+- **Router integration:** Each PaginationLink accepts `asChild` — wrap with NextLink/react-router Link for URL-based pagination.
+- **DataTable already has built-in pagination** — don't add Pagination separately; use DataTable's `pagination` prop.
+
 ## Gotchas
 - Root component is PaginationRoot (NOT Pagination)
+- PaginationNav is the convenience wrapper — prefer it unless you need custom rendering
 
 ## Changes
 ### v0.1.1
@@ -2549,8 +3021,17 @@ const { size, stroke } = useIconContext()
 </Popover>
 ```
 
+## Composability
+- Built on Radix Popover — accepts `open`, `onOpenChange`, `defaultOpen`, `modal`.
+- **Trigger:** `<PopoverTrigger asChild>` wraps any focusable element.
+- **PopoverAnchor:** Optional — decouples the visual anchor from the interactive trigger. Useful when the trigger is small (e.g. an icon button) but you want the popover to position relative to a larger surrounding element.
+- **Positioning:** PopoverContent accepts `side` (top / right / bottom / left), `align` (start / center / end), `sideOffset`, and `collisionPadding` — all forwarded to Floating UI via Radix.
+- **Portal rendering:** Content portals to body; z-index is `z-popover` (1400) — above Dialog (`z-dialog`) so nested popovers-in-dialogs work correctly.
+- **Not for tooltips** — use Tooltip for transient hover-label content; Popover is for interactive content (forms, menus, pickers).
+
 ## Gotchas
 - Uses Framer Motion for enter/exit animations (v0.18.0)
+- If content needs to be modal (backdrop, focus trap), pass `modal={true}` to the root Popover
 
 ## Changes
 ### v0.18.0
@@ -2583,6 +3064,13 @@ const { size, stroke } = useIconContext()
 <Progress size="sm" />  {/* indeterminate */}
 ```
 
+## Composability
+- **Radix Progress** underneath — `value` (determinate) or absent (indeterminate). Standard ARIA: role=progressbar, aria-valuenow/min/max.
+- **autoColor semantic signal:** Maps value thresholds to color so consumers don't have to manually compute: 0–59=default, 60–84=warning, 85–100=success, >100=error. Useful for storage meters, budget trackers, goal progress.
+- **Indeterminate:** Omit `value` to get a continuous animated indeterminate bar. Use for unknown-duration loads.
+- **Progress vs ProgressRing:** Progress is a linear bar (horizontal). ProgressRing is circular. ProgressRing offers multi-ring stacked variants; Progress doesn't.
+- **Inside Card/StatCard:** StatCard has a `progress` prop that renders a thin inline version — use that inside StatCards instead of a separate Progress.
+
 ## Gotchas
 - Omit value (or pass undefined) for indeterminate animation
 - `autoColor` overrides `color` when `value` is set — do not pass both unless you want autoColor to win
@@ -2630,6 +3118,13 @@ const { size, stroke } = useIconContext()
 />
 ```
 
+## Composability
+- **SVG-based circular progress** — pure SVG, no chart library dependency.
+- **MultiProgressRing** — concentric rings for multi-metric visualization (Apple Activity style: Move + Exercise + Stand). Don't stack more than 4-5 rings at a size; the innermost rings become too thin. Size auto-allocates ring stroke; pass `size="lg"` for more room.
+- **ProgressRing vs Progress:** Use ProgressRing for dashboard tiles, at-a-glance status, multi-metric visualizations. Use Progress for linear "percentage filled" UIs.
+- **`showValue={true}`** renders the percentage in the center (ProgressRing only). For MultiProgressRing, use external labels since center would conflict with multiple values.
+- **Label for a11y:** `label` falls back to `"{n}% progress"` so screen readers always get meaningful context.
+
 ## Gotchas
 - Uses Framer Motion for the animated fill — not server-safe
 - Value is clamped to `[0, max]` internally
@@ -2640,9 +3135,26 @@ const { size, stroke } = useIconContext()
 - Server-safe: No
 - Category: ui
 
+## Props
+### RadioGroup
+    value: string (controlled)
+    onValueChange: (value: string) => void
+    defaultValue: string
+    disabled: boolean (propagates to all items)
+    orientation: "horizontal" | "vertical"
+    name: string (form name for all items)
+
+### RadioGroupItem
+    value: string (REQUIRED — what's selected when this item is checked)
+    size: "sm" | "md" | "lg"
+    disabled: boolean (item-level override)
+
 ## Compound Components
-    RadioGroup (root, value, onValueChange, defaultValue)
-      RadioGroupItem (value: string, REQUIRED)
+    RadioGroup (root — value, onValueChange, defaultValue, disabled propagated)
+      RadioGroupItem (value REQUIRED, size/disabled individually overridable)
+
+## Defaults
+    RadioGroupItem size="md"
 
 ## Example
 ```jsx
@@ -2658,9 +3170,17 @@ const { size, stroke } = useIconContext()
 </RadioGroup>
 ```
 
+## Composability
+- Radix RadioGroup — keyboard navigation (arrow keys to move between items, space to select) is pre-wired.
+- **RadioGroup propagates** `disabled` to every RadioGroupItem; items can opt back in with `disabled={false}` for granular control (rare).
+- **Labels:** RadioGroupItem has no intrinsic label — pair each with `<Label htmlFor="x" />` + `<RadioGroupItem id="x" value="..." />`. Screen readers announce the group label (from FormField or aria-labelledby on RadioGroup) plus each item's label.
+- **Form libraries:** RadioGroup works with react-hook-form via Controller (onValueChange maps to field.onChange). The `name` prop puts a hidden form input per item for native form serialization.
+- **FormField integration:** RadioGroup does NOT auto-consume FormField error state. For error visuals, style the RadioGroup surround (e.g. via aria-invalid on a wrapping fieldset) — individual radios don't show red borders the way Inputs do.
+
 ## Gotchas
 - Each RadioGroupItem needs a unique `value` prop
 - Pair each item with a Label for accessibility
+- RadioGroup does NOT auto-inherit FormField error state — handle error styling at the group level
 
 ## Changes
 ### v0.4.2
@@ -2696,8 +3216,16 @@ const { size, stroke } = useIconContext()
 />
 ```
 
+## Composability
+- Purpose-built variant of Input for search — renders the leading search icon and a contextual clear/loading trailing slot. For anything more custom, use Input with explicit `startSection` / `endSection`.
+- **`onClear` makes the X button appear** only when `value` is non-empty. Pair them so users can reset.
+- **`loading={true}` swaps the clear button for a spinner** with `aria-busy="true"` on the input — useful for debounced/async search.
+- Doesn't auto-consume FormField (no `state` prop) — wrap a regular Input inside FormField for validated search fields.
+- Keyboard: Escape auto-triggers `onClear` when wired (handled via `type="search"`'s native behavior on most browsers).
+
 ## Gotchas
 - HTML native "size" attribute is excluded — use CSS width instead
+- Clear button only appears when both `onClear` is provided AND `value` is non-empty
 
 ## Changes
 ### v0.15.0
@@ -2718,8 +3246,8 @@ const { size, stroke } = useIconContext()
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg" (REQUIRED) — also accepts legacy "small" | "medium" | "big"
-    variant: "filled" | "tonal" (REQUIRED)
+    size: "sm" | "md" | "lg"
+    variant: "default" | "solid"
     options: SegmentedControlOption[] (REQUIRED)
     selectedId: string (REQUIRED)
     onSelect: (id: string) => void (REQUIRED)
@@ -2727,14 +3255,18 @@ const { size, stroke } = useIconContext()
 
 ## Types
     SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
-    SegmentedControlSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'big' (legacy aliases)
-    SegmentedControlVariant = 'filled' | 'tonal'
+    SegmentedControlSize = 'sm' | 'md' | 'lg'
+    SegmentedControlVariant = 'default' | 'solid'
+
+## Defaults
+    size: "md"
+    variant: "default"
 
 ## Example
 ```jsx
 <SegmentedControl
   size="md"
-  variant="tonal"
+  variant="default"
   options={[
     { id: 'list', text: 'List' },
     { id: 'grid', text: 'Grid' },
@@ -2744,16 +3276,27 @@ const { size, stroke } = useIconContext()
 />
 ```
 
+## Composability
+- **Data-driven, not compound** — unlike Tabs/ToggleGroup, SegmentedControl takes an `options` array rather than children. This makes it easier to render from a list but harder to customize per-option styling; use Tabs if you need compound children.
+- **When to use vs Tabs:** SegmentedControl is for mutually-exclusive VIEW-MODE toggles (List/Grid/Kanban) — short labels, no associated content panel. Tabs is for content switching where each tab has a corresponding TabsContent. Both render `role="tablist"`.
+- **Option icons** auto-size based on the `size` prop — don't set explicit icon sizes.
+- Fully controlled — there's no `defaultSelectedId`. Manage state in parent.
+- Built from scratch (no Radix primitive) — standard HTML buttons with `aria-selected` and roving tabindex.
+
 ## Gotchas
 - Controlled only — selectedId + onSelect are required
 - Uses data-driven API (options prop), not compound children
+- Use Tabs (not SegmentedControl) when you need associated content panels per option
 
 ## Changes
+### v0.38.0
+- **Removed** (BREAKING) deprecated `variant="accent"` alias. Use `variant="solid"`.
+
 ### v0.18.0
 - **Fixed** `bg-interactive` changed to `bg-accent-9`, `bg-field` changed to `bg-surface-3` (OKLCH migration)
 
 ### v0.4.2
-- **Changed** (BREAKING) `color` prop renamed to `variant` (values `filled`/`tonal` unchanged)
+- **Changed** (BREAKING) `color` prop renamed to `variant`
 
 ### v0.1.1
 - **Fixed** `tabIndex={0}` changed to `tabIndex={-1}` on tablist wrapper — fixes double-focus keyboard navigation bug
@@ -2769,11 +3312,13 @@ const { size, stroke } = useIconContext()
 
 ## Props
 ### SelectTrigger
-    size: "sm" | "md" | "lg"
+    variant: "default" | "outline" | "ghost"
+    color: "default" | "error" | "success" | "warning" (sets aria-invalid when error)
+    size: "xs" | "sm" | "md" | "lg"
 
 ## Compound Components
     Select (root — value, onValueChange, defaultValue)
-      SelectTrigger (size goes HERE, not on Select root)
+      SelectTrigger (variant/color/size go HERE, not on Select root)
         SelectValue (placeholder)
       SelectContent
         SelectGroup (optional grouping)
@@ -2782,7 +3327,7 @@ const { size, stroke } = useIconContext()
         SelectSeparator
 
 ## Defaults
-    SelectTrigger size: "md"
+    SelectTrigger variant="default", color="default", size="md"
 
 ## Example
 ```jsx
@@ -2797,6 +3342,15 @@ const { size, stroke } = useIconContext()
 </Select>
 ```
 
+## Composability
+- **Radix Select** underneath — `value`/`onValueChange`/`defaultValue`/`open`/`onOpenChange` standard state.
+- **Styling props live on SelectTrigger, not Select root.** The Select root owns value/state; the Trigger owns appearance (variant/color/size). Setting `<Select size="lg">` silently does nothing — TypeScript won't catch it.
+- **SelectItem requires `value`** — unique within the Select. Labels are the children of SelectItem.
+- **SelectGroup + SelectLabel:** Organize options into sections with a non-interactive section heading.
+- **FormField integration:** Set `color="error"` on SelectTrigger for error visuals. Not auto-consumed from FormField (same as Checkbox/Radio — form-library convention for select controls).
+- **Portal + z-popover (1400):** content portals to body, stacks above Dialog/Sheet/other overlays.
+- **Select vs Combobox vs Autocomplete:** Select = short fixed list, click-to-open, no typeahead. Combobox = searchable, forced selection. Autocomplete = searchable, free text. Pick by list size and search need.
+
 ## Gotchas
 - Size goes on SelectTrigger, NOT on Select root
 - `<Select size="lg">` is silently ignored (no TypeScript error)
@@ -2834,8 +3388,15 @@ const { size, stroke } = useIconContext()
 <Separator orientation="vertical" className="h-6" />
 ```
 
+## Composability
+- Radix Separator — no context, no cascade. Drop it anywhere; it inherits its stretch dimension from its parent container (full width for horizontal, full height for vertical — but vertical needs an explicit height from the parent flexbox).
+- `decorative={true}` (default) sets `role="none"` — screen readers skip it. Set `decorative={false}` for semantic separators (e.g. between navigation sections) so screen readers announce the boundary.
+- Gradient variants compose cleanly with any surface color — they use `bg-transparent` + inline linear-gradient, so the underlying `bg-*` of the parent shows through.
+- Common inside Menu/DropdownMenu/Sheet components; their internal *Separator subcomponents already wrap this one.
+
 ## Gotchas
 - When decorative is true, the separator is hidden from screen readers
+- Vertical separator needs an explicit height from the parent flex container (`h-6`, `h-full`, etc.)
 
 ## Changes
 ### v0.22.0
@@ -2880,8 +3441,18 @@ const { size, stroke } = useIconContext()
 </Sheet>
 ```
 
+## Defaults
+    side="right"
+
+## Composability
+- Same primitives as Dialog — open/onOpenChange/defaultOpen, trigger asChild, portal rendering, focus trap.
+- `side` controls both the enter-from edge and the layout: top/bottom sides full-width, left/right sides ~75% of viewport (capped at sm breakpoint).
+- Use Sheet for side-anchored drawers (settings panels, mobile navigation); use Dialog for centered modals.
+- On mobile (`isMobile` from use-mobile), consider Sheet as the mobile-friendly equivalent of a Dialog/Popover — more thumb-reachable on tall screens.
+
 ## Gotchas
 - Uses Framer Motion for slide enter/exit animations (v0.18.0)
+- SheetTitle is required for accessibility (same rule as Dialog)
 
 ## Changes
 ### v0.18.0
@@ -2899,6 +3470,14 @@ const { size, stroke } = useIconContext()
 - Server-safe: No
 - Category: ui
 
+## Props
+### SidebarMenuButton
+    variant: "default" | "outline"
+    size: "sm" | "md" | "lg"
+    isActive: boolean (highlights as current nav item)
+    tooltip: ReactNode | string (shown when sidebar is collapsed)
+    asChild: boolean (render as Slot — common with next/link)
+
 ## Compound Components
     SidebarProvider (context provider — must wrap everything)
       Sidebar (root panel)
@@ -2927,6 +3506,9 @@ const { size, stroke } = useIconContext()
 ## Hook
     useSidebar() => { state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar }
 
+## Defaults
+    SidebarMenuButton variant="default", size="md"
+
 ## Example
 ```jsx
 <SidebarProvider>
@@ -2954,9 +3536,28 @@ const { size, stroke } = useIconContext()
 </SidebarProvider>
 ```
 
+## Composability
+The whole Sidebar ecosystem is driven by `SidebarContext` — the Provider owns the expand/collapse state and every descendant reads from it.
+
+**Who reads the context:**
+- `Sidebar` — applies collapsed / expanded / off-canvas styles based on `state`
+- `SidebarTrigger` — calls `toggleSidebar()` on click; reflects aria-expanded
+- `SidebarMenuButton` — uses `state === 'collapsed'` to show its `tooltip` (hidden label appears only when sidebar is icon-width)
+- `SidebarInset` — main content area adjusts its left offset based on sidebar width + state
+- `SidebarRail` — invisible hit target on the outer edge for click-to-toggle
+- Any user component that calls `useSidebar()` — full access to open/isMobile/toggle
+
+**Desktop vs mobile:** Context tracks `isMobile` via the `use-mobile` hook and branches behavior: on desktop the sidebar collapses to an icon rail; on mobile it becomes an off-canvas drawer controlled by `openMobile`.
+
+**Controlled or uncontrolled:** `SidebarProvider` accepts `open` + `onOpenChange` (controlled) or `defaultOpen` (uncontrolled). State is synced to a cookie for cross-route persistence.
+
+**Next.js / router integration:** `SidebarMenuButton` with `asChild` wraps any link element (`next/link`, `react-router Link`, plain `<a>`) — it transfers its styling + isActive state to the child while preserving the link's navigation semantics.
+
 ## Gotchas
 - SidebarProvider MUST wrap both Sidebar and SidebarInset
 - Use SidebarMenuButton for nav items (supports tooltip in collapsed state)
+- `tooltip` is only visible when sidebar is collapsed — providing one doesn't duplicate the visible label
+- Cookie-based state persistence means the sidebar defaults to its prior state on page reload — use `defaultOpen` to override if needed
 
 ## Changes
 ### v0.18.0
@@ -3034,6 +3635,13 @@ const { size, stroke } = useIconContext()
 <SkeletonImage height="h-64" />
 ```
 
+## Composability
+- Server-safe — can render in RSC trees during server-side loading states.
+- **Pattern:** One SkeletonGroup per load region (wraps with `role="status"` + `aria-busy="true"` + announces the `label`). Inside, compose the individual shape skeletons (Avatar, Text, Button, Chart, Image) to mirror the structure that will appear when loaded.
+- Use LoadingSkeleton (composed) instead for pre-built layouts — CardSkeleton, TableSkeleton, ListSkeleton, BoardSkeleton — or PageSkeletons for full-page placeholders.
+- `animation="none"` disables animation entirely — useful when placed inside components that already have their own load animation.
+- No context cascade — each skeleton is independent. If you want to drive multiple skeletons from one "reduced motion" setting, either set `animation="none"` on each or rely on the `useReducedMotion` hook (shimmer already respects it automatically).
+
 ## Gotchas
 - shimmer respects prefers-reduced-motion
 - SkeletonGroup adds role="status" and aria-busy="true" — wrap multiple skeletons for a11y
@@ -3049,7 +3657,12 @@ const { size, stroke } = useIconContext()
 - Category: ui
 
 ## Props
-    Standard Radix Slider props (value, onValueChange, defaultValue, min, max, step, aria-label)
+    size: "sm" | "md" | "lg" (track height and thumb dimensions)
+    color: "accent" | "success" | "warning" | "error" (thumb border + focus ring color)
+    (plus standard Radix Slider props: value, onValueChange, defaultValue, min, max, step, aria-label)
+
+## Defaults
+    size="md", color="accent"
 
 ## Example
 ```jsx
@@ -3057,9 +3670,18 @@ const { size, stroke } = useIconContext()
 <Slider defaultValue={[25, 75]} max={100} step={1} /> {/* range slider */}
 ```
 
+## Composability
+- Radix Slider primitive — keyboard navigation (arrow keys, Home/End, PageUp/PageDown) pre-wired.
+- **Value is always an array** — single-thumb: `[50]`; range: `[25, 75]`. Don't pass a plain number.
+- **Multi-thumb range:** Pass `[start, end]` — renders two thumbs that can cross each other by default. Use `minStepsBetweenThumbs` to enforce a gap.
+- **FormField:** Slider does NOT auto-consume FormField state. No validation UX — sliders usually don't need it (values are always valid by construction).
+- **No label pairing via Label** — use `aria-label` or `aria-labelledby` directly on the Slider. The thumb is the focusable/labeled element.
+- Not portal-rendered — inline; overflow rules of parents apply.
+
 ## Gotchas
 - value is number[] (array), not a single number
 - Multi-thumb: Pass array `defaultValue={[25, 75]}` for range sliders — renders one thumb per value
+- Slider does NOT auto-consume FormField — sliders don't have validation state visuals by design
 
 ## Changes
 ### v0.18.0
@@ -3097,6 +3719,13 @@ const { size, stroke } = useIconContext()
 <Spinner variant="bare" /> {/* uses currentColor, for embedding in buttons */}
 ```
 
+## Composability
+- **Prefer Button's `loading` prop** for inline button spinners — Button's integration is automatic (disables, sets aria-busy, positions the spinner). Manual Spinner inside Button is more work for no gain.
+- **`variant="bare"`** uses `currentColor` — drop it into any surface (button, toolbar, badge, icon group) and it picks up the parent's text color automatically.
+- **State transitions:** `spinning → success → idle` / `spinning → error → idle`. Use the state machine for async operation feedback (the success checkmark, error X animate in). Pair with `onComplete` to trigger next-step logic after the transition.
+- **delay for flicker prevention:** Set `delay={150}` so very fast operations don't flash a spinner. The spinner mounts only after the delay elapses — if the operation completes first, the user never sees it.
+- **Icon.state="loading" uses Spinner internally** — same underlying component. If you're inside an Icon context, prefer `<Icon state="loading" />` for consistent sizing.
+
 ## Gotchas
 - Renders role="status" with sr-only "Loading..." text — no need for aria-label
 - Button has built-in loading prop — prefer that over manual Spinner composition
@@ -3162,6 +3791,17 @@ import { SplitButton } from '@devalok/shilp-sutra'
 | dropdownLabel | string | 'More options' | aria-label for trigger |
 | dropdownIcon | ReactNode | chevron-down | Custom trigger icon |
 
+## Composability
+- **Two-in-one button:** visually unified `[Action | ▼]` with the left half being the primary click and the right half opening a dropdown. Use for actions that have a most-common choice plus alternatives (Save vs. Save-As-Draft, Send vs. Schedule).
+- **Built on Button + Popover internally** — inherits Button's variant/color/size vocabulary and Popover's placement prop (`top-end` default works for most top-of-page toolbars).
+- **Dropdown content is consumer-provided** — pass any JSX via `dropdownContent` (typically a DropdownMenu, list of actions, a custom panel, or a small form). Don't try to shove a full-featured menu into the chevron; keep it focused on 2–5 alternatives.
+- **ButtonGroup compatibility:** Put SplitButton inside a `<ButtonGroup>` — it inherits variant/color/size from the group context just like Button does. Position-aware corners work too.
+- **Controlled dropdown:** Pass `open` + `onOpenChange` for controlled state; omit for uncontrolled. Useful when the dropdown must close programmatically after a selection.
+
+## Gotchas
+- Always provide `dropdownLabel` (aria-label on the chevron trigger) — defaults to "More options" but context-specific labels are better
+- `triggerSide="left"` flips the chevron to the left — rare, but useful for RTL layouts or when the primary action is the secondary emphasis
+
 ## Changes
 
 ### v0.33.0
@@ -3191,6 +3831,14 @@ import { SplitButton } from '@devalok/shilp-sutra'
 </Stack>
 ```
 
+## Composability
+- **Server-safe layout primitive.** Nothing to hydrate — works anywhere.
+- **Pattern:** Stack wraps child elements in a flex container. Swap between vertical/horizontal without rewriting the child layout.
+- **Polymorphic via `as`:** Use `as="ul"` / `as="ol"` for list semantics with flex styling; `as="section"` for major page divisions; etc.
+- **gap is design-system tokenized** — use token strings (`"ds-04"`) or numeric shortcuts (`4` → `"ds-04"`). Raw numbers map 1:1 to the `ds-0N` token set.
+- **Responsive direction:** Not built in — for responsive direction changes use Tailwind's `flex-col md:flex-row` directly on a plain div, or wrap multiple Stacks with display-toggling.
+- Container vs Stack: Container centers + caps width; Stack arranges children. Compose them: `<Container><Stack>...</Stack></Container>`.
+
 ## Gotchas
 - "row" and "column" are aliases for "horizontal" and "vertical"
 - gap accepts both token strings and numeric values
@@ -3254,6 +3902,15 @@ import { SplitButton } from '@devalok/shilp-sutra'
 />
 ```
 
+## Composability
+- **High-density metric card** — optimized for dashboards. Everything optional except `value`. Mix and match features (delta, sparkline, progress, secondary label, footer) per metric's needs.
+- **Router integration via href:** Internally uses `LinkContext` to resolve framework-specific Link components (Next.js, react-router). Set `href` in a LinkProvider-wrapped tree to get seamless client-side navigation without custom asChild wiring.
+- **Interactive modes:** `onClick` makes the entire card a button; `href` makes it a link. Mutually exclusive — href wins if both are set.
+- **Accent bar semantic:** Use `accent` to signal metric health at a glance (success for positive, warning for at-risk, error for over-target). Combine with delta.direction for layered emphasis.
+- **Sparkline:** Pure SVG, lightweight — no chart library. For rich charts use Chart components. Minimum 2 data points.
+- **Icon auto-sizing:** Accepts `ComponentType<{ className }>` OR `ReactNode`. The component prop (e.g. `icon={IconBolt}`) is preferred — icon is rendered at a consistent size.
+- **Loading state:** `loading={true}` renders the full card skeleton — use during initial data fetch.
+
 ## Gotchas
 - delta.direction "up" = green, "down" = red, "neutral" = grey
 - `label` and `title` are aliases — use either, not both
@@ -3289,6 +3946,15 @@ import { SplitButton } from '@devalok/shilp-sutra'
 <StatusDot status="warning" size="lg" label="Elevated load" />
 ```
 
+## Composability
+- **Server-safe presentational dot** — simple status indicator, pairs with inline text.
+- **Status semantics map to color:** healthy=success, warning=warning, critical=error, neutral=muted surface, inactive=dimmed. The pulse animation calls attention to "healthy" by default (active presence); you can flip it for other statuses by setting pulse explicitly.
+- **StatusDot vs BadgeIndicator vs StatusBadge:**
+  - StatusDot = tiny presence/status indicator with optional inline label (e.g. "Service online")
+  - BadgeIndicator = overlay on another element (notification dot on a bell icon)
+  - StatusBadge (composed) = full pill-style badge with colored bg and label text (e.g. ticket status)
+- **Label composability:** If you pass `label`, it renders inline after the dot. Use `labelClassName` for custom typography (e.g. font-mono for status codes).
+
 ## Gotchas
 - The `pulse` prop auto-enables for "healthy" status — pass `pulse={false}` to suppress
 - Status type is exported as `StatusDotStatus` if you need it in consumer code
@@ -3331,8 +3997,16 @@ import { SplitButton } from '@devalok/shilp-sutra'
 </Stepper>
 ```
 
+## Composability
+- `Stepper` passes `activeStep` + `orientation` + each step's index down to every `Step` child via `StepperContext`. Each Step derives its own status (completed / active / pending) from its position vs `activeStep`.
+- Step index is assigned by position in children — order matters. Don't conditionally render Steps via `&&` or `.filter()`; it shifts the indices and breaks the active highlight.
+- `StepperContent` is separate from `Stepper` — it's the animated panel surface that shows one child per step index. Pass the same `activeStep` value to both.
+- `orientation="vertical"` swaps the Step layout (stacked with connecting line on the left) AND changes how StepperContent animates (vertical crossfade instead of horizontal slide).
+- Custom icons via `Step.icon` override the default number/checkmark — the icon slot still receives the status-based styling (muted for pending, accent for active/completed).
+
 ## Gotchas
 - Steps before activeStep are "completed", at activeStep is "active", after is "pending"
+- Don't conditionally render Step children — position is the index contract
 
 ## Changes
 ### v0.18.0
@@ -3365,9 +4039,17 @@ import { SplitButton } from '@devalok/shilp-sutra'
 <Switch size="lg" color="success" thumbIcon={<IconCheck size={14} />} />
 ```
 
+## Composability
+- Radix Switch primitive — `checked` / `onCheckedChange` / `defaultChecked` standard control model.
+- **FormField:** Switch does NOT auto-consume FormField state (same as Checkbox/Radio — form-library convention for toggles). Pass `error` explicitly when needed.
+- **thumbIcon slot:** Any ReactNode renders inside the thumb circle — commonly used for check/X glyphs that animate with the thumb position.
+- **Label pairing:** Manual — pair with `<Label htmlFor="x" />` + `<Switch id="x" />`, or wrap both in a `<label>` for click-to-toggle.
+- Pair with FormHelperText (outside FormField wiring) for custom validation messages.
+
 ## Gotchas
 - Use error prop for validation states (matches Checkbox API)
 - `error` overrides `color` — when error is true, checked state always uses error-9
+- Switch does NOT auto-consume FormField — pass `error` explicitly inside a FormField
 
 ## Changes
 ### v0.29.0
@@ -3423,8 +4105,16 @@ import { SplitButton } from '@devalok/shilp-sutra'
 </Table>
 ```
 
+## Composability
+- **Server-safe pure HTML wrappers** — Table and sub-components are thin semantic wrappers around `<table>`, `<thead>`, `<tbody>`, etc. No state, no context. Safe in RSC trees.
+- **Table vs DataTable:** Table is presentational — you control every row, cell, header. DataTable (from `ui/data-table`) is feature-rich — sorting, filtering, pagination, selection, virtualization built in. Pick by whether you need that machinery.
+- **Use cases for bare Table:** Static data displays, marketing comparison tables, documentation tables, small lists where DataTable would be overkill.
+- **Composes with UI primitives inside cells:** Badge for status pills, Avatar for user cells, IconButton for row actions, StatusDot for state indicators. All server-safe if the table is server-rendered.
+- **TableCaption** renders as HTML `<caption>` — useful for a summary description that screen readers announce before the table content.
+
 ## Gotchas
 - Table headers automatically have scope="col" for screen reader navigation
+- For anything beyond trivial display, prefer DataTable — don't rebuild sorting/pagination/selection on top of bare Table
 
 ## Changes
 ### v0.18.0
@@ -3449,6 +4139,8 @@ import { SplitButton } from '@devalok/shilp-sutra'
 
 ### TabsList
     variant: "line" | "contained"
+    size: "sm" | "md" | "lg"
+    orientation: "horizontal" | "vertical"
 
 ### TabsTrigger
     value: string (REQUIRED)
@@ -3464,7 +4156,7 @@ import { SplitButton } from '@devalok/shilp-sutra'
       TabsContent (value)
 
 ## Defaults
-    TabsList variant: "line"
+    TabsList variant="line", size="md", orientation="horizontal"
 
 ## Example
 ```jsx
@@ -3478,8 +4170,14 @@ import { SplitButton } from '@devalok/shilp-sutra'
 </Tabs>
 ```
 
+## Composability
+- TabsList propagates `variant`, `size`, and `orientation` to every TabsTrigger child via `TabsListContext`. TabsTrigger reads all three from context; explicit props on a trigger override the inherited value.
+- `orientation="vertical"` on TabsList changes the TabsList layout (flex-col + left border) AND the `roving-tabindex` keyboard behavior (ArrowUp/Down navigate, not ArrowLeft/Right).
+- Tabs (root) is just the Radix Tabs.Root — state props (value, defaultValue, onValueChange) live there; styling props live on TabsList.
+- Tabs content is rendered inline (not portalled) — container-scoped queries work fine in tests.
+
 ## Gotchas
-- variant goes on TabsList, NOT on individual TabsTrigger (propagates via context)
+- variant/size/orientation go on TabsList, NOT on Tabs root or individual TabsTrigger
 - Normally omit `variant` on TabsTrigger — it inherits from TabsList via context. You CAN set it per-trigger to override.
 
 ## Changes
@@ -3502,12 +4200,9 @@ import { SplitButton } from '@devalok/shilp-sutra'
 - Category: ui
 
 ## Props
-    variant: TextVariant
+    variant: "heading-2xl" | "heading-xl" | "heading-lg" | "heading-md" | "heading-sm" | "heading-xs" | "body-lg" | "body-md" | "body-sm" | "body-xs" | "label-lg" | "label-md" | "label-sm" | "label-xs" | "label-plain-lg" | "label-plain-md" | "label-plain-sm" | "caption" | "overline" | "code"
     as: ElementType (override the auto-selected HTML element)
 
-## Types
-    TextVariant = 'heading-2xl' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline'
-
 ## Defaults
     variant: "body-md"
 
@@ -3522,9 +4217,17 @@ import { SplitButton } from '@devalok/shilp-sutra'
 <Text variant="label-sm" className="text-text-secondary">SECTION LABEL</Text>
 ```
 
+## Composability
+- **Server-safe** (one of few components in the library that is). Can render in RSC trees without `"use client"`.
+- No context consumption, no context cascade — pure typography primitive.
+- **Semantic HTML by default:** Each variant maps to a meaningful HTML element (h1 through p, span, code). The `as` prop overrides for visual-only demotion: e.g. `<Text variant="heading-xl" as="div">` renders h2-sized text inside a div, useful when the element already has a heading ancestor but you want the visual weight.
+- **Underpins many components:** Card's CardTitle, Alert's title, PageHeader, EmptyState, SectionHeader all render Text internally with specific variants. Don't wrap another Text inside them — variants cascade structurally, not via context.
+- Pairs with Code for inline code spans inside body text: `<Text>Call <Code>onClick</Code> to...</Text>`.
+
 ## Gotchas
 - label-* and overline variants are automatically uppercase
 - Use "as" prop to override the HTML element when needed
+- Don't use Text inside headings that already have semantic meaning (e.g. CardTitle) — the double-element wraps are redundant and break screen-reader heading navigation
 
 ## Changes
 ### v0.2.0
@@ -3539,7 +4242,7 @@ import { SplitButton } from '@devalok/shilp-sutra'
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg"
+    size: "xs" | "sm" | "md" | "lg"
     state: "default" | "error" | "warning" | "success"
     (plus standard textarea attributes except native "size")
 
@@ -3551,6 +4254,12 @@ import { SplitButton } from '@devalok/shilp-sutra'
 <Textarea size="lg" state="error" placeholder="Describe the issue..." />
 ```
 
+## Composability
+- **FormField auto-consumption:** Same pattern as Input — inside `<FormField>`, Textarea inherits `state`, `aria-describedby`, `aria-invalid`, `aria-required`. Explicit props override.
+- **Resize:** Vertically resizable by default (`resize-y`); override with `className="resize-none"` if needed.
+- **Label pairing:** Manual — `<Label htmlFor="x" />` + `<Textarea id="x" />`. FormField doesn't auto-wire.
+- No IconProvider cascade (no icon slots — different from Input).
+
 ## Gotchas
 - state="error" sets aria-invalid automatically; all sizes are vertically resizable
 - Inside FormField: auto-inherits state, aria-describedby, aria-required from context (explicit props override)
@@ -3614,6 +4323,15 @@ toast.error('Upload failed', { description: 'File too large' })
 toast.undo('Task deleted', { onUndo: () => restoreTask(id) })
 ```
 
+## Composability
+- **Imperative API only** — `toast.success(...)`, `toast.error(...)`, etc. NO JSX invocation. This is by design (Sonner-based) — you call from event handlers, not render.
+- **Requires Toaster mounted once** at app root. Without it, `toast.*` calls are no-ops. Render `<Toaster />` in the root layout, not inside route components.
+- **toast.promise** orchestrates async flows: `toast.promise(fetch(...), { loading: 'Saving', success: 'Saved', error: 'Failed' })`. One toast, three states. Beats manually calling `.loading()` + `.success()`/`.error()`.
+- **toast.undo** adds an inline Undo button with 8s default duration — pair with state management that supports reversal (soft-delete with restore, last-action redo).
+- **toast.upload** is specifically for file-upload progress — per-file progress bars, retry on error, remove from list. Replaces the old `UploadProgress` composed component.
+- **toast.custom** is the escape hatch — render arbitrary JSX. Use sparingly; prefer the typed methods for consistency.
+- **Distinction from Alert/Banner:** Toast = transient, auto-dismissing, non-interactive-dismissible floating notification. Alert = inline in-flow announcement. Banner = page-level strip. Pick by persistence + position.
+
 ## Gotchas
 - DO NOT use useToast() hook — it is deprecated, use imperative toast.* methods
 - DO NOT use toast({ title, color }) object syntax — use toast.success('message') etc.
@@ -3671,9 +4389,17 @@ export default function RootLayout({ children }) {
 }
 ```
 
+## Composability
+- **Mount once, use everywhere.** Render `<Toaster />` in the root layout file once. Every `toast.*` call anywhere in the tree routes to this single container.
+- **Global config lives here.** Set `position`, `duration`, `visibleToasts` on Toaster to control default behavior for all toasts. Individual `toast.*` calls can override `duration` per toast.
+- **Keyboard shortcut:** `hotkey` prop sets a global shortcut to focus the toast region (default: Alt+T). Useful for keyboard users to review recent notifications.
+- **Next.js / App Router:** Mount inside your root `app/layout.tsx`'s `<body>`. It's marked `'use client'` so it doesn't render on the server (Toaster is client-only).
+- **Portal rendering:** z-toast (highest layer) — Toaster content appears above Dialog, Popover, everything. Don't wrap it in a stacking context.
+
 ## Gotchas
 - Must be mounted once at the layout root for toast notifications to work
 - Use the `toast` import from `@devalok/shilp-sutra/ui/toast` to trigger toasts
+- NOT server-safe — mounts with 'use client'; rendering during SSR has no visual effect
 
 ## Changes
 ### v0.18.0
@@ -3692,13 +4418,13 @@ export default function RootLayout({ children }) {
 ## Props
     variant: "default" | "outline"
     size: "sm" | "md" | "lg"
+    color: "accent" | "error" | "success" | "neutral" (pressed-state bg + text color)
     pressed: boolean
     onPressedChange: (pressed: boolean) => void
     defaultPressed: boolean
 
 ## Defaults
-    variant: "default"
-    size: "md"
+    variant="default", size="md", color="accent"
 
 ## Example
 ```jsx
@@ -3707,8 +4433,16 @@ export default function RootLayout({ children }) {
 </Toggle>
 ```
 
+## Composability
+- Radix Toggle primitive — `pressed` / `onPressedChange` / `defaultPressed`. Not the same as Switch (boolean value doesn't map to on/off semantically — Toggle is "this action is currently active").
+- **Pairs with ToggleGroup** for mutually-exclusive or multi-select toggle clusters — ToggleGroupItem inherits variant + size from ToggleGroup via context. Don't set variant on a ToggleGroupItem directly.
+- **No context consumption as a standalone** — when rendered outside a ToggleGroup, Toggle is fully independent.
+- **Icon content:** Commonly wraps a single `<Icon>` for formatting toolbar toggles (Bold, Italic, AlignLeft). Pair with IconGroup for a horizontal cluster of independent toggles (vs. ToggleGroup for related state).
+- **aria-label is required** — icon-only toggles need an accessible name.
+
 ## Gotchas
 - Always provide aria-label for accessibility
+- Toggle is not Switch — Toggle means "this action is active right now"; Switch means "this setting is on"
 
 ## Changes
 ### v0.18.0
@@ -3738,8 +4472,11 @@ export default function RootLayout({ children }) {
     value: string
 
 ## Compound Components
-    ToggleGroup (root)
-      ToggleGroupItem (value: string)
+    ToggleGroup (root — variant, size propagated to items via context)
+      ToggleGroupItem (value: string — reads variant/size from context)
+
+## Defaults
+    variant="default", size="md"
 
 ## Example
 ```jsx
@@ -3750,9 +4487,15 @@ export default function RootLayout({ children }) {
 </ToggleGroup>
 ```
 
+## Composability
+- ToggleGroup passes `variant` and `size` to every ToggleGroupItem via `ToggleGroupContext`. Items read both from context; explicit props on a child override.
+- `type="single"` enforces one-selected-at-a-time (value: string); `type="multiple"` allows many (value: string[]). Radix Toggle Group underpins this — it's the same role + keyboard model as Radix.
+- Built on top of the plain `Toggle` component's CVA — the `variant` and `size` axes of ToggleGroupItem match Toggle exactly (`default | outline`, `sm | md | lg`).
+
 ## Gotchas
-- type is required — "single" or "multiple"
-- variant and size propagate from ToggleGroup to items
+- `type` is required — "single" or "multiple" — and drives the value shape
+- variant and size propagate from ToggleGroup to items; setting them on a ToggleGroupItem overrides that item only
+- Unlike Tabs (where TabsList is the styling surface), ToggleGroup itself is the styling surface — there's no intermediate List component
 
 ## Changes
 ### v0.18.0
@@ -3785,8 +4528,18 @@ export default function RootLayout({ children }) {
 </TooltipProvider>
 ```
 
+## Composability
+- Built on Radix Tooltip — accepts `delayDuration`, `skipDelayDuration` (on TooltipProvider), and `open`/`onOpenChange`/`defaultOpen` (on Tooltip root).
+- **Auto-provider (v0.22.0+):** If no ancestor TooltipProvider exists, `<Tooltip>` auto-wraps itself with one. Explicit TooltipProvider is still recommended at layout root for shared `delayDuration` tuning.
+- **Trigger:** `<TooltipTrigger asChild>` around the element that should show the tooltip on hover/focus. Icon-only buttons are the canonical use case.
+- **Not interactive:** TooltipContent is for non-interactive text labels — don't put buttons/links inside. Use HoverCard or Popover when the popped content needs interaction.
+- **Positioning:** TooltipContent accepts `side`, `align`, `sideOffset`, and arrow via `<TooltipArrow>` (optional).
+- **Portal rendering:** z-index is `z-tooltip` (highest in the stack — above Popover and Dialog).
+
 ## Gotchas
-- TooltipProvider is REQUIRED — without it, tooltips won't show
+- TooltipProvider is REQUIRED at the layout level OR auto-created per-tooltip — but having a single root provider is better for consistent delays
+- Don't use Tooltip for critical information — hover-triggered UI is invisible to touch users. Pair with a visible label or aria-description
+- TooltipContent children must be inert — no buttons, no links, no focusable elements
 
 ## Changes
 ### v0.22.0
@@ -3854,8 +4607,20 @@ export default function RootLayout({ children }) {
 </TreeView>
 ```
 
+## Composability
+- **Two rendering modes:**
+  - **Data-driven:** Pass `items: TreeNode[]` with nested `children`. Good for server-fetched or programmatic trees.
+  - **Declarative:** Use `<TreeItem>` children directly. Good for hardcoded nav, readable JSX.
+  - Don't mix — pick one per TreeView instance.
+- **useTree hook** lets you drive TreeView state externally (e.g. sync with URL, persist expanded state, drive from Redux). Pass `defaultExpanded`/`defaultSelected` initially OR manage state via the hook's return value.
+- **TreeItem composability:** Each TreeItem has `icon`, `label`, `secondaryLabel`, and `actions` slots — rich rows without custom render props. `actions` reveals on row hover (same pattern as Message.Actions).
+- **multiSelect + checkboxes:** Set both to turn TreeView into a file-picker style tree with checkboxes instead of single-select highlighting.
+- **Keyboard navigation:** Full `role="tree"` spec — Arrow Up/Down to move, Right to expand/descend, Left to collapse/ascend, Enter to select. Pre-wired; no manual key handling needed.
+
 ## Gotchas
 - Supports both data-driven (items prop) and declarative (children) modes
+- Don't mix data-driven and declarative in the same TreeView — pick one
+- For a simple flat checkbox list, use RadioGroup/Checkbox + Stack — TreeView is overkill for non-hierarchical data
 
 ## Changes
 ### v0.4.2
@@ -3880,9 +4645,16 @@ export default function RootLayout({ children }) {
 <VisuallyHidden>Screen reader only text</VisuallyHidden>
 ```
 
+## Composability
+- Server-safe. Works anywhere — no context, no cascade.
+- Canonical use: wrap a DialogTitle / SheetTitle that must exist for a11y but shouldn't show visually (`<DialogTitle asChild><VisuallyHidden>...</VisuallyHidden></DialogTitle>`).
+- Also useful inside IconButton to provide a text alternative when the icon already has an aria-label (redundant label is harmless and helps some screen readers).
+- Uses the `sr-only` CSS pattern under the hood — content is in the DOM, just positioned off-screen.
+
 ## Gotchas
 - Content is visually hidden but accessible to screen readers
 - Useful for providing accessible labels without visual UI
+- Don't use for content you want hidden entirely — that's `hidden` or conditional rendering
 
 ## Changes
 ### v0.1.0
@@ -3933,6 +4705,12 @@ export default function RootLayout({ children }) {
 ## Exported Utilities
     groupItemsByTime(items: ActivityItem[], labels?: GroupLabels) — pure function that buckets items into time groups; returns { label: string, items: ActivityItem[] }[]
 
+## Composability
+- **Built from ui primitives:** Avatar (actor), Button (Load more), Skeleton (loading), Text (body). Override via `renderItem` to use your own primitives per row.
+- **renderItem** is the composition hook — return your own JSX or `undefined` to fall back to default ActivityEntry. Timeline dot + layout wrapper stay consistent.
+- **groupBy="time"** wraps items in Today/Yesterday/This Week/Older buckets; `groupItemsByTime()` export reusable for custom renderers.
+- **Pagination is consumer-driven** — `hasMore` + `onLoadMore` for server-side, or `maxInitialItems` + "Show all" toggle for client-side truncation.
+
 ## Gotchas
 - `items` is required — passing an empty array renders the `emptyState` content
 - `color` on each item controls the timeline dot color
@@ -3998,6 +4776,14 @@ export default function RootLayout({ children }) {
 />
 ```
 
+## Composability
+- **Built on ui/Avatar** — each slot is an Avatar with overlap + border + optional Tooltip.
+- **Wraps TooltipProvider internally** — don't add another.
+- **renderAvatar** escape hatch for custom shapes. Wrapper handles overlap/border positioning; your renderer sets size + shape.
+- **borderColor** must match the surface the group sits on (`surface-raised` on Card, `surface-base` on page bg). Mismatch = visible seam.
+- **Overflow:** +N badge with optional `onOverflowClick` → pair with a Popover/Sheet for "show all members".
+- Per-user `ring` (lead/admin/client) surfaces Avatar's ring semantic at group level — use for role/presence hints.
+
 ## Gotchas
 - Wraps TooltipProvider internally — no need to add one yourself
 - Users beyond `max` are collapsed into a "+N" overflow badge
@@ -4059,6 +4845,12 @@ export default function RootLayout({ children }) {
 />
 ```
 
+## Composability
+- **Standalone floating toolbar** — use with DataTable, TreeView, or any selection-capable UI.
+- **DataTable auto-integration:** DataTable's `bulkActions` prop renders this internally — typically you don't render BulkActionBar directly when using DataTable.
+- **Data-driven actions:** `{ label, icon, onClick, color, disabled }[]`. For destructive confirmation, call ConfirmDialog from the onClick handler.
+- **Portal to body + fixed bottom-center z-50** — independent of parent layout. Check for other fixed elements that might overlap.
+
 ## Gotchas
 - Renders via `createPortal` into `document.body` — will not appear during SSR (mounts only client-side)
 - Positioned fixed at bottom-center with `z-50`; ensure no other fixed elements conflict
@@ -4090,6 +4882,13 @@ CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () =>
 />
 ```
 
+## Composability
+- **Built on Dialog (portal) + cmdk-style fuzzy matching.** Global Ctrl+K / Cmd+K by default; customize via `keybinding`.
+- **Groups + items are data-driven.** Each item: `{ id, label, icon?, shortcut?, description?, onSelect }`. Labels accept ReactNode for rich rendering; pair with `filterValue` for typeahead matching against a text representation.
+- **renderLabel hook** lets you highlight matched characters in query (`(query) => ReactNode`).
+- **Controlled / uncontrolled** via `open`+`onOpenChange` or `defaultOpen`.
+- **AppCommandPalette (shell)** is the app-wide variant with CommandRegistry — use that for global palettes with dynamically registered commands.
+
 ## Gotchas
 - Opens with Ctrl+K / Cmd+K by default
 - Items animate in with staggered slide-up (30ms delay cascade); groups fade in; active item icon/shortcut highlight in interactive color (v0.15.0)
@@ -4138,6 +4937,12 @@ const [open, setOpen] = useState(false)
 />
 ```
 
+## Composability
+- **Built on AlertDialog** — non-dismissible (no click-outside, Cancel-first focus), portal-rendered.
+- **Controlled-only.** Parent owns `open` + `onOpenChange`.
+- **onConfirm can be async.** `loading=true` replaces confirm text with "Processing..." and disables both buttons. Typical: setLoading(true) → await action() → setLoading(false) + setOpen(false).
+- **Stays open after confirm** — close via onOpenChange. Keeps the modal up on errors or for chained confirmations.
+
 ## Gotchas
 - Dialog stays open after confirm — consumer must close it via `onOpenChange`
 - Built on AlertDialog internally
@@ -4174,6 +4979,12 @@ const [open, setOpen] = useState(false)
 </ContentCard>
 ```
 
+## Composability
+- **Server-safe higher-level Card** — wraps ui/Card with conventional header/title/actions/footer slots.
+- **When to use:** List rows, dashboard tiles, any "card with title + optional actions + body + optional footer" pattern. Use raw ui/Card for custom layouts or when you need accent bars.
+- **Slot precedence:** `header` beats `headerTitle`. Use `headerTitle` for simple strings, `header` for rich content.
+- **padding variants** (default/compact/spacious/none) set once on ContentCard; the underlying Card size cascade propagates.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - Use `headerTitle` for simple text headers; use `header` for custom header content
@@ -4298,6 +5109,16 @@ PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'l
 <TimePicker value={time} onChange={setTime} format="24h" minuteStep={15} />
 ```
 
+## Composability
+- **7 sub-components in one kit:** DatePicker, DateRangePicker, DateTimePicker, TimePicker, CalendarGrid, MonthPicker, YearPicker, Presets. Built on Popover (trigger + calendar content) + date-fns.
+- **Layered abstractions:**
+  - High-level: DatePicker / DateRangePicker / DateTimePicker / TimePicker (use these 95% of the time — Popover-wrapped, single-field pickers with formatted value display).
+  - Low-level: CalendarGrid / MonthPicker / YearPicker (use for custom picker layouts, inline calendars, dashboards with embedded date selection).
+- **useCalendar hook** manages month navigation state — use it when building custom picker UI (e.g. inline calendar with custom header).
+- **Presets component** is standalone — drop it next to a DateRangePicker's calendar for quick-select sidebars (Today / Last 7 days / This month / etc.).
+- **Events on calendar:** CalendarGrid accepts `events: { date, color, label }[]` — renders up to 3 colored dots per day cell. Useful for availability / booked-days highlights.
+- **min/max/disabledDates** are shared contract across the whole family — pass the same bounds config to any date picker variant.
+
 ## Gotchas
 - TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful
 - CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases
@@ -4338,6 +5159,13 @@ PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'l
 <DeadlineIndicator deadline={task.dueDate} warningThreshold={2880} criticalThreshold={480} />
 ```
 
+## Composability
+- **Server-safe inline status** — renders a colored text label ("2d left" / "3h left" / "Overdue by 1d") with optional clock icon prefix.
+- **Threshold-driven color:** `warningThreshold` + `criticalThreshold` drive the green→yellow→red progression. Tune per use case (billing deadlines vs. task due dates have different urgency cadences).
+- **Composes inside Card, StatusBadge, DataTable cells** — anywhere a short inline deadline string fits.
+- **Doesn't live-update** — uses `Date.now()` at render time. For ticking timestamps, re-render via a parent interval or use a dedicated "time ago" library.
+- For static absolute timestamps (not relative), set `format="absolute"` — useful when you want the exact date rendered with semantic color coding.
+
 ## Gotchas
 - Color is semantic: green (on-track) -> yellow (warning threshold) -> red (critical/overdue)
 - Overdue deadlines show bold red text with "Overdue by Xd/h/m"
@@ -4381,6 +5209,14 @@ EmojiPicker, EmojiPickerPopover
 <EmojiPicker onSelect={handleEmoji} theme="dark" />
 ```
 
+## Composability
+- **Two exports:** `EmojiPicker` (inline grid, no trigger) and `EmojiPickerPopover` (trigger + popover wrapper). Use EmojiPickerPopover 95% of the time — trigger-on-click is the standard UX.
+- **Wraps @emoji-mart/react**, lazy-loaded with a Skeleton placeholder while the ~200KB bundle fetches. Don't pre-import unless you need it eagerly.
+- **Trigger composition:** EmojiPickerPopover's `children` is the trigger — wrap any Button/IconButton. Typical pairing is an icon-only IconButton with a 😀 label.
+- **TipTap integration:** Use `createEmojiSuggestion(set?)` factory to create a TipTap suggestion plugin that opens the picker on typing `:emoji`. Works with RichChatInput and RichTextEditor.
+- **Theme matching:** `theme="auto"` reads the `.dark` class on `<html>` — matches the DS dark mode toggle automatically. Override with explicit light/dark.
+- **Emoji sets:** Pass `set="apple" | "google" | ...` for consistent cross-platform emoji art (defaults to native OS glyphs).
+
 ## Gotchas
 - Wraps `@emoji-mart/react` which is lazy-loaded — shows a Skeleton placeholder while loading
 - `theme="auto"` reads the `.dark` class on `<html>` to pick light/dark
@@ -4423,6 +5259,14 @@ Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe d
 />
 ```
 
+## Composability
+- **Centered block for "no data" / "no results" states.** Renders icon + title + description + optional action slot.
+- **Icon composition:** Accepts both JSX (`<IconFolder />`) and component references (`IconFolder`). Component refs auto-instantiate with correct sizing. Default icon is the Devalok chakra.
+- **DataTable integration:** Pass an EmptyState component to DataTable's `emptyState` prop; takes precedence over `noResultsText` string.
+- **compact mode** for embedding inside Cards, sidebars, narrow sections. Defaults iconSize to 'sm' in compact mode automatically.
+- **Action slot** typically holds a single primary Button ("Create your first task", "Invite members"). For multi-action, use a div + flex with gap.
+- No longer server-safe (Framer Motion entrance animation).
+
 ## Gotchas
 - `icon` accepts both JSX elements (`<IconFolder />`) and component references (`IconFolder`). Component references are auto-instantiated with correct sizing classes.
 - `iconSize` controls icon dimensions regardless of icon type. When `compact=true` and no `iconSize`, defaults to `'sm'`.
@@ -4465,6 +5309,13 @@ Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe d
 <ErrorDisplay error={error} onReset={() => refetch()} />
 ```
 
+## Composability
+- **ErrorDisplay, not ErrorBoundary** — confusingly, the import path is `error-boundary` but the component is `ErrorDisplay`. It renders an error UI; it does NOT catch errors. Pair it with your own ErrorBoundary (from react-error-boundary, Next.js error.tsx, etc.) as the fallback UI.
+- **Auto-detects HTTP status codes** (404, 403, 500) when the `error` object has a `status` field — shows appropriate icon + message.
+- **Dev-only stack trace:** Renders the stack trace only when `process.env.NODE_ENV !== 'production'`. Production users see a clean error page.
+- **onReset for retry:** Pass a callback that re-fetches / resets state. Commonly wired to a react-query `refetch` or router `replace(...)`.
+- Composes with EmptyState for "no data" states (which aren't really errors) — use EmptyState for empty, ErrorDisplay for failed.
+
 ## Gotchas
 - Auto-detects HTTP status codes (404, 403, 500) and shows appropriate icon/message
 - Shows stack trace in development mode only
@@ -4510,6 +5361,14 @@ Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe d
 <FilePreview url="https://youtube.com/watch?v=..." />
 ```
 
+## Composability
+- **Type-auto-detection** from URL + mimeType routes to the right renderer (image / pdf / video / audio / embed). For ambiguous URLs, pass `type` explicitly.
+- **Heavy deps are lazy-loaded** — react-pdf (PDF), react-zoom-pan-pinch (Image zoom) are only fetched when first needed. Skeleton placeholder while loading. Don't pre-import.
+- **Composes inside Dialog/Sheet** — common pattern: thumbnail in a list → click to open a Dialog with `<FilePreview>` filling it.
+- **Embed URL normalization:** YouTube/Vimeo/Figma/Loom URLs auto-convert to embed format. Pass the original share URL; FilePreview handles it.
+- **PDF worker from unpkg CDN** — for offline apps, override `pdfjs.GlobalWorkerOptions.workerSrc` in your app entry.
+- **Download + error fallback** built in — if the file fails to load, users still get a download link.
+
 ## Gotchas
 - Image/PDF lazy-loaded (Skeleton on first render)
 - PDF worker from unpkg CDN — configure workerSrc for offline apps
@@ -4569,6 +5428,14 @@ FilterBar, FilterSelect, FilterMultiSelect
 </FilterBar>
 ```
 
+## Composability
+- **FilterBar + FilterSelect + FilterMultiSelect** — three-part kit. FilterBar is the toolbar container; FilterSelect/FilterMultiSelect are the individual filter controls.
+- **size propagates via context** from FilterBar to every FilterSelect/FilterMultiSelect child. Don't set size on individual filters.
+- **Children MUST be direct** — the size cascade breaks if filters are wrapped in extra divs. Use React fragments or let them be direct children.
+- **Active filter highlight:** FilterSelect/FilterMultiSelect auto-show an accent border when their value is set (non-empty array for multi, non-"all" for single).
+- **Pair with DataTable or any list:** FilterBar sits above a DataTable/list; `searchValue` + `onSearchChange` drive global filter; individual filters drive column filters via your own state management.
+- **"Clear all" convention:** Passing `onClearAll` renders a Reset button that's your escape hatch — implement it to clear all filter state in one call.
+
 ## Gotchas
 - FilterSelect and FilterMultiSelect must be direct children of FilterBar to inherit the size context
 - FilterSelect uses `"all"` as the sentinel value for "no filter" — do not use `"all"` as a real option value
@@ -4601,6 +5468,12 @@ FilterBar, FilterSelect, FilterMultiSelect
 </FormSection>
 ```
 
+## Composability
+- **Visual grouping of related FormFields.** Wraps its children with a title + description + horizontal rule separator. No state, no context.
+- **collapsible mode** wraps content in a Collapsible — useful for "Advanced settings" or optional form sections. `defaultOpen={false}` for initially-closed.
+- **Pairs with FormField:** Each form control inside should be a FormField for consistent label + helper text + validation. FormSection doesn't auto-wrap; you still structure each field yourself.
+- **Not a page-level header** — for a full form's main heading use PageHeader. FormSection is mid-form, between field groups.
+
 ## Gotchas
 - `defaultOpen` only applies when `collapsible={true}` — otherwise the section is always open
 - Renders a horizontal rule between the header and content automatically
@@ -4621,6 +5494,12 @@ FilterBar, FilterSelect, FilterMultiSelect
 <GlobalLoading isLoading={isNavigating} />
 ```
 
+## Composability
+- **Thin top-of-viewport progress bar** — for route-level navigation indicators (NProgress-style). Fixed at the top; z-toast layer.
+- **Wire to router events:** Pair with Next.js `useRouter` + navigation events, or react-router's `useNavigation`, or a custom global loading state in Redux/Zustand. Set `isLoading={true}` during transit, `false` when landed.
+- **Not for in-page loading** — use Spinner, Skeleton, or LoadingSkeleton for component-level loading states. GlobalLoading is strictly for cross-route / full-page transitions.
+- **Auto-unmounts when isLoading=false** — no need to manage visibility via classes or conditional rendering.
+
 ## Gotchas
 - Fixed-position bar at top of viewport (z-toast layer)
 - Renders nothing when `isLoading` is false
@@ -4658,6 +5537,14 @@ FilterBar, FilterSelect, FilterMultiSelect
 />
 ```
 
+## Composability
+- **contentEditable-based** — the text IS the editor (Notion / Linear / Figma layer-name pattern). No separate input field appears.
+- **Keyboard contract:** Click to focus (auto-selects text, like Finder rename). Type to edit. Enter saves, Escape reverts. Paste strips rich content.
+- **Async save:** `onSave` can return a Promise — InlineEdit shows a spinner and disables editing while pending. On rejection, text reverts to the original value automatically.
+- **Accessibility:** Accepts `aria-label` and `aria-labelledby` (forwarded to the role="textbox" span) — required when the text isn't self-descriptive. Falls back to `placeholder` as label when neither is provided.
+- **Not inside FormField** — InlineEdit is for in-place editing of existing content (task title, project name); use regular FormField + Input for traditional forms.
+- **textClassName for typography control:** Pass `"text-ds-lg font-semibold"` to make it look like a heading without changing the underlying element.
+
 ## Gotchas
 - Uses contentEditable — the text IS the editor. No input field appears.
 - Click to focus → cursor appears in text. Type to edit. Enter saves. Escape reverts.
@@ -4707,6 +5594,13 @@ Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
 <ListSkeleton rows={10} showAvatar={false} />
 ```
 
+## Composability
+- **Pre-composed skeleton layouts** — CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton. Each mimics the shape of a common DS layout so users see meaningful loading placeholders.
+- **Built on ui/Skeleton** — for custom loading layouts, use Skeleton directly (rectangle/circle/text variants). These composed versions are just opinionated shape combinations.
+- **Server-safe** — use during SSR for initial-paint skeletons in Next.js app router (while server data streams in).
+- **Pairs with conditional rendering:** `{isLoading ? <TableSkeleton rows={8} /> : <DataTable data={rows} />}`.
+- **PageSkeletons (separate file)** provides full-page placeholders (DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton) — use those for route-level loading states.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are pre-composed skeleton layouts — for individual skeleton shapes, use the `Skeleton` UI component
@@ -4739,6 +5633,15 @@ Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
 <MarkdownViewer content={trustedHtml} allowHtml />
 ```
 
+## Composability
+- **Read-only markdown renderer.** For editing, use RichTextEditor (TipTap-based). MarkdownViewer is strictly for display.
+- **Built on react-markdown + remark-gfm** — GFM tables, strikethrough, task lists supported out of the box.
+- **Syntax highlighting is lazy:** Code blocks with a language fence (```ts, ```python) lazy-load react-syntax-highlighter. First render shows a plain `<pre>` fallback. Don't pre-import.
+- **Security posture:** Raw HTML is stripped by default — `allowHtml={true}` must be explicit, and ONLY for trusted content (XSS vector otherwise).
+- **Links open external by default** (`target="_blank"` + `rel="noopener noreferrer"`). Override via `linkTarget`.
+- **compact mode** for inline use (comments, message bubbles). Default spacing is for article-body content.
+- **Pairs with Chat's Message.Body** — render markdown from user messages safely. Always keep `allowHtml={false}` for user-generated content.
+
 ## Gotchas
 - Code blocks with a language fence are syntax-highlighted via `react-syntax-highlighter` (lazy-loaded) — the first render shows a plain `<pre>` fallback
 - GFM (tables, strikethrough, task lists) is supported via `remark-gfm`
@@ -4788,6 +5691,13 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 </MasterDetail>
 ```
 
+## Composability
+- **Responsive list+detail layout.** Desktop: side-by-side panels. Mobile (below `breakpoint`): stacked, mutually exclusive (list OR detail, controlled by `selected`).
+- **Compound structure:** `MasterDetail.List` contains `MasterDetail.ListItem[]` (interactive). `MasterDetail.Detail` holds the currently-selected view.
+- **onBack is required for mobile** — renders the back button in Detail pane. Omitting it leaves users stranded once they drill into an item on mobile.
+- **SSR gotcha:** Uses `window.matchMedia` — initial SSR render picks desktop mode; hydrates to mobile mode if viewport is narrow. If that causes layout shift, consider rendering this only after mount (via `useState(false)` + `useEffect`).
+- **Pairs with EmptyState** — render EmptyState inside Detail when `selected === null` on desktop ("Pick an item to get started").
+
 ## Gotchas
 - On mobile (below breakpoint), List and Detail are mutually exclusive — selecting an item hides the list
 - The `onBack` callback is required for the mobile back button to appear in the Detail pane
@@ -4816,6 +5726,13 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 </MemberPicker>
 ```
 
+## Composability
+- **Trigger + Popover + search list.** Pass any button/element as `children` to act as the trigger. Typical pairing: outline Button that says "Assign" or an IconButton with avatar overflow.
+- **Single vs multi:** `multiple={true}` allows multiple selections; `false` (default) replaces the previous selection. `selectedIds` is always an array in both modes — consumer controls semantics.
+- **onSelect with a single ID:** Fires once per click with one memberId. Toggle logic in multi mode is consumer responsibility (derive the new array from the click).
+- **Avatar display:** Uses ui/Avatar internally — supply `avatar` URL in the member object, fallback to initials from `name`.
+- **For general-purpose multi-select** (non-members), use MultiSelectPopover which has the same popover+search pattern without member-specific avatar rendering.
+
 ## Gotchas
 - `children` is used as the trigger element (e.g., a Button)
 - `onSelect` is called with a single `memberId` — toggle logic is up to the consumer
@@ -4876,6 +5793,17 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 </MultiSelectPopover>
 ```
 
+## Composability
+- **Generalized multi-select popover** — picks from a fixed list (items) or grouped list (groups), with search, async search, and custom rendering.
+- **Items vs groups (mutually exclusive):** Pass `items` for flat lists, `groups` for sectioned lists. Don't pass both.
+- **Async search via onSearch:** When provided, local filtering is disabled — the callback owns filtering and returns a new list. `searchDebounce` (default 300ms) throttles calls.
+- **renderItem escape hatch:** Pass `(item, selected) => ReactNode` for custom item rendering (avatar + multi-line descriptions, etc.). Built-in default renders image + label + description.
+- **maxSelections behavior:** At the limit, clicking a new item REPLACES the oldest selection (FIFO). `maxSelections={1}` effectively acts as single-select.
+- **MultiSelectPopover vs Combobox vs MemberPicker:**
+  - Combobox = form-field multi-select (typeahead + selection in place)
+  - MultiSelectPopover = button-triggered popup for bulk selection (good for "Assign to" / "Add tags" scenarios)
+  - MemberPicker = MultiSelectPopover specialized for team-member UI
+
 ## Gotchas
 - Supply either `items` (flat) or `groups` (sectioned), not both
 - When `onSearch` is provided, local filtering is disabled — the callback must return results
@@ -4919,6 +5847,13 @@ MasterDetail (root), MasterDetail.List, MasterDetail.Detail, MasterDetail.ListIt
 />
 ```
 
+## Composability
+- **Server-safe page-top header** with title + subtitle + breadcrumbs + actions slot. Renders Breadcrumb internally from the `breadcrumbs` array.
+- **Auto-derived title:** If `title` is omitted, the last breadcrumb's `label` becomes the h1. Saves duplication when the page title matches the breadcrumb leaf.
+- **Breadcrumb contract:** Last item should NOT have an `href` (it's the current page — renders as BreadcrumbPage, not a link). Items with `href` render as BreadcrumbLink.
+- **actions slot:** Typically one to three buttons (Save, Cancel, More). For larger action groups, use ButtonGroup or a toolbar.
+- **Not for tabs / sub-navigation** — pair with Tabs rendered below PageHeader for that.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - If `title` is omitted, the last breadcrumb's `label` is used as the page title
@@ -4951,6 +5886,16 @@ Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
 <TaskDetailSkeleton />
 ```
 
+## Composability
+- **Full-page skeleton layouts** for route-level loading states. Each mimics a common page shape (dashboard tiles, project list with filters, task detail with sidebar).
+- **Server-safe** — use in Next.js app router `loading.tsx` files for instant route-transition feedback while data streams.
+- **Built on LoadingSkeleton + ui/Skeleton** — these just assemble the pre-built regional skeletons into page-shaped layouts.
+- **When to use which skeleton tier:**
+  - `<Skeleton>` (ui) — single shape for a single element
+  - `<CardSkeleton>` / `<TableSkeleton>` (LoadingSkeleton) — individual region shape
+  - `<DashboardSkeleton>` / etc. (PageSkeletons) — full page placeholder
+- **Fixed layout structure** — the className prop adjusts the outer container, but internal layout isn't customizable. For custom page skeletons, compose LoadingSkeleton pieces yourself.
+
 ## Gotchas
 - Server-safe: can be imported directly in Next.js Server Components
 - These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components
@@ -4983,6 +5928,13 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
 <PriorityIndicator priority="low" display="compact" />
 ```
 
+## Composability
+- **Server-safe priority label** — icon + color + text for task / issue priority.
+- **Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.
+- **display="compact"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display="full"` (default) in free space.
+- **Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.
+- Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon.
+
 ## Gotchas
 - Case-insensitive — "low" and "LOW" both work
 - Server-safe: can be imported directly in Next.js Server Components
@@ -4994,40 +5946,6 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
 
 ### v0.1.0
 - **Added** Initial release
-# ResponsiveOverlay
-
-- Import: @devalok/shilp-sutra/composed/responsive-overlay
-- Server-safe: No
-- Category: composed
-
-## Props
-    open: boolean
-    onOpenChange: (open: boolean) => void
-    title: string
-    description: string
-    breakpoint: "sm" | "md" (below this renders as bottom Sheet; above as Dialog)
-    children: ReactNode
-    className: string
-
-## Defaults
-    breakpoint="md"
-
-## Example
-```jsx
-<ResponsiveOverlay
-  open={open}
-  onOpenChange={setOpen}
-  title="Edit task"
-  description="Update the task details"
->
-  <TaskForm />
-</ResponsiveOverlay>
-```
-
-## Gotchas
-- Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
-- Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration
-- Title and description are optional; if omitted, no header is rendered in either mode
 # RichChatInput
 
 - Import: @devalok/shilp-sutra/composed/rich-chat-input
@@ -5097,6 +6015,18 @@ SlashCommandGroup: { label: string; commands: SlashCommand[] }
 />
 ```
 
+## Composability
+- **Chat-specific TipTap editor** — purpose-built for AI + human messaging. Built on RichTextEditor primitives but pre-configured for the chat UX (auto-resize, Enter-to-send, inline toolbar).
+- **Variant drives the UX envelope:**
+  - `compact` — 2-3 line inline (chat bubble composer)
+  - `expanded` — 5+ lines with always-visible toolbar (AI prompt input)
+  - `minimal` — single line, toolbar on focus (reply composer, quick comment)
+- **Toolbar is opt-in per feature:** Icons only appear when their corresponding handler/prop is set. `onFileUpload` → attach button appears. `slashCommands` → slash button appears. `mentions` or `onMentionSearch` → @ button appears.
+- **Composes with Message from ui/chat:** RichChatInput is the composer; Message is the read-only render of the message after send. Use them together for a complete chat UX (RichChatInput at the bottom, MessageList above).
+- **TipTap is bundled** — no need to install `@tiptap/*` directly.
+- **For general rich text editing** (not chat — long-form docs, notes), use RichTextEditor instead.
+- **isStreaming + onCancel** — when the receiving side is streaming a response, show a stop button in place of send. Standard AI chat pattern.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Enter sends by default; use `enterBehavior="newline"` for long-form composition (Cmd/Ctrl+Enter always sends)
@@ -5165,6 +6095,15 @@ MentionItem: { id: string; label: string; avatar?: string }
 <RichTextViewer content={savedHtml} />
 ```
 
+## Composability
+- **Two exports — editor + viewer.** RichTextEditor for composition; RichTextViewer for read-only rendering of saved HTML. Both share the same prose styling so round-trip display matches the editor.
+- **TipTap v3 bundled** — no `@tiptap/*` install needed. Consumers can't mix in arbitrary TipTap extensions without forking.
+- **Toolbar whitelist via `toolbar` prop:** Pass an array of ToolbarItem names to show only those buttons. Omit to show all. Dividers auto-collapse between empty groups.
+- **Image upload:** Without `onImageUpload`, pasted/dropped images are inlined as base64 (HTML bloats fast). Provide the handler to upload and return a URL.
+- **Mentions:** Static `mentions` array OR async `onMentionSearch` (which takes precedence). The viewer always renders mentions correctly from saved HTML — no mention props needed on the viewer side.
+- **For chat composition specifically** (AI + team chat with streaming / slash commands), use RichChatInput — it's built on the same foundation but pre-configured for chat UX.
+- **Pairs with MarkdownViewer** — many teams use RichTextEditor for compose (WYSIWYG), but render saved content as markdown for simpler serialization. Convert HTML ↔ markdown at the storage boundary.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers
@@ -5229,6 +6168,14 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 />
 ```
 
+## Composability
+- **Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.
+- **Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.
+- **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).
+- **Color vocabulary matches the DS** — `primary/success/warning/error/info/neutral`. Map your event types to these at the data layer.
+- **endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.
+- **Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`.
+
 ## Gotchas
 - `endHour` is exclusive — `endHour=18` means the last visible slot starts at 17:30 (with default 30min slots)
 - `onSlotClick` fires when clicking an empty time slot — useful for creating new events
@@ -5260,6 +6207,13 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 </SimpleTooltip>
 ```
 
+## Composability
+- **One-liner Tooltip** — wraps TooltipProvider + Tooltip + TooltipTrigger + TooltipContent so consumers don't have to manually compose them for a simple label.
+- **When to use:** 90% of tooltip use cases (icon-only button labels, abbreviated text expansions, secondary info). Use the ui/Tooltip compound for advanced cases (controlled open, nested triggers, custom animations).
+- **Auto-provides its own TooltipProvider** — safe to drop anywhere. You can still wrap a broader TooltipProvider at layout level for shared `delayDuration`; SimpleTooltip respects it if present.
+- **Content must be inert** — same rule as ui/Tooltip. For interactive popped content, use Popover or HoverCard.
+- **Pairs with IconButton** — the canonical pattern for labeled icon buttons.
+
 ## Gotchas
 - Wraps the full Tooltip compound (Provider + Tooltip + Trigger + Content) into one component — no need for TooltipProvider
 - Unlike the low-level Tooltip, SimpleTooltip does not require wrapping in a TooltipProvider
@@ -5300,6 +6254,16 @@ Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe
 <StatusBadge status="active" onClick={() => openStatusPicker()} />
 ```
 
+## Composability
+- **Semantic pill for workflow status.** Built on ui/Badge but with opinionated status → color mapping (active=success, pending=warning, rejected=error, etc.).
+- **status vs color discriminated union:** Pass either `status` (auto-mapped color) or `color` (explicit). Don't pass both — `color` wins if you do.
+- **Interactive mode:** Passing `onClick` renders as a `<button>` with a trailing chevron — common pattern for opening a status picker dropdown. Pair with a Popover or DropdownMenu for the status selector.
+- **Pairs with DataTable, Card headers, activity feeds** — anywhere an inline status pill fits. Use `size="sm"` for dense rows.
+- **StatusBadge vs ui/Badge vs StatusDot:**
+  - StatusBadge = workflow status pill with built-in status semantics
+  - ui/Badge = generic badge with full color/variant/shape control
+  - StatusDot = tiny presence indicator (no label pill)
+
 ## Gotchas
 - When `color` is set, it takes priority over `status` for styling
 - Props use a discriminated union — pass either `status` or `color`, not both
@@ -5367,6 +6331,14 @@ AppCommandPaletteUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Shell-level wrapper around composed/CommandPalette** — adds opinionated app conventions: user-aware admin command groups, search result integration, navigation dispatch.
+- **Required setup:** Place inside `<CommandRegistryProvider>` (which owns the list of page items). Typically at app root next to TopBar.
+- **Router integration via onNavigate:** Pass `(path) => router.push(path)` (Next.js) or equivalent for your framework. All page command clicks funnel through this callback.
+- **Server-search integration:** Pass `onSearch` + `searchResults` + `onSearchResultSelect` for async search (API calls). `isSearching` drives a loading state. When these props are omitted, AppCommandPalette falls back to local filtering of registered pages.
+- **Admin gating:** `isAdmin=true` surfaces `adminPages` from CommandRegistry. Takes precedence over `user.role`-based detection so you can force admin mode during testing / impersonation.
+- **For scoped, non-app-wide palettes** (per-page command trees, custom popups), use composed/CommandPalette directly without the Registry layer.
+
 ## Gotchas
 - Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
 - `isAdmin` takes precedence over `user.role` for showing admin command groups
@@ -5408,6 +6380,18 @@ BottomNavbarUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use AppSidebar instead.
+- **Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example:
+  ```jsx
+  const isMobile = useIsMobile()
+  return isMobile ? <BottomNavbar ... /> : <AppSidebar ... />
+  ```
+- **Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a "More" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.
+- **Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.
+- **Badge numbers** cap at 99+ (same as BadgeIndicator pattern).
+- **Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`.
+
 ## Gotchas
 - Designed for mobile viewports — fixed to bottom of screen
 - Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet
@@ -5470,6 +6454,13 @@ CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, key
 </CommandRegistryProvider>
 ```
 
+## Composability
+- **Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.
+- **Place at app root** — wrap both AppCommandPalette and the rest of the app inside `<CommandRegistryProvider>`. Positioning matters: any AppCommandPalette outside the provider gets `useCommandRegistry() === null` and falls back to minimal functionality.
+- **Separation of pages vs adminPages** — the palette filters based on user role / `isAdmin` flag. Keep admin-only routes in the adminPages array to avoid leaking them to regular users.
+- **useCommandRegistry()** is the consumer hook — returns the full registry or null. Use in your own command-aware components (e.g. a Spotlight-style keyboard-search embed elsewhere in the app).
+- **Works with LinkProvider** — CommandPaletteItems navigate via `onNavigate` prop on AppCommandPalette, which routes to your framework's Link component.
+
 ## Gotchas
 - Provides the command registry context consumed by AppCommandPalette
 - Place at app root, wrapping both AppCommandPalette and the rest of the app
@@ -5508,6 +6499,21 @@ import Link from 'next/link'
 </LinkProvider>
 ```
 
+## Composability
+- **The framework router bridge for all shell components.** Without LinkProvider, AppSidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.
+- **Required setup:**
+  ```tsx
+  // Next.js
+  import Link from 'next/link'
+  <LinkProvider component={Link}>
+    <App />
+  </LinkProvider>
+  ```
+- **Place at app root** — above every shell component that renders nav links.
+- **component must be forwardRef** (Next.js Link, Remix Link, react-router Link all qualify). Custom components need to forward ref + forward className + forward all anchor props.
+- **Consumer components use `useLink()`** — returns the registered component or falls back to plain `<a>`. Your own components can consume this hook to integrate with the same router abstraction.
+- **ui-category components don't consume LinkProvider** — they use `asChild` for router integration (e.g. `<Button asChild><NextLink ...>...</NextLink></Button>`). LinkProvider is shell-specific because shell components embed link arrays (can't use asChild per-item without breaking the data-driven API).
+
 ## Gotchas
 - Without LinkProvider, shell components render plain `<a>` tags (full page reloads)
 - Place at app root, wrapping all shell components that render navigation links
@@ -5565,6 +6571,16 @@ NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger',
 />
 ```
 
+## Composability
+- **Bell + Popover + notification list** — renders the bell button with unread count badge and a popover list on click.
+- **Typical placement:** Inside `<TopBar.Right>` — common pattern is `<TopBar.IconButton>` for utility actions PLUS `<NotificationCenter>` for the bell.
+- **No hardcoded routes** — `getNotificationRoute` is the consumer's routing decision. Return the correct path per notification type (task → `/tasks/:id`, comment → `/threads/:id`, etc.) or null for non-routable notifications.
+- **onNavigate** fires when a notification with a route is clicked — wire to your router's push/navigate call.
+- **Pagination:** Pass `hasMore` + `onFetchMore` for infinite-scroll of older notifications.
+- **emptySlot + footerSlot + headerActions** are content slots for customization — keep the bell+popover shell, swap the inside.
+- **Pairs with NotificationPreferences** (separate page component) for letting users configure which notification tiers/channels they want to receive.
+- **onDismiss** is optional — when provided, per-notification X buttons appear. Otherwise mark-as-read is the only dismissal mechanism.
+
 ## Gotchas
 - Typically rendered inside TopBar's `notificationSlot` prop
 - `getNotificationRoute` must be provided for clickable notifications — no hardcoded routes
@@ -5616,6 +6632,13 @@ NotificationProject: { id: string, title: string }
 />
 ```
 
+## Composability
+- **Full-page preferences UI** — typically rendered on a settings page (`/settings/notifications`). Not an overlay; not a dropdown.
+- **Per-project preferences** — each preference is tied to a project + channel + tier. Users can mute/unmute and adjust tier (INFO / IMPORTANT / CRITICAL threshold) per project-channel combo.
+- **All callback props support Promise<void>** — integrate with server actions / fetch calls without manual loading state management.
+- **Pairs with NotificationCenter** — NotificationCenter shows notifications in real time (driven by these preferences); NotificationPreferences lets users tune the rules.
+- **Data ownership is consumer-side** — you pass `preferences` + `projects`; NotificationPreferences renders. No built-in persistence or sync.
+
 ## Gotchas
 - Manages per-project notification preferences (channel, tier, mute)
 - All callback props support async (Promise<void>) for server-side operations
@@ -5674,6 +6697,17 @@ SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?:
 />
 ```
 
+## Composability
+- **Opinionated app sidebar** — data-driven via `navGroups`, with user profile header, navigation groups (with optional labels + group actions), and a configurable footer (links + version + optional promo banner).
+- **Required setup (three providers):**
+  - `SidebarProvider` (from ui/sidebar) — owns expanded/collapsed state + cookie persistence
+  - `LinkProvider` — framework router integration for nav item links
+  - `CommandRegistryProvider` (if pairing with AppCommandPalette) — registers the same navGroups so keyboard search finds them
+- **renderItem escape hatch:** Custom per-item rendering (e.g. custom icons per item type, status decorations, hover previews). Return `null` to fall back to default.
+- **Nested navigation:** NavItem's `children: NavSubItem[]` renders a collapsible subsection. Auto-opens if a child matches the current path.
+- **Footer as slot:** `footer` can include links, version info, a ReactNode slot (e.g. theme toggle), and a dismissable promo banner — structure it once, compose.
+- **Pairs with TopBar + BottomNavbar:** Desktop layout = AppSidebar + TopBar. Mobile layout = hide AppSidebar, show BottomNavbar.
+
 ## Gotchas
 - Must be wrapped in SidebarProvider (from ui/sidebar)
 - Requires LinkProvider for framework-specific link components
@@ -5829,6 +6863,17 @@ UserMenuItem fields:
 </TopBar>
 ```
 
+## Composability
+- **Composition-based, NOT data-driven.** Use dot-notation subcomponents (`TopBar.Left`, `TopBar.Center`, `TopBar.Right`, `TopBar.Section`, `TopBar.IconButton`, `TopBar.Title`, `TopBar.UserMenu`) to assemble. No "props config" — explicit JSX.
+- **Two-zone vs three-zone layout** — adding `TopBar.Center` flips the root from `flex` to CSS grid (`1fr auto 1fr`) for true centering. Standard apps are two-zone (Left + Right); dashboards with prominent search are three-zone.
+- **Required providers:**
+  - `SidebarProvider` — for SidebarTrigger inside `TopBar.Left` to work
+  - `LinkProvider` — for TopBar.UserMenu's menu items that use `href`
+- **NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.
+- **UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.
+- **Responsive hiding:** Actions that shouldn't appear on mobile use `className="hidden md:flex"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.
+- **Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region.
+
 ## Gotchas
 - Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.
 - `TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className="hidden md:flex"`) for mobile.