@devalok/shilp-sutra 0.37.0 → 0.37.1

package/docs/components/composed/responsive-overlay.md

@@ -28,6 +28,13 @@
 </ResponsiveOverlay>
 ```
 
+## Composability
+- **One component, two containers.** Above `breakpoint`: centered Dialog. Below: bottom-anchored Sheet. Same content slot, different surface treatment per viewport.
+- **Standard controlled model** — `open` + `onOpenChange` (same shape as Dialog/Sheet).
+- **title + description pattern** — matches Dialog/Sheet's requirement for an accessible heading. Omit both only when the surrounding context makes the purpose obvious (rare).
+- **SSR caveat:** `window.matchMedia` reads on mount — initial SSR render defaults to desktop (Dialog). Hydration flips to Sheet on mobile. Acceptable for most flows; visible layout shift on low-spec devices.
+- **When to use:** Any modal that needs to behave differently on mobile (edit dialogs, filter panels, quick-action menus). For always-the-same behavior, use Dialog or Sheet directly.
+
 ## Gotchas
 - Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
 - Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration

package/docs/components/composed/rich-chat-input.md

@@ -67,6 +67,18 @@ SlashCommandGroup: { label: string; commands: SlashCommand[] }
 />
 ```
 
+## Composability
+- **Chat-specific TipTap editor** — purpose-built for AI + human messaging. Built on RichTextEditor primitives but pre-configured for the chat UX (auto-resize, Enter-to-send, inline toolbar).
+- **Variant drives the UX envelope:**
+  - `compact` — 2-3 line inline (chat bubble composer)
+  - `expanded` — 5+ lines with always-visible toolbar (AI prompt input)
+  - `minimal` — single line, toolbar on focus (reply composer, quick comment)
+- **Toolbar is opt-in per feature:** Icons only appear when their corresponding handler/prop is set. `onFileUpload` → attach button appears. `slashCommands` → slash button appears. `mentions` or `onMentionSearch` → @ button appears.
+- **Composes with Message from ui/chat:** RichChatInput is the composer; Message is the read-only render of the message after send. Use them together for a complete chat UX (RichChatInput at the bottom, MessageList above).
+- **TipTap is bundled** — no need to install `@tiptap/*` directly.
+- **For general rich text editing** (not chat — long-form docs, notes), use RichTextEditor instead.
+- **isStreaming + onCancel** — when the receiving side is streaming a response, show a stop button in place of send. Standard AI chat pattern.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Enter sends by default; use `enterBehavior="newline"` for long-form composition (Cmd/Ctrl+Enter always sends)

package/docs/components/composed/rich-text-editor.md

