@devalok/shilp-sutra 0.37.0 → 0.37.1

package/docs/components/ui/label.md

@@ -14,8 +14,14 @@
 <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

package/docs/components/ui/link.md

@@ -18,8 +18,15 @@
 <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

package/docs/components/ui/menubar.md

@@ -30,8 +30,17 @@
 </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

package/docs/components/ui/navigation-menu.md

@@ -31,8 +31,17 @@
 </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

package/docs/components/ui/number-input.md

@@ -7,6 +7,8 @@
 ## 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)
@@ -14,6 +16,8 @@
 
 ## Defaults
     value: 0
+    size: "md"
+    state: "default"
     step: 1
     min: Number.MIN_SAFE_INTEGER
     max: Number.MAX_SAFE_INTEGER
@@ -23,6 +27,12 @@
 <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
 

package/docs/components/ui/pagination.md

@@ -36,8 +36,18 @@
 </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

package/docs/components/ui/popover.md

@@ -18,8 +18,17 @@
 </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

package/docs/components/ui/progress-ring.md

@@ -35,6 +35,13 @@
 />
 ```
 
+## 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

package/docs/components/ui/progress.md

@@ -22,6 +22,13 @@
 <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

package/docs/components/ui/radio.md

@@ -4,9 +4,26 @@
 - 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
@@ -22,9 +39,17 @@
 </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

package/docs/components/ui/search-input.md

@@ -26,8 +26,16 @@
 />
 ```
 
+## 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

package/docs/components/ui/segmented-control.md

@@ -31,9 +31,17 @@
 />
 ```
 
+## 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.18.0

package/docs/components/ui/select.md

@@ -6,11 +6,13 @@
 
 ## 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)
@@ -19,7 +21,7 @@
         SelectSeparator
 
 ## Defaults
-    SelectTrigger size: "md"
+    SelectTrigger variant="default", color="default", size="md"
 
 ## Example
 ```jsx
@@ -34,6 +36,15 @@
 </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)

package/docs/components/ui/separator.md

@@ -18,8 +18,15 @@
 <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

package/docs/components/ui/sheet.md

@@ -32,8 +32,18 @@
 </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

package/docs/components/ui/sidebar.md

@@ -4,6 +4,14 @@
 - 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)
@@ -32,6 +40,9 @@
 ## Hook
     useSidebar() => { state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar }
 
+## Defaults
+    SidebarMenuButton variant="default", size="md"
+
 ## Example
 ```jsx
 <SidebarProvider>
@@ -59,9 +70,28 @@
 </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

package/docs/components/ui/skeleton.md

@@ -67,6 +67,13 @@
 <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

package/docs/components/ui/slider.md

@@ -5,7 +5,12 @@
 - 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
@@ -13,9 +18,18 @@
 <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

package/docs/components/ui/spinner.md

@@ -24,6 +24,13 @@
 <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

package/docs/components/ui/split-button.md

@@ -35,6 +35,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

package/docs/components/ui/stack.md

@@ -23,6 +23,14 @@
 </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

package/docs/components/ui/stat-card.md

@@ -47,6 +47,15 @@
 />
 ```
 
+## 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

package/docs/components/ui/status-dot.md

@@ -21,6 +21,15 @@
 <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

package/docs/components/ui/stepper.md

@@ -37,8 +37,16 @@
 </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

package/docs/components/ui/switch.md

@@ -22,9 +22,17 @@
 <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

package/docs/components/ui/table.md

@@ -33,8 +33,16 @@
 </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

package/docs/components/ui/tabs.md

@@ -12,6 +12,8 @@
 
 ### TabsList
     variant: "line" | "contained"
+    size: "sm" | "md" | "lg"
+    orientation: "horizontal" | "vertical"
 
 ### TabsTrigger
     value: string (REQUIRED)
@@ -27,7 +29,7 @@
       TabsContent (value)
 
 ## Defaults
-    TabsList variant: "line"
+    TabsList variant="line", size="md", orientation="horizontal"
 
 ## Example
 ```jsx
@@ -41,8 +43,14 @@
 </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