banhaten 0.5.0 → 0.6.0

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

@@ -1,110 +1,160 @@
-# 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.
-
+# 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, bordered, or inset card 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.
+
+## Sizes
+
+`SidebarProvider` accepts `size="default" | "comfortable"`. The default size is the 32px Figma menu-item set. The comfortable size matches application shells that use 40px navigation rows:
+
+| | `default` | `comfortable` |
+| --- | --- | --- |
+| Menu row height | 32px | 40px (`--bh-sidebar-comfortable-item-height`) |
+| Gap between rows | 0 | 8px (`--bh-sidebar-comfortable-item-gap`) |
+| Row label | body-sm 14/20 | body-md 15/24 |
+| Icon to label | 6px gap + 4px label padding | 6px gap + 2px label padding |
+| Header, body and footer inline padding | 10px / 12px / 10px | 16px (`--bh-sidebar-comfortable-padding`) |
+| Rail edge | 1px end border | 1px stroke inside all four sides, an outline inset by its width (`--bh-sidebar-border`) |
+| Header to first menu, between body sections, and above the footer | header and footer padding | 24px (`--bh-sidebar-comfortable-section-gap`) |
+| Brand name | body-xl semibold 20/30 | heading-md semibold 24/28 |
+| Group label row | 24px with 4px bottom padding, 12px/6px group padding | 20px, no group padding, 8px to the first row |
+
+Comfortable rules apply only while the sidebar is expanded; the 48px collapsed rail is identical at both sizes. In comfortable sidebars the body is a flex column, so a section can be pinned to the bottom with `className="mt-auto"`.
+
+```tsx
+<SidebarProvider size="comfortable">
+  <Sidebar>
+    <SidebarHeader>
+      <SidebarHeaderBrand
+        brand="ATS360"
+        collapseAction={false}
+        logo={false}
+        searchAction={false}
+        subtitle="Recruiting"
+      />
+    </SidebarHeader>
+    <SidebarBody>
+      <SidebarMenu>{/* 40px rows */}</SidebarMenu>
+      <SidebarGroup className="mt-auto">
+        <SidebarGroupLabel>WORKSPACE</SidebarGroupLabel>
+        <SidebarMenu>{/* label-only rows */}</SidebarMenu>
+      </SidebarGroup>
+    </SidebarBody>
+    <SidebarFooter divider={false}>
+      <SidebarFooterUser name="Omar Ali" supportText="Talent acquisition" variant="card" />
+    </SidebarFooter>
+  </Sidebar>
+</SidebarProvider>
+```
+
+`SidebarHeaderBrand` takes `logo={false}` for a text-only brand and `subtitle` for a stacked product or module line in body-sm `content-subtle`. A collapsed text-only brand shows only its header actions.
+
+`SidebarFooterUser variant="card"` renders the signed-in user as an inset `--bh-sidebar-user-card-bg` block with 8px padding, a body-md medium name and a body-sm subtle role. It shows no avatar or chevron unless `avatar` or `trailingIcon` is passed. Any footer variant accepts `avatar={false}` and `trailingIcon={false}` to hide those slots while expanded. Pair the card with `SidebarFooter divider={false}` to drop the top rule.
+
+Group label text uses `--bh-sidebar-group-label-content`, which defaults to `--bh-content-muted`. A product theme can point it at `--bh-content-subtle` without restyling the label.
+
+## 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
 
@@ -118,9 +168,15 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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.size` | `"default" \| "comfortable"; default "default"; Set on SidebarProvider. comfortable uses 40px rows 8px apart with body-md labels, 16px shell padding, a 24px section gap, a heading-md brand, and 20px group labels; the collapsed rail is unchanged.` |
+| `props.subtitle` | `React.ReactNode; default "undefined"; Adds a body-sm content-subtle line under the SidebarHeaderBrand name and switches the brand to a stacked layout.` |
+| `props.logo` | `React.ReactNode \| false; default "Sparkles glyph"; Replaces the SidebarHeaderBrand mark; false renders a text-only brand with no logo slot.` |
+| `props.divider` | `boolean; default true; Draws the SidebarFooter top rule; false removes it for inset footer cards.` |
+| `props.avatar` | `React.ReactNode \| false; default "person glyph"; Replaces the SidebarFooterUser avatar; false hides the slot while expanded. The collapsed rail always shows a glyph.` |
+| `props.trailingIcon` | `React.ReactNode \| false; default "part-specific"; Trailing glyph on menu rows and the footer user; false hides the footer user's chevron.` |
 | `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.variant` | `SidebarMenuButtonVariant \| SidebarWorkspaceVariant \| "default" \| "supporting-text" \| "card"; default "part-specific"; Selects default/avatar/nested menu rows, action/card workspace headers, or default/supporting-text/card footers on the part that owns it. The card footer is an inset bg-subtle block with a body-md name and body-sm role and no avatar or chevron unless passed.` |
 | `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.` |