@@ -47,6 +47,15 @@ MentionItem: { id: string; label: string; avatar?: string }
 <RichTextViewer content={savedHtml} />
 ```
 
+## Composability
+- **Two exports — editor + viewer.** RichTextEditor for composition; RichTextViewer for read-only rendering of saved HTML. Both share the same prose styling so round-trip display matches the editor.
+- **TipTap v3 bundled** — no `@tiptap/*` install needed. Consumers can't mix in arbitrary TipTap extensions without forking.
+- **Toolbar whitelist via `toolbar` prop:** Pass an array of ToolbarItem names to show only those buttons. Omit to show all. Dividers auto-collapse between empty groups.
+- **Image upload:** Without `onImageUpload`, pasted/dropped images are inlined as base64 (HTML bloats fast). Provide the handler to upload and return a URL.
+- **Mentions:** Static `mentions` array OR async `onMentionSearch` (which takes precedence). The viewer always renders mentions correctly from saved HTML — no mention props needed on the viewer side.
+- **For chat composition specifically** (AI + team chat with streaming / slash commands), use RichChatInput — it's built on the same foundation but pre-configured for chat UX.
+- **Pairs with MarkdownViewer** — many teams use RichTextEditor for compose (WYSIWYG), but render saved content as markdown for simpler serialization. Convert HTML ↔ markdown at the storage boundary.
+
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
 - Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers

package/docs/components/composed/schedule-view.md

@@ -29,6 +29,14 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 />
 ```
 
+## Composability
+- **Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.
+- **Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.
+- **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).
+- **Color vocabulary matches the DS** — `primary/success/warning/error/info/neutral`. Map your event types to these at the data layer.
+- **endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.
+- **Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`.
+
 ## Gotchas
 - `endHour` is exclusive — `endHour=18` means the last visible slot starts at 17:30 (with default 30min slots)
 - `onSlotClick` fires when clicking an empty time slot — useful for creating new events

package/docs/components/composed/simple-tooltip.md

@@ -21,6 +21,13 @@
 </SimpleTooltip>
 ```
 
+## Composability
+- **One-liner Tooltip** — wraps TooltipProvider + Tooltip + TooltipTrigger + TooltipContent so consumers don't have to manually compose them for a simple label.
+- **When to use:** 90% of tooltip use cases (icon-only button labels, abbreviated text expansions, secondary info). Use the ui/Tooltip compound for advanced cases (controlled open, nested triggers, custom animations).
+- **Auto-provides its own TooltipProvider** — safe to drop anywhere. You can still wrap a broader TooltipProvider at layout level for shared `delayDuration`; SimpleTooltip respects it if present.
+- **Content must be inert** — same rule as ui/Tooltip. For interactive popped content, use Popover or HoverCard.
+- **Pairs with IconButton** — the canonical pattern for labeled icon buttons.
+
 ## Gotchas
 - Wraps the full Tooltip compound (Provider + Tooltip + Trigger + Content) into one component — no need for TooltipProvider
 - Unlike the low-level Tooltip, SimpleTooltip does not require wrapping in a TooltipProvider

package/docs/components/composed/status-badge.md

@@ -28,6 +28,16 @@ Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe
 <StatusBadge status="active" onClick={() => openStatusPicker()} />
 ```
 
+## Composability
+- **Semantic pill for workflow status.** Built on ui/Badge but with opinionated status → color mapping (active=success, pending=warning, rejected=error, etc.).
+- **status vs color discriminated union:** Pass either `status` (auto-mapped color) or `color` (explicit). Don't pass both — `color` wins if you do.
+- **Interactive mode:** Passing `onClick` renders as a `<button>` with a trailing chevron — common pattern for opening a status picker dropdown. Pair with a Popover or DropdownMenu for the status selector.
+- **Pairs with DataTable, Card headers, activity feeds** — anywhere an inline status pill fits. Use `size="sm"` for dense rows.
+- **StatusBadge vs ui/Badge vs StatusDot:**
+  - StatusBadge = workflow status pill with built-in status semantics
+  - ui/Badge = generic badge with full color/variant/shape control
+  - StatusDot = tiny presence indicator (no label pill)
+
 ## Gotchas
 - When `color` is set, it takes priority over `status` for styling
 - Props use a discriminated union — pass either `status` or `color`, not both

package/docs/components/shell/app-command-palette.md

@@ -31,6 +31,14 @@ AppCommandPaletteUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Shell-level wrapper around composed/CommandPalette** — adds opinionated app conventions: user-aware admin command groups, search result integration, navigation dispatch.
+- **Required setup:** Place inside `<CommandRegistryProvider>` (which owns the list of page items). Typically at app root next to TopBar.
+- **Router integration via onNavigate:** Pass `(path) => router.push(path)` (Next.js) or equivalent for your framework. All page command clicks funnel through this callback.
+- **Server-search integration:** Pass `onSearch` + `searchResults` + `onSearchResultSelect` for async search (API calls). `isSearching` drives a loading state. When these props are omitted, AppCommandPalette falls back to local filtering of registered pages.
+- **Admin gating:** `isAdmin=true` surfaces `adminPages` from CommandRegistry. Takes precedence over `user.role`-based detection so you can force admin mode during testing / impersonation.
+- **For scoped, non-app-wide palettes** (per-page command trees, custom popups), use composed/CommandPalette directly without the Registry layer.
+
 ## Gotchas
 - Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
 - `isAdmin` takes precedence over `user.role` for showing admin command groups

package/docs/components/shell/bottom-navbar.md

@@ -28,6 +28,18 @@ BottomNavbarUser: { name: string, role?: string }
 />
 ```
 
+## Composability
+- **Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use AppSidebar instead.
+- **Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example:
+  ```jsx
+  const isMobile = useIsMobile()
+  return isMobile ? <BottomNavbar ... /> : <AppSidebar ... />
+  ```
+- **Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a "More" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.
+- **Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.
+- **Badge numbers** cap at 99+ (same as BadgeIndicator pattern).
+- **Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`.
+
 ## Gotchas
 - Designed for mobile viewports — fixed to bottom of screen
 - Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet

package/docs/components/shell/command-registry.md

@@ -38,6 +38,13 @@ CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, key
 </CommandRegistryProvider>
 ```
 
+## Composability
+- **Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.
+- **Place at app root** — wrap both AppCommandPalette and the rest of the app inside `<CommandRegistryProvider>`. Positioning matters: any AppCommandPalette outside the provider gets `useCommandRegistry() === null` and falls back to minimal functionality.
+- **Separation of pages vs adminPages** — the palette filters based on user role / `isAdmin` flag. Keep admin-only routes in the adminPages array to avoid leaking them to regular users.
+- **useCommandRegistry()** is the consumer hook — returns the full registry or null. Use in your own command-aware components (e.g. a Spotlight-style keyboard-search embed elsewhere in the app).
+- **Works with LinkProvider** — CommandPaletteItems navigate via `onNavigate` prop on AppCommandPalette, which routes to your framework's Link component.
+
 ## Gotchas
 - Provides the command registry context consumed by AppCommandPalette
 - Place at app root, wrapping both AppCommandPalette and the rest of the app

package/docs/components/shell/link-context.md

@@ -28,6 +28,21 @@ import Link from 'next/link'
 </LinkProvider>
 ```
 
+## Composability
+- **The framework router bridge for all shell components.** Without LinkProvider, AppSidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.
+- **Required setup:**
+  ```tsx
+  // Next.js
+  import Link from 'next/link'
+  <LinkProvider component={Link}>
+    <App />
+  </LinkProvider>
+  ```
+- **Place at app root** — above every shell component that renders nav links.
+- **component must be forwardRef** (Next.js Link, Remix Link, react-router Link all qualify). Custom components need to forward ref + forward className + forward all anchor props.
+- **Consumer components use `useLink()`** — returns the registered component or falls back to plain `<a>`. Your own components can consume this hook to integrate with the same router abstraction.
+- **ui-category components don't consume LinkProvider** — they use `asChild` for router integration (e.g. `<Button asChild><NextLink ...>...</NextLink></Button>`). LinkProvider is shell-specific because shell components embed link arrays (can't use asChild per-item without breaking the data-driven API).
+
 ## Gotchas
 - Without LinkProvider, shell components render plain `<a>` tags (full page reloads)
 - Place at app root, wrapping all shell components that render navigation links

package/docs/components/shell/notification-center.md

@@ -44,6 +44,16 @@ NotificationAction: { label: string, variant?: 'primary' | 'default' | 'danger',
 />
 ```
 
+## Composability
+- **Bell + Popover + notification list** — renders the bell button with unread count badge and a popover list on click.
+- **Typical placement:** Inside `<TopBar.Right>` — common pattern is `<TopBar.IconButton>` for utility actions PLUS `<NotificationCenter>` for the bell.
+- **No hardcoded routes** — `getNotificationRoute` is the consumer's routing decision. Return the correct path per notification type (task → `/tasks/:id`, comment → `/threads/:id`, etc.) or null for non-routable notifications.
+- **onNavigate** fires when a notification with a route is clicked — wire to your router's push/navigate call.
+- **Pagination:** Pass `hasMore` + `onFetchMore` for infinite-scroll of older notifications.
+- **emptySlot + footerSlot + headerActions** are content slots for customization — keep the bell+popover shell, swap the inside.
+- **Pairs with NotificationPreferences** (separate page component) for letting users configure which notification tiers/channels they want to receive.
+- **onDismiss** is optional — when provided, per-notification X buttons appear. Otherwise mark-as-read is the only dismissal mechanism.
+
 ## Gotchas
 - Typically rendered inside TopBar's `notificationSlot` prop
 - `getNotificationRoute` must be provided for clickable notifications — no hardcoded routes

package/docs/components/shell/notification-preferences.md

@@ -32,6 +32,13 @@ NotificationProject: { id: string, title: string }
 />
 ```
 
+## Composability
+- **Full-page preferences UI** — typically rendered on a settings page (`/settings/notifications`). Not an overlay; not a dropdown.
+- **Per-project preferences** — each preference is tied to a project + channel + tier. Users can mute/unmute and adjust tier (INFO / IMPORTANT / CRITICAL threshold) per project-channel combo.
+- **All callback props support Promise<void>** — integrate with server actions / fetch calls without manual loading state management.
+- **Pairs with NotificationCenter** — NotificationCenter shows notifications in real time (driven by these preferences); NotificationPreferences lets users tune the rules.
+- **Data ownership is consumer-side** — you pass `preferences` + `projects`; NotificationPreferences renders. No built-in persistence or sync.
+
 ## Gotchas
 - Manages per-project notification preferences (channel, tier, mute)
 - All callback props support async (Promise<void>) for server-side operations

package/docs/components/shell/sidebar.md

@@ -48,6 +48,17 @@ SidebarPromo: { text: string, icon?: ReactNode, action?: { label: string, href?:
 />
 ```
 
+## Composability
+- **Opinionated app sidebar** — data-driven via `navGroups`, with user profile header, navigation groups (with optional labels + group actions), and a configurable footer (links + version + optional promo banner).
+- **Required setup (three providers):**
+  - `SidebarProvider` (from ui/sidebar) — owns expanded/collapsed state + cookie persistence
+  - `LinkProvider` — framework router integration for nav item links
+  - `CommandRegistryProvider` (if pairing with AppCommandPalette) — registers the same navGroups so keyboard search finds them
+- **renderItem escape hatch:** Custom per-item rendering (e.g. custom icons per item type, status decorations, hover previews). Return `null` to fall back to default.
+- **Nested navigation:** NavItem's `children: NavSubItem[]` renders a collapsible subsection. Auto-opens if a child matches the current path.
+- **Footer as slot:** `footer` can include links, version info, a ReactNode slot (e.g. theme toggle), and a dismissable promo banner — structure it once, compose.
+- **Pairs with TopBar + BottomNavbar:** Desktop layout = AppSidebar + TopBar. Mobile layout = hide AppSidebar, show BottomNavbar.
+
 ## Gotchas
 - Must be wrapped in SidebarProvider (from ui/sidebar)
 - Requires LinkProvider for framework-specific link components

package/docs/components/shell/top-bar.md

@@ -111,6 +111,17 @@ UserMenuItem fields:
 </TopBar>
 ```
 
+## Composability
+- **Composition-based, NOT data-driven.** Use dot-notation subcomponents (`TopBar.Left`, `TopBar.Center`, `TopBar.Right`, `TopBar.Section`, `TopBar.IconButton`, `TopBar.Title`, `TopBar.UserMenu`) to assemble. No "props config" — explicit JSX.
+- **Two-zone vs three-zone layout** — adding `TopBar.Center` flips the root from `flex` to CSS grid (`1fr auto 1fr`) for true centering. Standard apps are two-zone (Left + Right); dashboards with prominent search are three-zone.
+- **Required providers:**
+  - `SidebarProvider` — for SidebarTrigger inside `TopBar.Left` to work
+  - `LinkProvider` — for TopBar.UserMenu's menu items that use `href`
+- **NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.
+- **UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.
+- **Responsive hiding:** Actions that shouldn't appear on mobile use `className="hidden md:flex"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.
+- **Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region.
+
 ## Gotchas
 - Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.
 - `TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className="hidden md:flex"`) for mobile.

package/docs/components/ui/accordion.md

@@ -30,9 +30,19 @@
 </Accordion>
 ```
 
+## Composability
+- Built on Radix Accordion — accepts `value`/`defaultValue`/`onValueChange` matching the `type` discriminated union.
+- **`type="single"`** — value is a string (which item is open). Only one item open at a time. Pair with `collapsible` to allow closing the current item by re-clicking it.
+- **`type="multiple"`** — value is a string[] (which items are open). Multiple can be open at once.
+- **AccordionTrigger chevron:** Inline SVG that auto-rotates via the `data-state` attribute Radix sets (`open` / `closed`). The `chevronPosition` prop controls render order inside the trigger (left / right) — rotation still works from either position.
+- **AccordionContent:** Uses Radix CSS custom properties (`--radix-accordion-content-height`) for open/close height animation. Framer Motion handles the fade. Don't wrap AccordionContent children in additional motion components — doubles the animation.
+- **Inline, not portalled** — parent `overflow: hidden` WILL clip an open accordion. Keep accordions out of tight overflow contexts or use `overflow-visible` on the container.
+
 ## Gotchas
 - type is REQUIRED — omitting it causes runtime error
 - collapsible only works with type="single"
+- Each AccordionItem needs a unique `value` — duplicates silently break toggling
+- Don't put focusable elements inside AccordionTrigger — the trigger IS the focusable button, nested focusables break screen reader navigation
 
 ## Changes
 ### v0.29.0

package/docs/components/ui/alert-dialog.md

@@ -42,8 +42,17 @@
 </AlertDialog>
 ```
 
+## Composability
+- Built on Radix AlertDialog — like Dialog but **non-dismissible** by clicking outside or pressing Escape. The user must choose Cancel or Action.
+- Same portal + trigger + asChild pattern as Dialog.
+- `AlertDialogAction` and `AlertDialogCancel` are semantically distinct from generic buttons: they auto-close the dialog on click. Use them even if you wrap them around a styled Button via `asChild` so the close behavior stays wired.
+- **Focus management:** Initial focus lands on `AlertDialogCancel` (the safe default) — destructive confirmation is always one tab away.
+- Use AlertDialog for destructive / irreversible actions; use Dialog for everything else.
+
 ## Gotchas
-- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button
+- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button with `asChild`
+- Do NOT add a close-on-outside-click handler — the non-dismissible behavior is the whole point
+- AlertDialogCancel receives initial focus; don't flip the convention
 
 ## Changes
 ### v0.19.1

package/docs/components/ui/alert.md

@@ -5,14 +5,15 @@
 - Category: ui
 
 ## Props
-    variant: "subtle" | "filled" | "outline"
+    variant: "subtle" | "solid" | "outline" | "filled" (deprecated alias for "solid")
     color: "info" | "success" | "warning" | "error" | "neutral"
+    size: "sm" | "md" | "lg"
     title: string (optional)
     onDismiss: () => void (optional, shows X button when provided)
     children: ReactNode (body text)
 
 ## Defaults
-    variant="subtle", color="info"
+    variant="subtle", color="info", size="md"
 
 ## Example
 ```jsx
@@ -21,6 +22,13 @@
 </Alert>
 ```
 
+## Composability
+- **Flat, not compound** — unlike Dialog/Card, there's no `<AlertTitle>` / `<AlertDescription>`. Use the `title` prop for the heading and `children` for the body text. This simplifies the API and prevents composition traps (missing title, out-of-order header parts).
+- **Auto-icon by color:** Icon is selected automatically from color (info→circle, success→check, warning→triangle, error→alert). Pass a custom `icon` prop to override.
+- **Role=alert:** Announces assertively to screen readers. Don't stack multiple Alerts in a row — the last one wins.
+- **Dismissal pattern:** Pass `onDismiss` for user-dismissable alerts; the library tracks the exit animation before calling back. For persistent alerts (system state), omit `onDismiss`.
+- **Not for transient messages** — use Toast for transient/time-limited notifications and Banner for page-level announcements. Alert is inline, in-flow, block-level.
+
 ## Gotchas
 - NOT a compound component — use title prop, NOT <AlertTitle>
 - DO NOT use variant="destructive" — use color="error"

package/docs/components/ui/aspect-ratio.md

@@ -17,8 +17,15 @@
 </AspectRatio>
 ```
 
+## Composability
+- Radix AspectRatio primitive — pure layout wrapper, no context, no cascade.
+- **Child fill pattern:** Its child is absolutely positioned to fill. Pair with `object-cover` / `object-contain` on `<img>`/`<video>` and `w-full h-full` for anything else.
+- Useful as a responsive-image container, a chart area (pair with Chart components), or a placeholder frame for media skeletons.
+- Works inside Card, any layout component, or flex/grid containers — nothing to configure.
+
 ## Gotchas
 - ratio is a number, not a string — use `16/9` not `"16/9"`
+- The child must be size-fluid (`w-full h-full` or absolutely positioned) — elements with intrinsic size escape the aspect-ratio box
 
 ## Changes
 ### v0.1.0

package/docs/components/ui/autocomplete.md

@@ -27,6 +27,13 @@
 />
 ```
 
+## Composability
+- **Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether "off-list" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).
+- **Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.
+- **FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.
+- **Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.
+- **Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering.
+
 ## Gotchas
 - Allows free-text input (no forced selection) — use Combobox for forced selection
 - value is an object { value, label }, NOT just a string

package/docs/components/ui/avatar.md

@@ -31,10 +31,20 @@
 </Avatar>
 ```
 
+## Composability
+- **Two internal contexts cascade to AvatarFallback:**
+  - `AvatarSizeContext` — carries the Avatar's `size` so AvatarFallback's font size scales without re-specifying (xs → `text-[9px]`, sm → `text-ds-xs`, md → `text-ds-sm`, lg → `text-ds-md`, xl → `text-ds-lg`)
+  - `AvatarShapeContext` — carries `shape` so AvatarFallback inherits the same border-radius (critical for `shape="square"` / `shape="rounded"` — without context the fallback would always be `rounded-ds-full` regardless of parent)
+- **Status + Ring + Badge are independent** — you can stack all three on one Avatar. They render in separate layers so they don't conflict visually.
+- **Use with AvatarGroup:** AvatarGroup applies its own `size` to children. If your Avatar has an explicit `size`, it overrides AvatarGroup's default — keep it consistent across the group.
+- **AvatarFallback colorSeed:** Deterministic background color from the seed string — identical user IDs produce identical backgrounds across renders. Useful for user-identifying avatars without photos.
+- **Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-raised`. On other backgrounds, add a ring-offset className to compensate.
+
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)
 - Dot size scales automatically with avatar size
 - AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
+- AvatarFallback shape inherits from Avatar (via AvatarShapeContext) — setting `rounded-*` on AvatarFallback directly conflicts with the context
 - Ring offset color matches the surface context — ensure it sits on the expected background
 - Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
 - Online status dot pulses with a CSS animation

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

@@ -27,6 +27,13 @@
 {/* Renders: React, TypeScript, Tailwind, +2 */}
 ```
 
+## Composability
+- **Wrapper for Badge children** — doesn't style children, just lays them out and optionally collapses overflow into a "+N" indicator.
+- **Server-safe** — can render in RSC trees (children still need to be server-safe themselves).
+- **Overflow indicator is a Badge** — picks `variant="outline" color="neutral"` and the `size` prop on BadgeGroup. Child badges keep their own variant/color/size.
+- **Click-to-reveal pattern:** Pair `onOverflowClick` with a Popover / Sheet / Dialog that shows the full list. Without the handler, the overflow badge is inert (decorative count).
+- Doesn't accept arbitrary children — only Badges. Non-Badge children render but may look off (no gap rhythm matching).
+
 ## Gotchas
 - Overflow badge is always `variant="outline" color="neutral"`
 - `size` only applies to the overflow badge — child badges keep their own size

package/docs/components/ui/badge-indicator.md

@@ -29,6 +29,13 @@
 </Badge.Indicator>
 ```
 
