banhaten 0.3.0 → 0.5.0

package/docs/design-system/components/sheet.md

@@ -1,69 +1,69 @@
-# Sheet
-
-Sheet is a Radix Dialog-based side or edge panel for contextual workflows that need more room than a popover but less interruption than a full modal. It supports logical `start` and `end` sides for RTL, plus top and bottom placements.
-
-## API
-
-```tsx
-<Sheet>
-  <SheetTrigger asChild>
-    <Button>Open settings</Button>
-  </SheetTrigger>
-  <SheetContent side="end">
-    <SheetHeader>
-      <SheetTitle>Workspace settings</SheetTitle>
-      <SheetDescription>Update billing and access controls.</SheetDescription>
-    </SheetHeader>
-    <SheetBody>...</SheetBody>
-    <SheetFooter>...</SheetFooter>
-  </SheetContent>
-</Sheet>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `Sheet`, `SheetTrigger`, `SheetClose`, `SheetPortal` | Radix Dialog shell |
-| `SheetOverlay`, `SheetContent` | overlay and trapped panel |
-| `SheetHeader`, `SheetTitle`, `SheetDescription` | accessible heading area |
-| `SheetBody`, `SheetFooter` | scrollable content and actions |
-
-| Prop | Values |
-| --- | --- |
-| `side` | `start`, `end`, `top`, `bottom` |
-| `size` | `sm`, `default`, `lg` |
-| `showCloseButton` | `boolean` |
-
-## Token Contract
-
-Sheet uses Banhaten overlay, raised surface, border, radius, shadow, spacing, typography, focus, and content tokens.
-
-## RTL
-
-Use `side="start"` and `side="end"` instead of physical left/right placement. CSS logical edges place the panel on the right edge in LTR for `end`, and on the left edge in RTL.
-
-## Accessibility
-
-Radix Dialog provides focus trap, Escape dismissal, outside dismissal, title/description wiring, and modal dialog semantics. Use Alert Dialog for destructive confirmations.
-
-## Install
-
-```bash
-npx banhaten add sheet
-```
-
-## Examples
-
-Primary registry example: `examples/sheet-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs sheet` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `placement`: Use side="start" and side="end" for logical placement; CSS start/end edges mirror under RTL.
-- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
-- `semantics`: Radix Dialog handles modal semantics, focus trapping, and dismissal.
-
+# Sheet
+
+Sheet is a Radix Dialog-based side or edge panel for contextual workflows that need more room than a popover but less interruption than a full modal. It supports logical `start` and `end` sides for RTL, plus top and bottom placements.
+
+## API
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>Open settings</Button>
+  </SheetTrigger>
+  <SheetContent side="end">
+    <SheetHeader>
+      <SheetTitle>Workspace settings</SheetTitle>
+      <SheetDescription>Update billing and access controls.</SheetDescription>
+    </SheetHeader>
+    <SheetBody>...</SheetBody>
+    <SheetFooter>...</SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Sheet`, `SheetTrigger`, `SheetClose`, `SheetPortal` | Radix Dialog shell |
+| `SheetOverlay`, `SheetContent` | overlay and trapped panel |
+| `SheetHeader`, `SheetTitle`, `SheetDescription` | accessible heading area |
+| `SheetBody`, `SheetFooter` | scrollable content and actions |
+
+| Prop | Values |
+| --- | --- |
+| `side` | `start`, `end`, `top`, `bottom` |
+| `size` | `sm`, `default`, `lg` |
+| `showCloseButton` | `boolean` |
+
+## Token Contract
+
+Sheet uses Banhaten overlay, raised surface, border, radius, shadow, spacing, typography, focus, and content tokens.
+
+## RTL
+
+Use `side="start"` and `side="end"` instead of physical left/right placement. CSS logical edges place the panel on the right edge in LTR for `end`, and on the left edge in RTL.
+
+## Accessibility
+
+Radix Dialog provides focus trap, Escape dismissal, outside dismissal, title/description wiring, and modal dialog semantics. Use Alert Dialog for destructive confirmations.
+
+## Install
+
+```bash
+npx banhaten add sheet
+```
+
+## Examples
+
+Primary registry example: `examples/sheet-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs sheet` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: Use side="start" and side="end" for logical placement; CSS start/end edges mirror under RTL.
+- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
+- `semantics`: Radix Dialog handles modal semantics, focus trapping, and dismissal.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -78,5 +78,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `focus trap`, `outside dismissal`, `Escape dismissal`, `logical sides`, `scrollable body`, `footer actions` |
 | `sides` | `start`, `end`, `top`, `bottom` |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-bg-backdrop`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-button-focus`, `--shadow-component-default` |