@@ -128,9 +184,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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` |
+| `features` | `280px expanded and 48px collapsed shells`, `comfortable size with 40px rows, 8px row gap, and body-md labels`, `controlled collapse`, `uncontrolled collapse`, `brand header with search and collapse actions`, `text-only brand with a stacked subtitle`, `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, icon actions, and a tokenized label color`, `four-level tree navigation`, `supporting-text, bordered, and inset card user footers`, `divider-free footer`, `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` |
+| `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-comfortable-brand-padding`, `--bh-sidebar-comfortable-group-label-height`, `--bh-sidebar-comfortable-item-gap`, `--bh-sidebar-comfortable-item-height`, `--bh-sidebar-comfortable-label-padding`, `--bh-sidebar-comfortable-padding`, `--bh-sidebar-comfortable-section-gap`, `--bh-sidebar-compact-control-size`, `--bh-sidebar-group-label-content`, `--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-card-bg`, `--bh-sidebar-user-card-bg-hover`, `--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-none`, `--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-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-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-text-heading-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-letter-spacing`, `--bh-text-heading-md-semibold-line-height`, `--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`, `card footer`, `comfortable size` |
 <!-- 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 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.
-
+# 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
 

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

@@ -1,67 +1,67 @@
-# Slideout
-
-`Slideout` renders a right- or left-aligned panel for focused secondary workflows. It supports desktop and mobile breakpoints, three desktop widths, optional header action, optional footer actions, and LTR/RTL direction.
-
-Figma reference: `Slideout`, node `256:19065`.
-
-## Examples
-
-The local implementation includes these Figma slot-content examples:
-
-| Example | Figma node |
-| --- | --- |
-| Filters | `256:18779` |
-| User profile activity | `256:18872` |
-| Payment detail | `256:18901` |
-| Payment detail 02 | `256:18964` |
-
-## API
-
-```tsx
-<Slideout size="small" breakpoint="desktop" dir="ltr">
-  <SlideoutFiltersExample />
-</Slideout>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `size` | `small`, `medium`, `large` | `small` |
-| `breakpoint` | `desktop`, `mobile` | `desktop` |
-| `dir` | `ltr`, `rtl` | `ltr` |
-| `title` | `string` | none |
-| `headerAction` | `boolean` | `true` |
-| `footer` | `boolean` | `true` |
-| `secondaryAction` | `boolean` | `true` |
-
-## Layout
-
-- Desktop outer sizes match the Figma matrix: small `356px`, medium `416px`, and large `516px`, each at `900px` height.
-- Mobile uses `375px x 812px` and removes the desktop panel corner radius.
-- Header and footer are fixed-height regions; the body owns vertical scrolling.
-- Slot content is passed as children so product workflows can compose filters, activity, payment details, forms, or custom content without changing the panel API.
-
-## Accessibility
-
-- The panel uses `role="dialog"` with the current title as its accessible label.
-- Close and action controls are real buttons.
-- Slot examples keep text content as real text and mirror layout through `dir="rtl"` rather than separate component APIs.
-
-## Install
-
-```bash
-npx banhaten add slideout
-```
-
-## Token Contract
-
-Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
-Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
-Covered source files: `components/expanded/slideout.css`, `components/expanded/Slideout.tsx`.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
-
+# Slideout
+
+`Slideout` renders a right- or left-aligned panel for focused secondary workflows. It supports desktop and mobile breakpoints, three desktop widths, optional header action, optional footer actions, and LTR/RTL direction.
+
+Figma reference: `Slideout`, node `256:19065`.
+
+## Examples
+
+The local implementation includes these Figma slot-content examples:
+
+| Example | Figma node |
+| --- | --- |
+| Filters | `256:18779` |
+| User profile activity | `256:18872` |
+| Payment detail | `256:18901` |
+| Payment detail 02 | `256:18964` |
+
+## API
+
+```tsx
+<Slideout size="small" breakpoint="desktop" dir="ltr">
+  <SlideoutFiltersExample />
+</Slideout>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `small`, `medium`, `large` | `small` |
+| `breakpoint` | `desktop`, `mobile` | `desktop` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `title` | `string` | none |
+| `headerAction` | `boolean` | `true` |
+| `footer` | `boolean` | `true` |
+| `secondaryAction` | `boolean` | `true` |
+
+## Layout
+
+- Desktop outer sizes match the Figma matrix: small `356px`, medium `416px`, and large `516px`, each at `900px` height.
+- Mobile uses `375px x 812px` and removes the desktop panel corner radius.
+- Header and footer are fixed-height regions; the body owns vertical scrolling.
+- Slot content is passed as children so product workflows can compose filters, activity, payment details, forms, or custom content without changing the panel API.
+
+## Accessibility
+
+- The panel uses `role="dialog"` with the current title as its accessible label.
+- Close and action controls are real buttons.
+- Slot examples keep text content as real text and mirror layout through `dir="rtl"` rather than separate component APIs.
+
+## Install
+
+```bash
+npx banhaten add slideout
+```
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/slideout.css`, `components/expanded/Slideout.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
 <!-- registry-contract:start -->
 ## Registry Contract