+## Composability
+- **Overlay wrapper** — takes any child and overlays a positioned count/dot at the specified corner. The child must be inline-friendly (anything that renders in a span-wrapped position: relative context).
+- **Common pairings:** IconButton (notification bell with count), Avatar (online presence dot), Button (cart with item count), tabs (unread indicator).
+- **Invisible for layout stability:** Use `invisible={true}` to keep the child's position consistent when the badge should disappear — avoids layout shift as counts appear/disappear.
+- **showZero vs hide-on-zero:** By default `count={0}` hides the indicator. Set `showZero={true}` for use cases where "zero" is meaningful (scores, pending items that should display 0 explicitly).
+- **Dot vs count:** `dot={true}` is a presence-only pulse indicator (online, new activity); count is a numeric badge. They're mutually exclusive — setting both uses dot.
+
 ## Gotchas
 - Wraps children in `position: relative` span — the indicator is absolutely positioned
 - Animation uses spring physics, respects `prefers-reduced-motion`

package/docs/components/ui/badge.md

@@ -36,6 +36,18 @@
 <Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
 ```
 
+## Composability
+- **Badge.Group** (BadgeGroup) wraps a set of badges with overflow collapse (`max` + "+N" indicator) and gap control. Use it for filter chips, tag lists, user cluster avatars-equivalent.
+- **Badge.Indicator** (BadgeIndicator) attaches a count / dot overlay to ANY child (icons, avatars, buttons). It's positioning-only — doesn't style the child.
+- **Interactive modes:**
+  - `onClick` alone → renders as `<button>` (standard interactive badge)
+  - `onDismiss` alone → renders as `<span>` with an inner X button
+  - Both → renders as `<div role="button">` (avoids invalid nested buttons) — the X button inside handles its own click isolation
+- **asChild:** Use with router Links for nav-style badges (`<Badge asChild><Link href="/tags/react">React</Link></Badge>`).
+- **Custom colors via CSS variables:** Set `color="custom"` + inline style `style={{ '--badge-color': '#...' }}`. For solid variant, also set `--badge-fg-color` for the foreground.
+- **Icon slots auto-size via IconProvider** — same cascade as Button. Don't set explicit size on nested `<Icon>`.
+- **Chip (deprecated)** was merged into Badge — use Badge with `onClick` and `selected` for the old Chip use case.
+
 ## Gotchas
 - DO NOT use variant="destructive" — use variant="solid" color="error"
 - Badge is now interactive when `onClick` is provided (renders as `<button>`)

package/docs/components/ui/banner.md

@@ -21,6 +21,13 @@
 </Banner>
 ```
 
