@devalok/shilp-sutra 0.37.0 → 0.38.0

package/docs/components/ui/file-upload.md

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

package/docs/components/ui/form.md

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

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

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

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

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

package/docs/components/ui/icon-context.md

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

package/docs/components/ui/icon-group.md

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

package/docs/components/ui/icon.md

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

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

@@ -5,17 +5,32 @@
 - 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} />
@@ -30,8 +45,15 @@
 </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

package/docs/components/ui/input.md

@@ -14,8 +14,6 @@
     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
@@ -32,6 +30,13 @@
 <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
@@ -43,6 +48,10 @@
 - 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)

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

@@ -5,8 +5,8 @@
 - 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)
@@ -14,14 +14,18 @@
 
 ## 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' },
@@ -31,16 +35,27 @@
 />
 ```
 
+## 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

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