@devalok/shilp-sutra 0.37.0 → 0.38.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

package/docs/components/ui/text.md

@@ -5,12 +5,9 @@
 - 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"
 
@@ -25,9 +22,17 @@
 <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

package/docs/components/ui/textarea.md

@@ -5,7 +5,7 @@
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg"
+    size: "xs" | "sm" | "md" | "lg"
     state: "default" | "error" | "warning" | "success"
     (plus standard textarea attributes except native "size")
 
@@ -17,6 +17,12 @@
 <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)

package/docs/components/ui/toast.md

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

package/docs/components/ui/toaster.md

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

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

@@ -16,8 +16,11 @@
     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
@@ -28,9 +31,15 @@
 </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

package/docs/components/ui/toggle.md

@@ -7,13 +7,13 @@
 ## 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
@@ -22,8 +22,16 @@
 </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

package/docs/components/ui/tooltip.md

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

package/docs/components/ui/tree-view.md

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

package/docs/components/ui/visually-hidden.md

@@ -12,9 +12,16 @@
 <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