+## Composability
+- **Banner vs Alert vs Toast:** Banner is full-width, top-of-page / top-of-region announcements (maintenance, quota, trial-expiring). Alert is inline in-flow. Toast is transient floating notifications. Pick by where the message lives in the visual hierarchy.
+- **actions slot:** Pass one or more `<Button>` elements — the container flex-wraps on narrow viewports so actions drop below the message rather than squeezing horizontally.
+- **Role=alert** announces assertively. Same constraint as Alert — don't stack multiple Banners.
+- **Dismissal timing:** `onDismiss` fires AFTER the exit animation completes, not on click. Use it to remove the banner from state only after it's visually gone.
+- Works inside Shell layouts (TopBar / Sidebar / main content) — usually sits above main content, below the TopBar.
+
 ## Gotchas
 - Banner is full-width (spans container). Alert is inline.
 - Renders role="alert" automatically

package/docs/components/ui/breadcrumb.md

@@ -26,8 +26,16 @@
 </Breadcrumb>
 ```
 
+## Composability
+- **Compound structure only** — no context cascade, each part is standalone. The semantic shape (`<nav>` → `<ol>` → `<li>`) is what matters for a11y, not any internal state.
+- **BreadcrumbLink vs BreadcrumbPage:** Use BreadcrumbLink for everything except the current page; BreadcrumbPage for the current page (not clickable, renders without href, announced as "current page" via aria-current).
+- **Router integration:** Use `<BreadcrumbLink asChild><NextLink href="/x">...</NextLink></BreadcrumbLink>` (Radix Slot pattern).
+- **Truncation:** For long paths, use BreadcrumbEllipsis between the first and last items instead of showing all. Pair with a DropdownMenu (open the ellipsis to show hidden intermediate items) if you need to expose them.
+- **PageHeader (composed) auto-builds Breadcrumb** from its `breadcrumbs` prop — use that higher-level component for page-top breadcrumbs and save this component for inline or custom positioning.
+
 ## Gotchas
 - Use BreadcrumbPage for the current (non-clickable) page, BreadcrumbLink for navigable items
+- Don't wrap BreadcrumbPage in a link — it's the current location by definition
 
 ## Changes
 ### v0.18.0

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

@@ -5,24 +5,44 @@
 - Category: ui
 
 ## Props
-    variant: ButtonProps['variant'] (propagated to children)
+    variant: ButtonProps['variant'] (propagated to children via context)
     color: ButtonProps['color'] (propagated to children)
     size: ButtonProps['size'] (propagated to children)
-    orientation: "horizontal" | "vertical" (default: "horizontal")
+    weight: ButtonProps['weight'] (propagated to children)
+    shape: ButtonProps['shape'] (propagated to children)
+    disabled: boolean (propagates to all children)
+    orientation: "horizontal" | "vertical"
+    attached: boolean (true = buttons visually merge with shared borders; false = spaced apart via gap)
+    fullWidth: boolean (group stretches to parent width; children stretch equally)
 
 ## Defaults
-    orientation="horizontal"
+    orientation="horizontal", attached=true
 
 ## Example
 ```jsx
 <ButtonGroup variant="outline" size="sm">
   <Button>Bold</Button>
   <Button>Italic</Button>