+| `tokens` | `--bh-bg-backdrop`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--elevation-button-focus`, `--elevation-component-default` |
 <!-- registry-contract:end -->

package/docs/design-system/components/shimmer-text.md

@@ -0,0 +1,67 @@
+# Shimmer Text
+
+`ShimmerText` is text with a soft brightness valley sweeping through it, for labels of work in progress such as a sync that is running or a file being read. The AI conversation components share it: the Thinking State label, the Thinking Reasoning header, the active Task List row, and the Agent Input while it enhances a prompt all use it, so they move the same way.
+
+Use it to mark a moving part inside ordinary copy. It is presentational; announce progress through your own semantics or through Thinking State.
+
+## API
+
+```tsx
+import { ShimmerText } from "@/components/ui/shimmer-text"
+
+<p>
+  Searching the workspace for <ShimmerText tone="default">billing/invoices.ts</ShimmerText>
+</p>
+
+<ShimmerText>Reading 12 files</ShimmerText>
+<ShimmerText animated={false}>Read 12 files</ShimmerText>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `animated` | `boolean` | `true` | Runs the brightness sweep. Set false to keep the same colors without motion. |
+| `tone` | `"subtle" \| "default"` | `"subtle"` | `subtle` reads as secondary copy; `default` matches primary text. |
+
+Any other `span` prop passes through. The `data-slot="shimmer-text"` attribute is what the styles key on, so it cannot be overridden; wrap the primitive when you need your own hook.
+
+## Install
+
+```bash
+npx banhaten add shimmer-text
+```
+
+## Examples
+
+Primary registry example: `examples/shimmer-text-demo.tsx`.
+
+## Token Contract
+
+The shimmer is built from existing content tokens: the base color is `--bh-content-subtle` (or `--bh-content-default` for the `default` tone) and the passing valley is `--bh-content-disabled` (or `--bh-content-subtle`). The sweep runs on `--bh-shimmer-text-duration` with the `--bh-easing-standard` foundation easing. Text size and weight are inherited.
+
+Covered source files: `components/shimmer-text.tsx` and `components/shimmer-text.css`.
+
+## RTL Rules
+
+- The text inherits document direction.
+- The shine sweeps from the reading start to the reading end, so RTL text uses mirrored keyframes automatically.
+
+## Accessibility
+
+The glyphs stay real text, so screen readers read them normally. The shimmer is purely decorative: under `prefers-reduced-motion` it renders as static text in the base color with no gradient, and the resting color keeps the base text contrast.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/shimmer-text.tsx: ShimmerText` |
+| `parts` | `ShimmerText` |
+| `registryDependencies` | None |
+| `props.animated` | `boolean; default "true"; Runs the brightness sweep; set false to keep the same colors without motion.` |
+| `props.tone` | `"subtle" \| "default"; default "subtle"; Secondary or primary text color pair for the sweep.` |
+| `tokens` | `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-easing-standard`, `--bh-shimmer-text-duration` |
+| `tones` | `subtle`, `default` |
+<!-- registry-contract:end -->

package/docs/design-system/components/sidebar.md

@@ -1,74 +1,110 @@
-# Sidebar
-
-Sidebar is a composable app navigation surface with collapse state, grouped menu items, logical start/end placement, and generated `--bh-sidebar-*` tokens.
-
-`Sidebar` can also render as a standalone static navigation surface. Use `SidebarProvider` whenever collapse controls or provider-aware menu parts are present.
-
-## API
-
-```tsx
-<SidebarProvider>
-  <Sidebar>
-    <SidebarHeader>
-      Workspace
-      <SidebarToggle />
-    </SidebarHeader>
-    <SidebarBody>
-      <SidebarGroup>
-        <SidebarGroupLabel>Main</SidebarGroupLabel>
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <SidebarMenuButton active>Overview</SidebarMenuButton>
-          </SidebarMenuItem>
-        </SidebarMenu>
-      </SidebarGroup>
-    </SidebarBody>
-  </Sidebar>
-</SidebarProvider>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `SidebarProvider` | controlled or uncontrolled collapsed state |
-| `Sidebar` | navigation surface |
-| `SidebarHeader`, `SidebarBody`, `SidebarFooter` | layout regions |
-| `SidebarGroup`, `SidebarGroupLabel` | grouped navigation |
-| `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton` | menu structure |
-| `SidebarToggle`, `SidebarRail` | collapse controls |
-| `SidebarTrigger` | shadcn-compatible alias for `SidebarToggle` |
-| `SidebarInset` | main content wrapper for app-shell layouts |
-
-## Token Contract
-
-Sidebar uses generated `--bh-sidebar-width`, `--bh-sidebar-width-collapsed`, `--bh-sidebar-item-height`, `--bh-sidebar-padding`, `--bh-sidebar-bg`, `--bh-sidebar-border`, and `--shadow-sidebar` tokens.
-
-## RTL
-
-Use `dir="rtl"` on `SidebarProvider` and `side="start"` or `side="end"` for logical placement.
-
-## Accessibility
-
-Use clear labels for collapsed icon-only menu buttons. `SidebarToggle` announces the pressed collapse state.
-Sidebar composition parts must be rendered inside `SidebarProvider`.
-
-## Install
-
-```bash
-npx banhaten add sidebar
-```
-
-## Examples
-
-Primary registry example: `examples/sidebar-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs sidebar` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `placement`: Use side="start" or side="end" with dir on SidebarProvider for logical placement.
-- `spacing`: Menu item icon and label spacing uses flex gaps and logical text alignment.
-
+# Sidebar
+
+Sidebar is the complete Figma-aligned application navigation system. It provides a 900px minimum height, 280px expanded shell and 48px icon rail, staged expand/collapse motion, brand and workspace headers, grouped and nested menus, tree navigation, badges and actions, user footers with hover identity previews, tooltips, controlled state, and logical RTL placement.
+
+All sidebar parts render inside `SidebarProvider`. The provider owns controlled or uncontrolled collapse state and supplies the tooltip context used by icon-only menu rows.
+
+## API
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>
+      <SidebarHeaderWorkspaceSwitch label="Acme Inc" />
+    </SidebarHeader>
+    <SidebarBody>
+      <SidebarGroup>
+        <SidebarGroupLabel>Main</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton active icon={<LayoutGridIcon />}>
+              Overview
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+          <SidebarMenuItem>
+            <SidebarMenuButton icon={<CreditCardIcon />}>
+              Transactions
+            </SidebarMenuButton>
+            <SidebarMenuSub>
+              <SidebarMenuSubButton active showLine>
+                Payments
+              </SidebarMenuSubButton>
+            </SidebarMenuSub>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarBody>
+    <SidebarFooter>
+      <SidebarFooterUser name="Olivia Rhye" supportText="olivia@acme.com" />
+    </SidebarFooter>
+  </Sidebar>
+</SidebarProvider>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `SidebarProvider` | controlled or uncontrolled collapsed state |
+| `Sidebar` | 280px navigation surface and 48px collapsed rail |
+| `SidebarHeader`, `SidebarBody`, `SidebarFooter` | layout regions |
+| `SidebarHeaderBrand`, `SidebarHeaderWorkspaceSwitch` | brand and workspace header compositions |
+| `SidebarHeaderAction` | compact search or custom header action |
+| `SidebarFooterUser` | supporting-text or bordered user switcher with a collapsed hover/focus identity preview |
+| `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupAction` | grouped navigation, disclosure, and actions |
+| `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton` | default and avatar menu structure with optional slots |
+| `SidebarMenuBadge` | neutral count badge for a menu row |
+| `SidebarMenuSub`, `SidebarMenuSubButton` | plain or line-guided Level 2 navigation |
+| `SidebarTreeGroup`, `SidebarMenuTreeItem` | four-level file or project tree navigation |
+| `SidebarToggle`, `SidebarRail` | collapse controls |
+| `SidebarTrigger` | shadcn-compatible alias for `SidebarToggle` |
+| `SidebarInset` | main content wrapper for app-shell layouts |
+
+`SidebarMenuButton` accepts `variant="default" | "avatar" | "level2" | "level2-line"`. Its optional `icon`, `supportText`, `badge`, and `trailingIcon` props keep every row aligned to the Figma slots. Prefer `SidebarMenuSubButton` for nested rows because its `showLine` prop selects the nested treatment directly.
+
+Use `SidebarHeaderBrand` for product navigation. Use `SidebarHeaderWorkspaceSwitch` with `variant="actions"` for the compact search/collapse header or `variant="card"` for the bordered workspace card.
+
+Brand and workspace headers keep a visible `SidebarTrigger` beneath their identity control while the rail is collapsed, so the same header can always expand again. Pass `collapseAction={false}` only when another persistent expand control is present.
+
+When the rail is collapsed, `SidebarFooterUser` reveals the user's name and supporting text beside the avatar on hover or keyboard focus. Set `showIdentityPreview={false}` to disable that behavior. To make the row selectable, wrap it with `MenuRoot` and `MenuTrigger asChild`, then render account actions in a portalled `MenuContent`; the live playground example demonstrates this composition.
+
+## Token Contract
+
+Sidebar uses generated `--bh-sidebar-*` tokens for its 900px minimum height, expanded and collapsed widths, row heights, header actions, compact controls, workspace cards, tree indentation, user-preview placement, motion duration and easing, padding, backgrounds, borders, and menu states. Expanded and collapsed navigation share the same 18px glyph in a centered 20px slot. Do not replace these dimensions with local literals in product compositions.
+
+## Motion
+
+The shell, header, menu rows, nested lists, and footer share one tokenized choreography. The width boundary uses `--bh-sidebar-motion-duration` with `--bh-sidebar-motion-easing`; labels and secondary actions use the faster `--bh-sidebar-motion-duration-content`. Content exits as collapse begins and returns after `--bh-sidebar-motion-delay-content`, while icons stay on the logical-start track instead of jumping to the center of the still-expanded shell.
+
+Nested menus and group labels contract through layout rather than unmounting on the first frame. The rail remains clipped until its width transition finishes, then permits the footer identity preview to extend outside the shell. The global reduced-motion rule and component-level `motion-reduce` variants remove the choreography when the user requests less motion.
+
+## RTL
+
+Use `dir="rtl"` on `SidebarProvider` and `side="start"` or `side="end"` for logical placement. Inline borders, padding, submenu guides, tree indentation, collapse icons, and disclosure chevrons mirror automatically.
+
+## Accessibility
+
+Provide a text child or explicit `aria-label` for every menu button. Collapsed rows reuse that label in a tooltip. Active menu and tree rows expose `aria-current="page"`; expandable tree rows expose `aria-expanded`; `SidebarToggle` announces both its action and pressed collapse state.
+
+Level 2 rows, group labels, and tree groups remain mounted long enough to animate, but become `aria-hidden` and inert while collapsed so keyboard and assistive-technology users do not encounter invisible controls. Use native links through `asChild` when a row navigates, and keep button rendering for in-place actions.
+
+## Install
+
+```bash
+npx banhaten add sidebar
+```
+
+## Examples
+
+Primary registry example: `examples/sidebar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs sidebar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: Use side="start" or side="end" with dir on SidebarProvider for logical placement and border selection.
+- `spacing`: Headers, menu rows, nested guides, tree indentation, group actions, and footer content use logical inline spacing.
+- `icons`: Directional collapse, disclosure, and tree chevrons mirror in RTL; semantic icons retain their orientation.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -77,9 +113,24 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/sidebar.tsx: Sidebar, SidebarBody, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarRail, SidebarToggle, SidebarTrigger` |
-| `parts` | `SidebarProvider`, `Sidebar`, `SidebarHeader`, `SidebarBody`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarToggle`, `SidebarTrigger`, `SidebarInset`, `SidebarRail` |
-| `registryDependencies` | None |
-| `features` | `standalone static surface`, `controlled collapse`, `uncontrolled collapse`, `group labels`, `icon-only collapsed state`, `logical side placement` |
-| `tokens` | `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-sidebar-bg`, `--bh-sidebar-bg-collapsed`, `--bh-sidebar-border`, `--bh-sidebar-icon-size`, `--bh-sidebar-item-bg-active`, `--bh-sidebar-item-bg-hover`, `--bh-sidebar-item-content`, `--bh-sidebar-item-content-active`, `--bh-sidebar-item-gap`, `--bh-sidebar-item-height`, `--bh-sidebar-item-padding-x`, `--bh-sidebar-padding`, `--bh-sidebar-rail-width`, `--bh-sidebar-width`, `--bh-sidebar-width-collapsed`, `--bh-space-19xl-384`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--shadow-button-focus`, `--shadow-sidebar` |
+| `supportedExports` | `components/sidebar.tsx: Sidebar, SidebarBody, SidebarFooter, SidebarFooterUser, SidebarGroup, SidebarGroupAction, SidebarGroupLabel, SidebarHeader, SidebarHeaderAction, SidebarHeaderBrand, SidebarHeaderWorkspaceSwitch, SidebarInset, SidebarMenu, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuTreeItem, SidebarProvider, SidebarRail, SidebarToggle, SidebarTreeGroup, SidebarTrigger` |
+| `parts` | `SidebarProvider`, `Sidebar`, `SidebarHeader`, `SidebarHeaderAction`, `SidebarHeaderBrand`, `SidebarHeaderWorkspaceSwitch`, `SidebarBody`, `SidebarFooter`, `SidebarFooterUser`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupLabel`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuTreeItem`, `SidebarTreeGroup`, `SidebarToggle`, `SidebarTrigger`, `SidebarInset`, `SidebarRail` |
+| `registryDependencies` | `tooltip` |
+| `props.collapsed` | `boolean; default false; Controls the provider-owned 280px expanded or 48px rail state. Pair with onCollapsedChange for controlled usage.` |
+| `props.defaultCollapsed` | `boolean; default false; Sets the initial rail state when SidebarProvider owns collapse state internally.` |
+| `props.showIdentityPreview` | `boolean; default true; Reveals the collapsed footer user's name and supporting text beside the rail on hover or keyboard focus.` |
+| `props.side` | `"start" \| "end"; default "start"; Places Sidebar on the logical start or end edge and selects the matching logical border.` |
+| `props.variant` | `SidebarMenuButtonVariant \| SidebarWorkspaceVariant \| "default" \| "supporting-text"; default "part-specific"; Selects default/avatar/nested menu rows, action/card workspace headers, or default/supporting-text footers on the part that owns it.` |
+| `props.active` | `boolean; default false; Applies the selected menu or tree treatment and exposes aria-current="page".` |
+| `props.state` | `"default" \| "hover" \| "active" \| "focus"; default "default"; Deterministic interaction state for documentation matrices; product hover and focus remain native CSS interactions.` |
+| `props.showLine` | `boolean; default false; Selects the neutral/brand line-guided Level 2 treatment on SidebarMenuSubButton.` |
+| `props.level` | `1 \| 2 \| 3 \| 4; default 1; Controls tokenized logical indentation for SidebarMenuTreeItem.` |
+| `props.expandable` | `boolean; default false; Adds a disclosure affordance to group labels or tree-group headings.` |
+| `props.asChild` | `boolean; default false; Renders menu, tree, or inset content through Radix Slot while preserving sidebar layout and semantics.` |
+| `directions` | `ltr`, `rtl` |
+| `features` | `280px expanded and 48px collapsed shells`, `controlled collapse`, `uncontrolled collapse`, `brand header with search and collapse actions`, `workspace action and card headers`, `visible collapsed-header expand action`, `default, avatar, Level 2, and Level 2 line menu rows`, `supporting text, count badge, and trailing action slots`, `group labels with disclosure and icon actions`, `four-level tree navigation`, `supporting-text and bordered user footers`, `collapsed footer identity preview on hover and keyboard focus`, `tokenized staged expand and collapse motion`, `reduced-motion fallback`, `icon-only rail with tooltips`, `logical side placement and RTL mirroring` |
+| `sides` | `start`, `end` |
+| `states` | `default`, `hover`, `active`, `focus`, `expanded`, `collapsed` |
+| `tokens` | `--bh-bg-brand-default`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-sm`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-active`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-sidebar-active-guide-height`, `--bh-sidebar-bg`, `--bh-sidebar-bg-collapsed`, `--bh-sidebar-border`, `--bh-sidebar-brand-height`, `--bh-sidebar-compact-control-size`, `--bh-sidebar-header-action-size`, `--bh-sidebar-icon-size`, `--bh-sidebar-icon-size-collapsed`, `--bh-sidebar-icon-slot-size`, `--bh-sidebar-item-bg-active`, `--bh-sidebar-item-bg-hover`, `--bh-sidebar-item-content`, `--bh-sidebar-item-content-active`, `--bh-sidebar-item-height`, `--bh-sidebar-item-height-collapsed`, `--bh-sidebar-item-padding-x`, `--bh-sidebar-level-2-indent-width`, `--bh-sidebar-min-height`, `--bh-sidebar-motion-delay-content`, `--bh-sidebar-motion-duration`, `--bh-sidebar-motion-duration-content`, `--bh-sidebar-motion-easing`, `--bh-sidebar-padding`, `--bh-sidebar-rail-width`, `--bh-sidebar-tree-indent-step`, `--bh-sidebar-tree-item-height`, `--bh-sidebar-user-preview-gap`, `--bh-sidebar-user-preview-height`, `--bh-sidebar-user-preview-width`, `--bh-sidebar-width`, `--bh-sidebar-width-collapsed`, `--bh-sidebar-workspace-card-height`, `--bh-sidebar-workspace-trigger-max-width`, `--bh-sidebar-workspace-trigger-width`, `--bh-space-10xl-80`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--bh-text-body-3xs-semibold-letter-spacing`, `--bh-text-body-3xs-semibold-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xl-semibold-font-size`, `--bh-text-body-xl-semibold-font-weight`, `--bh-text-body-xl-semibold-letter-spacing`, `--bh-text-body-xl-semibold-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-text-body-xs-semibold-font-weight`, `--bh-z-overlay`, `--elevation-button-focus`, `--elevation-component-default` |
+| `variants` | `default menu`, `avatar menu`, `Level 2 menu`, `Level 2 line menu`, `workspace actions`, `workspace card`, `default footer`, `supporting-text footer` |
 <!-- registry-contract:end -->