+  <Button>Underline</Button>
+</ButtonGroup>
+
+{/* Spaced, not attached */}
+<ButtonGroup attached={false} variant="soft">
+  <Button>Save</Button>
+  <Button>Cancel</Button>
 </ButtonGroup>
 ```
 
+## Composability
+- Every Button child reads variant/color/size/weight/shape/disabled from ButtonGroup context. Explicit props on individual children override context.
+- **Position-aware border radius:** Child Buttons read their position in the group (first / middle / last) and apply appropriate corner radii inline. Works for both horizontal and vertical orientations.
+- **Focus z-index isolation:** The focused button rises above its siblings so the focus ring isn't clipped by adjacent borders.
+- **Tonal dividers:** For solid/soft/ghost variants without visible borders, ButtonGroup injects subtle divider elements between children.
+- **Works with SplitButton:** `<SplitButton>` inside a `<ButtonGroup>` inherits the same context and position rules.
+
 ## Gotchas
-- Children can override variant/size individually
+- Children can override variant/size individually — context is a default, not a lock
+- `attached={false}` disables the position-aware border radius (children use their default corners)
 
 ## Changes
 ### v0.33.0

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

@@ -10,6 +10,11 @@ Internal component that renders the processing animation overlay for Button. Con
 
 See `Button` docs for the public API.
 
+## Composability
+- **Internal only — do NOT import or use directly.** The Button component owns the lifecycle of this overlay.
+- Drives Button's `processing` prop rendering. If you're building a custom button and want similar marching-ants feedback, copy the SVG/animation pattern — don't reach into this component.
+- Listed here for reference so consumers grep'ing for "processing" find the behavior origin.
+
 ## Changes
 ### v0.29.0
 - **Added** Initial release — marching ants processing overlay (SVG dashed rect with animated stroke-dashoffset). Speed tiers: ambient (3s), working (2s), urgent (1s). Color maps to step-11 tokens for visibility on all variants.

package/docs/components/ui/button.md

@@ -34,6 +34,15 @@
 <Button variant="soft" color="warning" size="compact-sm" shape="pill">Overdue</Button>
 ```
 
+## Composability
+- **ButtonGroup context consumption:** When nested inside `<ButtonGroup>`, Button auto-inherits variant/color/size/weight/shape/disabled. Explicit props on the individual Button override. The context also drives position-aware border-radius (first/middle/last within an attached group).
+- **IconProvider cascade:** Icons in `startIcon`/`endIcon` auto-size via IconProvider per the button size (xs→sm, sm→sm, md→md, lg→md, icon-xs→xs, icon-lg→lg). Don't pass explicit `size` to `<Icon>` inside Button.
+- **asChild for router links:** `<Button asChild><Link href="/foo">...</Link></Button>` transfers Button's styling to the Link while preserving navigation semantics. Required for Next.js `<Link>` / react-router `<Link>`.
+- **onClickAsync state machine:** Overrides onClick. Auto-cycles `idle → loading (aria-busy, spinner) → success (checkmark) → idle` on resolve; `loading → error (X mark) → idle` on reject. Duration controlled by `asyncFeedbackDuration` (1500ms default). Auto-activates `processing='working'` during loading — marching-ants border keeps users visually aware.
+- **Processing vs loading:** `loading` is a short async state (shows spinner, blocks clicks). `processing` is a longer-running state (marching ants border, may or may not block clicks based on `processingDisabled`). Use onClickAsync for simple request cases; use processing explicitly for long-running background operations.
+- **DevalokGrain children:** Grain elements are auto-extracted and rendered as direct button children for absolute positioning — lets you layer grain texture on solid-variant buttons without breaking layout.
+- **Prefer `variant="soft"` over `variant="outline"` for secondary actions** (see Gotchas for details). This is a design-system-wide convention.
+
 ## Gotchas
 - **Prefer `variant="soft"` over `variant="outline"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-raised bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.
 - DO NOT use variant="destructive" — use variant="solid" color="error"

package/docs/components/ui/card.md

@@ -6,18 +6,22 @@
 
 ## Props
     variant: "default" | "elevated" | "outline" | "flat"
+    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" (border accent color)
+    size: "sm" | "md" | "lg" (padding — propagated to CardHeader/CardContent/CardFooter via context)
     interactive: boolean (enables hover shadow lift + pointer cursor)
+    accent: "left" | "top" | "right" | "bottom" (render a colored accent bar on the specified edge)
+    accentColor: "default" | "accent" | "error" | "success" | "warning" | "info" (color of the accent bar; default maps to accent-9)
 
 ## Compound Components
     Card (root)
-      CardHeader
+      CardHeader      ← inherits size from Card context
         CardTitle
         CardDescription
-      CardContent
-      CardFooter
+      CardContent     ← inherits size from Card context
+      CardFooter      ← inherits size from Card context
 
 ## Defaults
-    variant="default"
+    variant="default", color="default", size="md"
 
 ## Example
 ```jsx