package/docs/design-system/components/skeleton.md

@@ -1,77 +1,77 @@
-# Skeleton
-
-Skeleton is the token-built loading placeholder system for pending content. It includes a small primitive plus composed text, avatar, button, input, card, list, table, and form placeholders.
-
-## API
-
-```tsx
-import {
-  Skeleton,
-  SkeletonCard,
-  SkeletonTable,
-  SkeletonText,
-} from "@/components/ui/skeleton"
-
-export function LoadingPanel() {
-  return (
-    <section aria-busy="true" aria-label="Loading project details">
-      <SkeletonCard />
-      <SkeletonTable rows={4} columns={4} />
-    </section>
-  )
-}
-```
-
-| Export | Purpose |
-| --- | --- |
-| `Skeleton` | Base block, text, or circle placeholder. |
-| `SkeletonText` | Multi-line text placeholder with optional line widths. |
-| `SkeletonAvatar` | Token-sized circular avatar placeholder. |
-| `SkeletonButton` | Button-height placeholder for actions and icon buttons. |
-| `SkeletonInput` | Label, control, and helper-text loading field. |
-| `SkeletonCard` | Media, avatar/text, and action skeleton composition. |
-| `SkeletonList` | Repeated row loading state for feeds, menus, and lists. |
-| `SkeletonTable` | Header and row loading state for table surfaces. |
-| `SkeletonForm` | Repeated input loading state with footer actions. |
-
-## Token Contract
-
-Skeleton consumes Banhaten background, border, radius, spacing, button, card, opacity, and shadow tokens. Custom layout sizing should be passed through CSS variables or token classes rather than raw dimensions.
-
-- Fill: `--bh-bg-muted`, `--bh-bg-subtle`, `--bh-bg-raised-subtle`, `--bh-bg-brand-subtle`
-- Highlight: `--bh-bg-raised-subtle`, `--bh-bg-default`, `--bh-bg-brand-soft`
-- Shape: `--bh-radius-md-6`, `--bh-radius-full`, `--bh-control-default`
-- Layout: `--bh-space-*`, `--bh-button-*-height`, `--bh-card-desktop-content-padding`
-
-## RTL And Accessibility
-
-- Skeleton compositions inherit `dir` from the nearest parent.
-- The shimmer direction mirrors in RTL containers.
-- Skeletons are decorative by default. Put `aria-busy="true"` and an accessible label or status message on the loading region when the loading state needs to be announced.
-
-## Install
-
-```bash
-npx banhaten add skeleton
-```
-
-## Examples
-
-Primary registry example: `examples/skeleton-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs skeleton` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `motion`: The shimmer direction mirrors inside RTL containers while preserving logical layout.
-- `composition`: Composed card, list, table, and form placeholders use logical gaps, inherited direction, and token-sized rows.
-- `accessibility`: Skeletons are decorative by default; set aria-busy on the loading region and pair with a status label when loading progress needs to be announced.
-
-## Accessibility
-
-Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
-
+# Skeleton
+
+Skeleton is the token-built loading placeholder system for pending content. It includes a small primitive plus composed text, avatar, button, input, card, list, table, and form placeholders.
+
+## API
+
+```tsx
+import {
+  Skeleton,
+  SkeletonCard,
+  SkeletonTable,
+  SkeletonText,
+} from "@/components/ui/skeleton"
+
+export function LoadingPanel() {
+  return (
+    <section aria-busy="true" aria-label="Loading project details">
+      <SkeletonCard />
+      <SkeletonTable rows={4} columns={4} />
+    </section>
+  )
+}
+```
+
+| Export | Purpose |
+| --- | --- |
+| `Skeleton` | Base block, text, or circle placeholder. |
+| `SkeletonText` | Multi-line text placeholder with optional line widths. |
+| `SkeletonAvatar` | Token-sized circular avatar placeholder. |
+| `SkeletonButton` | Button-height placeholder for actions and icon buttons. |
+| `SkeletonInput` | Label, control, and helper-text loading field. |
+| `SkeletonCard` | Media, avatar/text, and action skeleton composition. |
+| `SkeletonList` | Repeated row loading state for feeds, menus, and lists. |
+| `SkeletonTable` | Header and row loading state for table surfaces. |
+| `SkeletonForm` | Repeated input loading state with footer actions. |
+
+## Token Contract
+
+Skeleton consumes Banhaten background, border, radius, spacing, button, card, opacity, and elevation tokens. Custom layout sizing should be passed through CSS variables or token classes rather than raw dimensions.
+
+- Fill: `--bh-bg-muted`, `--bh-bg-subtle`, `--bh-bg-raised-subtle`, `--bh-bg-brand-subtle`
+- Highlight: `--bh-bg-raised-subtle`, `--bh-bg-default`, `--bh-bg-brand-soft`
+- Shape: `--bh-radius-md-6`, `--bh-radius-full`, `--bh-control-default`
+- Layout: `--bh-space-*`, `--bh-button-*-height`, `--bh-card-desktop-content-padding`
+
+## RTL And Accessibility
+
+- Skeleton compositions inherit `dir` from the nearest parent.
+- The shimmer direction mirrors in RTL containers.
+- Skeletons are decorative by default. Put `aria-busy="true"` and an accessible label or status message on the loading region when the loading state needs to be announced.
+
+## Install
+
+```bash
+npx banhaten add skeleton
+```
+
+## Examples
+
+Primary registry example: `examples/skeleton-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs skeleton` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `motion`: The shimmer direction mirrors inside RTL containers while preserving logical layout.
+- `composition`: Composed card, list, table, and form placeholders use logical gaps, inherited direction, and token-sized rows.
+- `accessibility`: Skeletons are decorative by default; set aria-busy on the loading region and pair with a status label when loading progress needs to be announced.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -86,6 +86,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `shimmer animation`, `reduced motion`, `text lines`, `avatar placeholders`, `button placeholders`, `input placeholders`, `card placeholders`, `list placeholders`, `table placeholders`, `form placeholders` |
 | `shapes` | `block`, `text`, `circle` |
 | `sizes` | `xs`, `sm`, `md`, `lg`, `xl` |