@@ -30,8 +34,16 @@
 </Card>
 ```
 
+## Composability
+- **Size cascades through context** — Card's `size` prop sets padding on CardHeader, CardContent, and CardFooter via `CardSizeContext`. Don't set padding classes on sub-components directly; override via `className` if needed.
+- **Not a compound state machine** — Card, CardHeader, CardTitle, etc. are purely structural. No open/close state.
+- **Accent bar is independent:** The `accent` / `accentColor` props render a decorative colored edge bar (absolutely positioned, `aria-hidden`). Works alongside `color` (which tints the border) — the two can stack for layered emphasis.
+- **Interactive cards:** Set `interactive={true}` + `onClick` for clickable cards (entire surface becomes the button). Add `aria-label` on the Card root when there's no visible heading. For complex multi-action cards, prefer standard Card with explicit buttons inside.
+- **ContentCard (composed)** is a higher-level wrapper with built-in header/footer slots and title/actions — use it for list-row-style cards; use Card directly for custom layouts.
+
 ## Gotchas
 - Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
+- Don't override CardHeader/CardContent/CardFooter padding via className if you want the size cascade to work — set size on Card instead
 
 ## Changes
 ### v0.31.0

package/docs/components/ui/charts.md

@@ -28,9 +28,18 @@ import { BarChart } from '@devalok/shilp-sutra/ui/charts'
 <BarChart data={salesData} />
 ```
 
+## Composability
+- **ChartContainer wraps all chart primitives** — provides responsive sizing (fills parent width, configurable aspect ratio) and a consistent background/padding. Always render charts inside a ChartContainer unless you're building a custom container.
+- **Legend is a sibling, not a child** — render `<Legend items={...} />` next to your chart (above/below), not nested. Use `onHover` / `onClick` handlers in Legend + chart to sync hover highlights.
+- **Data shape is chart-specific** — BarChart wants `[{ label, value }]`, LineChart wants `[{ x, y, series }]`, etc. Each chart's props doc spells out the shape; don't assume cross-chart compatibility.
+- **Sparkline is the only chart safe to use inline** — it's a minimal 1-line SVG, no axes, no legend. Use it inside StatCard, tables, tight cells. For anything larger, reach for the full chart types.
+- **Entrance animations** — all charts use Framer Motion spring-based entry. Animations respect `prefers-reduced-motion`.
+- **Accessibility:** Charts render role="img" with aria-label from the chart title. For dense data, provide a hidden accessible table fallback manually (WCAG requirement for complex charts).
+
 ## Gotchas
 - Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/charts`, NOT the `ui` barrel
 - Requires D3 as an optional peer dependency
+- Chart components do NOT auto-generate accessible data tables — add one manually for WCAG compliance on complex charts
 
 ## Changes
 ### v0.18.0