-| `tokens` | `--bh-alpha-alpha-transparent`, `--bh-bg-brand-soft`, `--bh-bg-brand-subtle`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-muted`, `--bh-bg-raised`, `--bh-bg-raised-subtle`, `--bh-bg-subtle`, `--bh-border-default`, `--bh-border-subtle`, `--bh-button-lg-height`, `--bh-button-md-height`, `--bh-button-sm-height`, `--bh-button-xl-height`, `--bh-card-desktop-content-padding`, `--bh-control-default`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-skeleton-bg`, `--bh-skeleton-duration`, `--bh-skeleton-height`, `--bh-skeleton-highlight`, `--bh-skeleton-radius`, `--bh-skeleton-shimmer-width`, `--bh-skeleton-table-columns`, `--bh-skeleton-width`, `--bh-space-11xl-96`, `--bh-space-12xl-128`, `--bh-space-13xl-160`, `--bh-space-14xl-192`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-regular-line-height`, `--shadow-component-default` |
+| `tokens` | `--bh-alpha-alpha-transparent`, `--bh-bg-brand-soft`, `--bh-bg-brand-subtle`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-muted`, `--bh-bg-raised`, `--bh-bg-raised-subtle`, `--bh-bg-subtle`, `--bh-border-default`, `--bh-border-subtle`, `--bh-button-lg-height`, `--bh-button-md-height`, `--bh-button-sm-height`, `--bh-button-xl-height`, `--bh-card-desktop-content-padding`, `--bh-control-default`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-skeleton-bg`, `--bh-skeleton-duration`, `--bh-skeleton-height`, `--bh-skeleton-highlight`, `--bh-skeleton-radius`, `--bh-skeleton-shimmer-width`, `--bh-skeleton-table-columns`, `--bh-skeleton-width`, `--bh-space-11xl-96`, `--bh-space-12xl-128`, `--bh-space-13xl-160`, `--bh-space-14xl-192`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-regular-line-height`, `--elevation-component-default` |
 | `tones` | `default`, `subtle`, `surface`, `brand` |
 <!-- registry-contract:end -->