banhaten 0.2.0 → 0.4.0

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

@@ -25,7 +25,7 @@ Pagination navigates paged result sets, tables, and long lists. It supports nume
 
 ## Token Contract
 
-Pagination uses Banhaten control height, radius, border, background, content, focus, icon, caption, and shadow tokens.
+Pagination uses Banhaten control height, radius, border, background, content, focus, icon, caption, and shadow tokens. Previous/next glyphs are 18px inside 20px slots.
 
 ## RTL
 
@@ -65,7 +65,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/pagination.tsx: Pagination, arabicPaginationMessages, paginationControlVariants, paginationItemVariants, paginationVariants` |
 | `parts` | `Pagination` |
 | `registryDependencies` | None |
-| `tokens` | `--bh-border-brand-strong`, `--bh-content-disabled`, `--bh-icon-stroke-225`, `--bh-pagination-action-gap`, `--bh-pagination-active-bg`, `--bh-pagination-active-border`, `--bh-pagination-active-content`, `--bh-pagination-caption-content`, `--bh-pagination-caption-font-weight`, `--bh-pagination-caption-width`, `--bh-pagination-control-content`, `--bh-pagination-control-gap`, `--bh-pagination-control-ghost-bg`, `--bh-pagination-control-ghost-hover`, `--bh-pagination-control-ghost-pressed`, `--bh-pagination-control-label-padding-x`, `--bh-pagination-control-label-rtl-padding-x`, `--bh-pagination-control-soft-bg`, `--bh-pagination-control-soft-hover`, `--bh-pagination-control-soft-pressed`, `--bh-pagination-control-text-gap`, `--bh-pagination-control-text-padding-x`, `--bh-pagination-control-text-rtl-gap`, `--bh-pagination-control-text-rtl-padding-x`, `--bh-pagination-font-size`, `--bh-pagination-icon-size`, `--bh-pagination-item-size`, `--bh-pagination-label-font-weight`, `--bh-pagination-letter-spacing`, `--bh-pagination-line-height`, `--bh-pagination-numeric-width`, `--bh-pagination-page-bg`, `--bh-pagination-page-content`, `--bh-pagination-page-gap`, `--bh-pagination-page-hover`, `--bh-pagination-page-pressed`, `--bh-pagination-radius`, `--bh-pagination-root-gap`, `--bh-pagination-simple-width`, `--bh-space-md-8`, `--shadow-pagination-active`, `--shadow-pagination-control`, `--shadow-pagination-focus` |
+| `features` | `container-aware compact numeric pages`, `contained horizontal control scrolling`, `wrapping captions and summaries` |
+| `tokens` | `--bh-border-brand-strong`, `--bh-content-disabled`, `--bh-icon-stroke-225`, `--bh-pagination-action-gap`, `--bh-pagination-active-bg`, `--bh-pagination-active-border`, `--bh-pagination-active-content`, `--bh-pagination-caption-content`, `--bh-pagination-caption-font-weight`, `--bh-pagination-caption-width`, `--bh-pagination-control-content`, `--bh-pagination-control-gap`, `--bh-pagination-control-ghost-bg`, `--bh-pagination-control-ghost-hover`, `--bh-pagination-control-ghost-pressed`, `--bh-pagination-control-label-padding-x`, `--bh-pagination-control-label-rtl-padding-x`, `--bh-pagination-control-soft-bg`, `--bh-pagination-control-soft-hover`, `--bh-pagination-control-soft-pressed`, `--bh-pagination-control-text-gap`, `--bh-pagination-control-text-padding-x`, `--bh-pagination-control-text-rtl-gap`, `--bh-pagination-control-text-rtl-padding-x`, `--bh-pagination-font-size`, `--bh-pagination-icon-size`, `--bh-pagination-icon-slot-size`, `--bh-pagination-item-size`, `--bh-pagination-label-font-weight`, `--bh-pagination-letter-spacing`, `--bh-pagination-line-height`, `--bh-pagination-numeric-width`, `--bh-pagination-page-bg`, `--bh-pagination-page-content`, `--bh-pagination-page-gap`, `--bh-pagination-page-hover`, `--bh-pagination-page-pressed`, `--bh-pagination-radius`, `--bh-pagination-root-gap`, `--bh-pagination-simple-width`, `--bh-space-md-8`, `--shadow-pagination-active`, `--shadow-pagination-control`, `--shadow-pagination-focus` |
 | `types` | `numeric`, `simple`, `summary` |
 | `variants` | `soft`, `ghost` |
 <!-- registry-contract:end -->

package/docs/design-system/components/radio-card.md

@@ -60,6 +60,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `RadioCard` |
 | `registryDependencies` | None |
 | `states` | `default`, `active`, `disabled` |
-| `tokens` | `--bh-bg-accent-blue-soft`, `--bh-bg-accent-purple-soft`, `--bh-bg-always-white`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-stroke-180`, `--bh-icon-stroke-200`, `--bh-interactive-radiobutton-default`, `--bh-opacity-disabled-media`, `--bh-radio-card-bg`, `--bh-radio-card-border`, `--bh-radio-card-border-width`, `--bh-radio-card-border-width-active`, `--bh-radio-card-company-mark-color`, `--bh-radio-card-payment-height`, `--bh-radio-card-payment-logo-color`, `--bh-radio-card-payment-logo-height`, `--bh-radio-card-payment-logo-width`, `--bh-radio-card-payment-width`, `--bh-radio-card-width`, `--bh-radio-control-border`, `--bh-radius-full`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-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`, `--shadow-component-default`, `--shadow-radio-card`, `--shadow-radio-card-current`, `--shadow-radio-card-disabled`, `--shadow-radio-control` |
+| `tokens` | `--bh-bg-accent-blue-soft`, `--bh-bg-accent-purple-soft`, `--bh-bg-always-white`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-180`, `--bh-icon-stroke-200`, `--bh-interactive-radiobutton-default`, `--bh-opacity-disabled-media`, `--bh-radio-card-bg`, `--bh-radio-card-border`, `--bh-radio-card-border-width`, `--bh-radio-card-border-width-active`, `--bh-radio-card-company-mark-color`, `--bh-radio-card-payment-height`, `--bh-radio-card-payment-logo-color`, `--bh-radio-card-payment-logo-height`, `--bh-radio-card-payment-logo-width`, `--bh-radio-card-payment-width`, `--bh-radio-card-width`, `--bh-radio-control-border`, `--bh-radius-full`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-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`, `--shadow-component-default`, `--shadow-radio-card`, `--shadow-radio-card-current`, `--shadow-radio-card-disabled`, `--shadow-radio-control` |
 | `types` | `with-icon`, `icon-radio-right`, `payment`, `with-avatar`, `company-icon`, `icon-radio-left`, `radio-label` |
 <!-- registry-contract:end -->

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

@@ -53,5 +53,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` |
 | `registryDependencies` | None |
 | `features` | `horizontal panels`, `vertical panels`, `keyboard resize handle` |
-| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-muted`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-z-raised`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-muted`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-z-raised`, `--shadow-button-focus`, `--shadow-component-focus-ring` |
 <!-- registry-contract:end -->

package/docs/design-system/components/scroll-area.md

@@ -8,11 +8,15 @@ Scroll Area wraps Radix ScrollArea with tokenized viewport, scrollbar, thumb, an
 <ScrollArea className="h-48">
   <div>Scrollable content</div>
 </ScrollArea>
+
+<ScrollArea className="h-48" orientation="both">
+  <div className="h-max w-max">Two-axis content</div>
+</ScrollArea>
 ```
 
 | Part | Purpose |
 | --- | --- |
-| `ScrollArea` | root and viewport |
+| `ScrollArea` | root and viewport; `orientation` accepts `vertical`, `horizontal`, or `both` |
 | `ScrollBar` | vertical or horizontal scrollbar |
 
 ## Token Contract
@@ -55,6 +59,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/scroll-area.tsx: ScrollArea, ScrollBar` |
 | `parts` | `ScrollArea`, `ScrollBar` |
 | `registryDependencies` | None |
-| `features` | `vertical scrollbar`, `horizontal scrollbar`, `viewport clipping` |
-| `tokens` | `--bh-border-default`, `--bh-radius-full`, `--bh-space-lg-10`, `--bh-space-xxs-2` |
+| `features` | `vertical scrollbar`, `horizontal scrollbar`, `two-axis scrollbar composition`, `viewport clipping`, `keyboard-focusable viewport`, `viewportProps escape hatch` |
+| `tokens` | `--bh-border-default`, `--bh-radius-full`, `--bh-space-lg-10`, `--bh-space-xxs-2`, `--shadow-component-focus-ring` |
 <!-- registry-contract:end -->

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

@@ -82,6 +82,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `selectionTypes` | `default`, `checkbox` |
 | `sizes` | `lg`, `md`, `comfortable` |
 | `states` | `default`, `filled`, `error`, `disabled` |
-| `tokens` | `--bh-bg-accent-blue-default`, `--bh-bg-accent-blue-soft`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-red-default`, `--bh-bg-always-white`, `--bh-bg-brand-default`, `--bh-bg-danger-default`, `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-info-default`, `--bh-bg-neutral-default`, `--bh-bg-success-default`, `--bh-bg-warning-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-accent-blue-strong`, `--bh-content-accent-purple-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-weight-semibold`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-interactive-checkbox-default`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-select-avatar-font-size`, `--bh-select-check-color`, `--bh-select-checkbox-border`, `--bh-select-checkbox-icon-size`, `--bh-select-checkbox-radius`, `--bh-select-checkbox-size`, `--bh-select-company-icon-size`, `--bh-select-content-gap`, `--bh-select-field-gap`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-item-check-offset`, `--bh-select-item-content-padding`, `--bh-select-item-gap`, `--bh-select-item-hover-bg`, `--bh-select-item-min-height`, `--bh-select-item-padding-x`, `--bh-select-item-radius`, `--bh-select-item-selected-padding-end`, `--bh-select-item-value-padding-x`, `--bh-select-label-gap`, `--bh-select-media-inset`, `--bh-select-menu-bg`, `--bh-select-menu-list-gap`, `--bh-select-menu-offset`, `--bh-select-menu-padding-y`, `--bh-select-menu-radius`, `--bh-select-menu-width`, `--bh-select-payment-height`, `--bh-select-payment-mark-offset`, `--bh-select-payment-mark-size`, `--bh-select-payment-radius`, `--bh-select-payment-width`, `--bh-select-status-dot-size`, `--bh-select-trigger-bg`, `--bh-select-trigger-bg-disabled`, `--bh-select-trigger-bg-soft`, `--bh-select-trigger-border`, `--bh-select-trigger-border-current`, `--bh-select-trigger-border-disabled`, `--bh-select-trigger-border-error`, `--bh-select-trigger-border-focus`, `--bh-select-trigger-gap`, `--bh-select-trigger-icon-color`, `--bh-select-trigger-padding-x`, `--bh-select-trigger-padding-y-comfortable`, `--bh-select-trigger-padding-y-lg`, `--bh-select-trigger-padding-y-md`, `--bh-select-trigger-radius`, `--bh-select-value-padding-inline`, `--bh-select-width`, `--bh-space-md-8`, `--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-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--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-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`, `--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-z-popover`, `--shadow-component-default`, `--shadow-select-checkbox`, `--shadow-select-danger-focus-ring`, `--shadow-select-focus-ring`, `--shadow-select-menu`, `--shadow-select-trigger` |
+| `tokens` | `--bh-bg-accent-blue-default`, `--bh-bg-accent-blue-soft`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-red-default`, `--bh-bg-always-white`, `--bh-bg-brand-default`, `--bh-bg-danger-default`, `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-info-default`, `--bh-bg-neutral-default`, `--bh-bg-success-default`, `--bh-bg-warning-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-accent-blue-strong`, `--bh-content-accent-purple-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-interactive-checkbox-default`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-select-avatar-font-size`, `--bh-select-check-color`, `--bh-select-checkbox-border`, `--bh-select-checkbox-icon-size`, `--bh-select-checkbox-radius`, `--bh-select-checkbox-size`, `--bh-select-company-icon-size`, `--bh-select-content-gap`, `--bh-select-field-gap`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-item-check-offset`, `--bh-select-item-content-padding`, `--bh-select-item-gap`, `--bh-select-item-hover-bg`, `--bh-select-item-min-height`, `--bh-select-item-padding-x`, `--bh-select-item-radius`, `--bh-select-item-selected-padding-end`, `--bh-select-item-value-padding-x`, `--bh-select-label-gap`, `--bh-select-media-inset`, `--bh-select-menu-bg`, `--bh-select-menu-list-gap`, `--bh-select-menu-offset`, `--bh-select-menu-padding-y`, `--bh-select-menu-radius`, `--bh-select-menu-width`, `--bh-select-payment-height`, `--bh-select-payment-mark-offset`, `--bh-select-payment-mark-size`, `--bh-select-payment-radius`, `--bh-select-payment-width`, `--bh-select-status-dot-size`, `--bh-select-trigger-bg`, `--bh-select-trigger-bg-disabled`, `--bh-select-trigger-bg-soft`, `--bh-select-trigger-border`, `--bh-select-trigger-border-current`, `--bh-select-trigger-border-disabled`, `--bh-select-trigger-border-error`, `--bh-select-trigger-border-focus`, `--bh-select-trigger-gap`, `--bh-select-trigger-icon-color`, `--bh-select-trigger-padding-x`, `--bh-select-trigger-padding-y-comfortable`, `--bh-select-trigger-padding-y-lg`, `--bh-select-trigger-padding-y-md`, `--bh-select-trigger-radius`, `--bh-select-value-padding-inline`, `--bh-select-width`, `--bh-space-md-8`, `--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-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--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-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`, `--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-z-popover`, `--shadow-component-default`, `--shadow-select-checkbox`, `--shadow-select-danger-focus-ring`, `--shadow-select-focus-ring`, `--shadow-select-menu`, `--shadow-select-trigger` |
 | `variants` | `default`, `soft` |
 <!-- registry-contract:end -->

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

@@ -1,6 +1,8 @@
 # Sidebar
 
-Sidebar is a composable app navigation surface with collapse state, grouped menu items, logical start/end placement, and generated `--bh-sidebar-*` tokens.
+Sidebar is the complete Figma-aligned application navigation system. It provides a 280px expanded shell and 48px icon rail, brand and workspace headers, grouped and nested menus, tree navigation, badges and actions, user footers, 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
 
@@ -8,19 +10,33 @@ Sidebar is a composable app navigation surface with collapse state, grouped menu
 <SidebarProvider>
   <Sidebar>
     <SidebarHeader>
-      Workspace
-      <SidebarToggle />
+      <SidebarHeaderWorkspaceSwitch label="Acme Inc" />
     </SidebarHeader>
     <SidebarBody>
       <SidebarGroup>
         <SidebarGroupLabel>Main</SidebarGroupLabel>
         <SidebarMenu>
           <SidebarMenuItem>
-            <SidebarMenuButton active>Overview</SidebarMenuButton>
+            <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>
 ```
@@ -28,26 +44,37 @@ Sidebar is a composable app navigation surface with collapse state, grouped menu
 | Part | Purpose |
 | --- | --- |
 | `SidebarProvider` | controlled or uncontrolled collapsed state |
-| `Sidebar` | navigation surface |
+| `Sidebar` | 280px navigation surface and 48px collapsed rail |
 | `SidebarHeader`, `SidebarBody`, `SidebarFooter` | layout regions |
-| `SidebarGroup`, `SidebarGroupLabel` | grouped navigation |
-| `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton` | menu structure |
+| `SidebarHeaderBrand`, `SidebarHeaderWorkspaceSwitch` | brand and workspace header compositions |
+| `SidebarHeaderAction` | compact search or custom header action |
+| `SidebarFooterUser` | supporting-text or bordered user switcher |
+| `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.
+
 ## 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.
+Sidebar uses generated `--bh-sidebar-*` tokens for expanded and collapsed widths, row heights, header actions, compact controls, workspace cards, tree indentation, 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.
 
 ## RTL
 
-Use `dir="rtl"` on `SidebarProvider` and `side="start"` or `side="end"` for logical placement.
+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
 
-Use clear labels for collapsed icon-only menu buttons. `SidebarToggle` announces the pressed collapse state.
-Sidebar composition parts must be rendered inside `SidebarProvider`.
+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 unmount while collapsed so keyboard users do not encounter invisible controls. Use native links through `asChild` when a row navigates, and keep button rendering for in-place actions.
 
 ## Install
 
@@ -64,8 +91,9 @@ Open the live component page or run `npx banhaten docs sidebar` to inspect sourc
 ## 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.
+- `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
@@ -75,9 +103,23 @@ 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` | `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.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`, `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`, `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-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-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-padding`, `--bh-sidebar-rail-width`, `--bh-sidebar-tree-indent-step`, `--bh-sidebar-tree-item-height`, `--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-19xl-384`, `--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`, `--shadow-button-focus` |
+| `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/slideout.md

@@ -72,6 +72,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | --- | --- |
 | `supportedExports` | `components/expanded/Slideout.tsx: Slideout` |
 | `parts` | `Slideout` |
-| `registryDependencies` | None |
+| `registryDependencies` | `button` |
+| `modes` | `desktop`, `mobile` |
+| `sizes` | `small`, `medium`, `large` |
+| `states` | `header-action`, `footer-actions`, `without-footer`, `primary-only` |
 | `tokens` | `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-muted`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-default`, `--bh-border-input`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-stroke-220`, `--bh-interactive-brand-default`, `--bh-interactive-ghost-hover`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-11xl-96`, `--bh-space-12xl-128`, `--bh-space-18xl-320`, `--bh-space-19xl-384`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-9xl-64`, `--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-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-heading-sm-medium-font-size`, `--bh-text-heading-sm-medium-font-weight`, `--bh-text-heading-sm-medium-line-height`, `--bh-text-heading-xs-medium-font-size`, `--bh-text-heading-xs-medium-line-height`, `--shadow-button-raised`, `--shadow-button-soft`, `--shadow-component-default` |
 <!-- registry-contract:end -->

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

@@ -70,8 +70,13 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/expanded/Steps.tsx: HorizontalStepItem, Steps, VerticalStepItem` |
-| `parts` | `HorizontalStepItem`, `Steps`, `VerticalStepItem` |
+| `supportedExports` | `components/expanded/Steps.tsx: HorizontalStepItem, ProgressSteps, Steps, VerticalStepItem` |
+| `parts` | `HorizontalStepItem`, `ProgressSteps`, `Steps`, `VerticalStepItem` |
 | `registryDependencies` | `button` |
+| `modes` | `steps`, `progress-steps`, `horizontal-item`, `vertical-item` |
+| `orientations` | `horizontal`, `vertical` |
+| `states` | `complete`, `active`, `todo` |
 | `tokens` | `--bh-bg-accent-purple-subtle`, `--bh-bg-inverse`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-content-default`, `--bh-content-inverse`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-steps-horizontal-width`, `--bh-steps-indicator-panel-width`, `--bh-steps-vertical-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size` |
+| `variants` | `icon`, `number` |
 <!-- registry-contract:end -->
+`ProgressSteps` covers compact bar progress and status-aware marker sequences used in setup and enrollment flows.

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

@@ -33,6 +33,19 @@ Figma references:
   filters={filters}
   pagination={{ pageSize: 10 }}
 />
+
+<TableRoot aria-label="Compact audit data">
+  <TableHeader>
+    <TableRowElement>
+      <TableHead>Activity</TableHead>
+    </TableRowElement>
+  </TableHeader>
+  <TableBody>
+    <TableRowElement>
+      <TableCell>Member invited</TableCell>
+    </TableRowElement>
+  </TableBody>
+</TableRoot>
 ```
 
 The table is composed from these parts:
@@ -43,6 +56,8 @@ The table is composed from these parts:
 - `TableCell`: the layout shell for any table item.
 - `TableItem`: the content variant rendered inside a cell.
 - `DataTable`: composed workflow shell for search, filters, actions, pagination, and table states.
+- `DataTableSurface`: ARIA table surface for bespoke CSS-grid rows while keeping the table root owned by Banhaten.
+- `TableRoot`, `TableHeader`, `TableBody`, `TableRowElement`, `TableHead`, and `TableCell`: owned semantic elements for product-specific read-only tables that do not fit the data-column API.
 
 Use semantic `<table>` markup when the table is mostly read-only data. Use an ARIA grid only when the product needs cell-level keyboard navigation. Interactive content inside cells, such as checkboxes, toggles, and actions, must remain real controls.
 
@@ -52,7 +67,7 @@ The Figma sample is `1024px` wide, but the implementation should be responsive.
 
 ```ts
 const exampleColumns = [
-  { id: "select", width: 40, kind: "selection" },
+  { id: "select", width: 42, kind: "selection" },
   { id: "project", header: "Project Name", width: "fill", sortable: true },
   { id: "leader", header: "Project Leader", width: 203, sortable: true },
   { id: "status", header: "Status", width: 147, sortable: true },
@@ -72,7 +87,7 @@ RTL tables reverse the visual column order and align cell content to the end. Th
 | Body row | `sm` | `48px` | `44px` |
 | Body row | `lg` | `56px` | `56px` |
 
-Cell padding is `8px` on the inline axis. Inline content gap is `6px`; header label and sort icon gap is `4px`. The base checkbox and action columns use fixed dimensions so hover, selected, and icon states do not shift the table.
+Cell padding is `12px` on the inline axis. The fixed `44px` action column keeps `8px` inline padding around its `28px` action button. Inline content gap is `6px`; header label and sort icon gap is `4px`. The base checkbox and action columns use fixed dimensions so hover, selected, and icon states do not shift the table.
 
 ## States
 
@@ -365,7 +380,7 @@ const filters = [
 - Progress bars are `8px` high and pill-shaped. In RTL, the filled segment grows from the right.
 - Badges are `24px` tall, pill-shaped, and use `11px / 14px` medium text.
 - Tags are `24px` tall with a 1px border and `13px / 20px` medium text.
-- Avatar-only and avatar-stack cells use 20px avatars in compact rows and 32px avatars where the `lg` item variant calls for it.
+- Avatar-with-text cells use the shared 24px avatar in `sm` rows. Avatar-only and avatar-stack cells use 20px avatars. All three use 32px avatars in `lg` rows.
 - Action buttons are fixed `28px` in `sm` rows and `32px` in `lg` rows.
 
 ## Install
@@ -376,7 +391,7 @@ npx banhaten add table
 
 ## API
 
-Supported runtime exports: `DataTable`, `Table`.
+Supported runtime exports: `DataTable`, `Table`, `DataTableSurface`, `TableBody`, `TableCell`, `TableHead`, `TableHeader`, `TableRoot`, `TableRowElement`.
 
 Use the live registry docs for the generated API table and source-backed examples.
 
@@ -404,8 +419,11 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/expanded/Table.tsx: DataTable, Table` |
-| `parts` | `Table`, `DataTable` |
+| `supportedExports` | `components/expanded/Table.tsx: DataTable, Table`, `components/table-elements.tsx: DataTableSurface, TableBody, TableCell, TableHead, TableHeader, TableRoot, TableRowElement` |
+| `parts` | `Table`, `DataTable`, `DataTableSurface`, `TableRoot`, `TableHeader`, `TableBody`, `TableRowElement`, `TableHead`, `TableCell` |
 | `registryDependencies` | `avatar`, `badge`, `button`, `checkbox`, `pagination`, `progress`, `spinner`, `tag`, `toggle`, `toolbar` |
-| `tokens` | `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-danger-subtle`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-bg-success-subtle`, `--bh-bg-warning-default`, `--bh-bg-warning-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-accent-amber-strong`, `--bh-content-accent-fuchsia-strong`, `--bh-content-brand-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-strong`, `--bh-control-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-semibold`, `--bh-icon-stroke-190`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-opacity-muted`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-2xl-14`, `--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-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-table-min-width`, `--bh-table-selection-column-min-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-regular-line-height`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-font-weight`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size` |
+| `modes` | `table`, `data-table` |
+| `sizes` | `sm`, `lg` |
+| `states` | `default`, `selected`, `disabled`, `loading`, `empty`, `error` |
+| `tokens` | `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-size-md`, `--bh-avatar-size-xs`, `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-danger-subtle`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-bg-success-subtle`, `--bh-bg-warning-default`, `--bh-bg-warning-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-accent-amber-strong`, `--bh-content-accent-fuchsia-strong`, `--bh-content-brand-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-strong`, `--bh-control-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-190`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-interactive-ghost-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-opacity-muted`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-2xl-14`, `--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-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-table-min-width`, `--bh-table-selection-column-min-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-regular-line-height`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-font-weight`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-line-height`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--shadow-component-focus-ring` |
 <!-- registry-contract:end -->

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

@@ -47,9 +47,9 @@ The component consumes semantic design-system tokens only:
 - `md` tags are `28px` tall and use body-sm medium text.
 - `lg` tags are `36px` tall and use body-md medium text.
 - Simple tags use centered text and no leading slot.
-- Dot, flag, avatar, and icon tags use a `20px` leading slot.
+- Dot, flag, avatar, and icon tags use a `20px` leading slot; the default icon glyph is `18px`.
 - Close buttons are `16px` with a `12px` icon.
-- Focused tags use a brand border plus an outside focus ring at reduced opacity.
+- Focused tags use a brand border plus a solid outside focus ring.
 - Active tags use selected/brand treatment and a stronger brand border.
 - Disabled tags use disabled background, border, and content tokens.
 - RTL uses logical inline padding and inherited direction so leading media, label, and close button mirror naturally.
@@ -90,6 +90,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `sizes` | `xs`, `md`, `lg` |
 | `states` | `default`, `active`, `disabled` |
-| `tokens` | `--bh-bg-accent-green-default`, `--bh-bg-always-dark`, `--bh-bg-always-white`, `--bh-bg-brand-subtle`, `--bh-bg-danger-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-control-default`, `--bh-control-md`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-opacity-30`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-tag-active-border-width`, `--bh-tag-focus-ring-inset`, `--bh-tag-focus-ring-width`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--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-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`, `--bh-z-raised`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-accent-green-default`, `--bh-bg-always-dark`, `--bh-bg-always-white`, `--bh-bg-brand-subtle`, `--bh-bg-danger-default`, `--bh-bg-neutral-bold`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-neutral`, `--bh-control-default`, `--bh-control-md`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-opacity-30`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-tag-active-border-width`, `--bh-tag-focus-ring-inset`, `--bh-tag-focus-ring-width`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--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-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`, `--bh-z-raised`, `--shadow-button-focus` |
 | `types` | `simple`, `dot`, `flag`, `avatar`, `icon` |
 <!-- registry-contract:end -->

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

@@ -91,5 +91,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/Timeline.tsx: Timeline, TimelineItem` |
 | `parts` | `Timeline`, `TimelineItem` |
 | `registryDependencies` | None |
-| `tokens` | `--bh-bg-brand-default`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-timeline-grid-width`, `--bh-timeline-narrow-width`, `--bh-timeline-sidebar-width` |
+| `orientations` | `vertical`, `horizontal` |
+| `states` | `finished`, `active`, `inactive` |
+| `tokens` | `--bh-bg-brand-default`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-timeline-grid-width`, `--bh-timeline-narrow-width`, `--bh-timeline-sidebar-width`, `--shadow-component-focus-ring` |
+| `variants` | `default`, `icon` |
 <!-- registry-contract:end -->

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

@@ -92,5 +92,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `optional handle icons`, `leading label`, `trailing label`, `supporting text` |
 | `sizes` | `sm`, `md` |
 | `states` | `unchecked`, `checked`, `hover`, `focused`, `disabled` |
-| `tokens` | `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-light`, `--bh-content-subtle`, `--bh-icon-stroke-250`, `--bh-interactive-switch-active`, `--bh-interactive-switch-active-disabled`, `--bh-interactive-switch-active-hover`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-interactive-switch-hover`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-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-toggle-handle-size`, `--bh-toggle-icon-size-md`, `--bh-toggle-icon-size-sm`, `--bh-toggle-offset`, `--shadow-component-default`, `--shadow-social-button-focus-ring` |
+| `tokens` | `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-light`, `--bh-content-subtle`, `--bh-icon-stroke-250`, `--bh-interactive-switch-active`, `--bh-interactive-switch-active-disabled`, `--bh-interactive-switch-active-hover`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-interactive-switch-hover`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-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-toggle-handle-size`, `--bh-toggle-icon-size-md`, `--bh-toggle-icon-size-sm`, `--bh-toggle-offset`, `--shadow-md`, `--shadow-social-button-focus-ring` |
 <!-- registry-contract:end -->

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

@@ -101,5 +101,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `densities` | `compact`, `default`, `comfortable` |
 | `layouts` | `inline`, `split`, `stack`, `wrap` |
 | `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
-| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-label-padding-x`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-radius-full`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-trigger-padding-x`, `--bh-select-width`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-soft`, `--shadow-input`, `--shadow-input-focus-ring`, `--shadow-select-trigger` |
+| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-icon-slot-size`, `--bh-button-label-padding-x`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-radius-full`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-trigger-padding-x`, `--bh-select-width`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-soft`, `--shadow-input`, `--shadow-input-focus-ring`, `--shadow-select-trigger` |
 <!-- registry-contract:end -->

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

@@ -102,6 +102,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `pointerPositions` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-right`, `center-left`, `none` |
 | `sizes` | `sm`, `lg` |
-| `tokens` | `--bh-bg-always-dark`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-inverse-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-family`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--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-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-tooltip-bg`, `--bh-tooltip-border`, `--bh-tooltip-close-fg`, `--bh-tooltip-close-icon-size`, `--bh-tooltip-close-size`, `--bh-tooltip-fg`, `--bh-tooltip-lg-padding`, `--bh-tooltip-lg-radius`, `--bh-tooltip-lg-width`, `--bh-tooltip-max-width`, `--bh-tooltip-pointer-border-depth`, `--bh-tooltip-pointer-border-half-width`, `--bh-tooltip-pointer-border-offset`, `--bh-tooltip-pointer-depth`, `--bh-tooltip-pointer-half-width`, `--bh-tooltip-pointer-inline-offset`, `--bh-tooltip-pointer-offset`, `--bh-tooltip-pointer-width`, `--bh-tooltip-shadow`, `--bh-tooltip-shortcut-bg`, `--bh-tooltip-shortcut-border`, `--bh-tooltip-shortcut-height`, `--bh-tooltip-shortcut-min-width`, `--bh-tooltip-sm-padding-x`, `--bh-tooltip-sm-padding-y`, `--bh-tooltip-sm-radius`, `--bh-z-overlay`, `--bh-z-raised`, `--shadow-button-focus`, `--shadow-component-default` |
+| `tokens` | `--bh-bg-always-dark`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-inverse-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-family`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--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-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-tooltip-bg`, `--bh-tooltip-border`, `--bh-tooltip-close-fg`, `--bh-tooltip-close-icon-size`, `--bh-tooltip-close-size`, `--bh-tooltip-fg`, `--bh-tooltip-lg-padding`, `--bh-tooltip-lg-radius`, `--bh-tooltip-lg-width`, `--bh-tooltip-max-width`, `--bh-tooltip-pointer-border-depth`, `--bh-tooltip-pointer-border-half-width`, `--bh-tooltip-pointer-border-offset`, `--bh-tooltip-pointer-depth`, `--bh-tooltip-pointer-half-width`, `--bh-tooltip-pointer-inline-offset`, `--bh-tooltip-pointer-offset`, `--bh-tooltip-pointer-width`, `--bh-tooltip-shadow`, `--bh-tooltip-shortcut-bg`, `--bh-tooltip-shortcut-border`, `--bh-tooltip-shortcut-height`, `--bh-tooltip-shortcut-min-width`, `--bh-tooltip-sm-padding-x`, `--bh-tooltip-sm-padding-y`, `--bh-tooltip-sm-radius`, `--bh-z-overlay`, `--bh-z-raised`, `--shadow-button-focus`, `--shadow-lg` |
 | `variants` | `dark`, `default` |
 <!-- registry-contract:end -->

package/docs/design-system/density-and-elevation.md

@@ -38,7 +38,28 @@ not silently resize navigation, cards, typography, or unrelated layout spacing.
 
 Elevation uses two layers:
 
-- General steps: `--shadow-xs` through `--shadow-xl`.
+- General steps: `--shadow-xs` through `--shadow-3xl`.
 - Semantic component aliases: `--shadow-component-*`, focus/danger rings, menus, controls, and component-specific aliases.
 
-Components consume the semantic alias that describes purpose rather than selecting a visual step directly. The Shadows documentation groups aliases under their canonical effect and distinguishes surface elevation, control strokes, focus rings, overlay elevation, and intentional `none` values.
+The seven general steps mirror the current Figma `elevation/01` through
+`elevation/07` effect styles in [Shadow tests → With Variables](https://www.figma.com/design/LVAWtr5A5oEcAvsBmk6vdt/Banhaten-Design-system-3.0?node-id=6436-13190).
+The geometry is shared across modes. Figma's bound shadow color variables make
+the dark-mode drops, rings, and highlights stronger, so Banhaten publishes a
+separate exact recipe for each mode.
+
+| CSS step | Figma style | Current component roles |
+| --- | --- | --- |
+| `xs` | `elevation/01` | Flat surfaces with an ambient ring only |
+| `sm` | `elevation/02` | Subtle lift for inner cards, inset panels, and compact raised details |
+| `md` | `elevation/03` | Cards, surfaces, slider thumbs, and toggle handles |
+| `lg` | `elevation/04` | Menus, select menus, popovers, tooltips, and date surfaces |
+| `xl` | `elevation/05` | Sticky and floating surfaces, including floating banners |
+| `2xl` | `elevation/06` | Modals and dialogs |
+| `3xl` | `elevation/07` | Full-overlay surfaces that require maximum depth |
+
+Components consume the semantic alias that describes purpose rather than
+selecting a visual step directly. Focus rings, inset borders, and the Figma
+`Shadow/component/*` control effects remain separate from surface elevation.
+The Shadows documentation groups aliases under their canonical effect and
+distinguishes surface elevation, control strokes, focus rings, overlay
+elevation, and intentional `none` values.

package/docs/design-system/gap-promotion-report.md

@@ -2,7 +2,7 @@
 
 This file is generated from background scenario gap metadata. A candidate appears when the same normalized need occurs in at least three distinct backgrounds. Heuristics cover common shells, navigation, tables, steps, composers, timelines, assets, and elevation; use `promotionKey` on a gap when an explicit cross-background grouping is more accurate.
 
-Scanned 194 gaps across 36 backgrounds. Found 8 promotion candidates at the 3-background threshold.
+Scanned 100 gaps across 38 backgrounds. Found 4 promotion candidates at the 3-background threshold.
 
 ## Application/workspace shell
 
@@ -58,46 +58,6 @@ Backgrounds: `ai-growth-marketing`, `ai-node-detail`, `bauhow-room-planning`, `c
 | `shipment-list` | carrier brand mark (`shipment-carrier-brand-mark`) | icon asset | approximation |
 | `sku-management` | product and assistant icon set (`sku-product-icons`) | icon asset | approximation |
 
-## Sidebar navigation
-
-Key: `sidebar-navigation` · 11 backgrounds
-
-Backgrounds: `acme-finance-advisor`, `ai-growth-marketing`, `audit-log`, `bauhow-room-planning`, `data-source-browser`, `debt-payoff`, `marcohr-people`, `people-add-member`, `shipment-list`, `sku-management`, `stripe-demo-account`
-
-| Background | Gap | Kind | Status |
-| --- | --- | --- | --- |
-| `acme-finance-advisor` | compact app sidebar navigation (`acme-sidebar-navigation`) | component | missing |
-| `ai-growth-marketing` | report sidebar navigation (`report-sidebar-navigation`) | component | missing |
-| `audit-log` | audit sidebar navigation (`audit-sidebar-navigation`) | component | missing |
-| `bauhow-room-planning` | planning sidebar navigation (`room-planning-sidebar-navigation`) | component | missing |
-| `data-source-browser` | sidebar navigation with pinned list (`sidebar-navigation-with-pinned-list`) | component | missing |
-| `debt-payoff` | planning sidebar navigation (`planning-sidebar-navigation`) | component | missing |
-| `marcohr-people` | HR sidebar navigation (`marcohr-sidebar-navigation`) | component | missing |
-| `people-add-member` | HR sidebar navigation (`people-sidebar-navigation`) | component | missing |
-| `shipment-list` | shipment sidebar navigation (`shipment-sidebar-navigation`) | component | missing |
-| `sku-management` | cropped app sidebar navigation (`sku-sidebar-navigation`) | component | missing |
-| `stripe-demo-account` | payments sidebar navigation (`payments-sidebar-navigation`) | component | missing |
-
-## Data table pattern
-
-Key: `data-table-pattern` · 10 backgrounds
-
-Backgrounds: `audit-log`, `debt-payoff`, `inference-providers`, `marcohr-people`, `people-add-member`, `recent-orders`, `school-assignments`, `share-of-voice`, `sku-management`, `stripe-demo-account`
-
-| Background | Gap | Kind | Status |
-| --- | --- | --- | --- |
-| `audit-log` | audit activity table (`audit-activity-table`) | component | missing |
-| `debt-payoff` | debt table and pagination (`debt-table-and-pagination`) | component | approximation |
-| `inference-providers` | expandable provider configuration table (`expandable-provider-table`) | component | missing |
-| `marcohr-people` | employee policy table (`marcohr-employee-table`) | component | approximation |
-| `people-add-member` | people table with status rows (`people-table-and-status-rows`) | component | approximation |
-| `recent-orders` | orders table controls and rows (`orders-table-region`) | component | approximation |
-| `school-assignments` | assignments table (`assignments-table`) | component | missing |
-| `share-of-voice` | analytics table density (`share-of-voice-analytics-table`) | component | approximation |
-| `sku-management` | SKU data table and pagination (`sku-data-table`) | component | approximation |
-| `stripe-demo-account` | metric table cards (`metric-table-cards`) | component | approximation |
-| `stripe-demo-account` | sales tabs and table (`sales-tabs-and-table`) | component | approximation |
-
 ## Elevation/blur semantic effects
 
 Key: `elevation-effects` · 10 backgrounds
@@ -135,32 +95,6 @@ Backgrounds: `delivery-tracking`, `investor-profile`, `mcp-settings`, `profile-m
 | `school-assignments` | teacher avatar (`teacher-avatar`) | image asset | missing |
 | `stripe-demo-account` | Stripe mark and account avatar (`stripe-brand-and-avatar-assets`) | image asset | approximation |
 
-## Progress/step indicator
-
-Key: `progress-step-indicator` · 5 backgrounds
-
-Backgrounds: `accounting-workspace-setup`, `benefits-enrollment`, `mcp-settings`, `quran-audio-add-employee`, `refund-simulation`
-
-| Background | Gap | Kind | Status |
-| --- | --- | --- | --- |
-| `accounting-workspace-setup` | step progress indicator (`setup-progress-indicator`) | component | approximation |
-| `benefits-enrollment` | enrollment progress header (`enrollment-progress-header`) | component | missing |
-| `mcp-settings` | numbered setup steps (`numbered-setup-steps`) | component | missing |
-| `quran-audio-add-employee` | three-step employee progress indicator (`quran-audio-progress-stepper`) | component | approximation |
-| `refund-simulation` | refund progress timeline (`refund-progress-timeline`) | component | missing |
-
-## Composer pattern
-
-Key: `composer-pattern` · 3 backgrounds
-
-Backgrounds: `acme-finance-advisor`, `email-compose`, `order-shipment-timeline`
-
-| Background | Gap | Kind | Status |
-| --- | --- | --- | --- |
-| `acme-finance-advisor` | advisor prompt composer (`acme-advisor-composer`) | component | approximation |
-| `email-compose` | compose modal shell (`compose-modal-shell`) | layout/composition pattern | missing |
-| `order-shipment-timeline` | note composer (`note-composer`) | component | missing |
-
 ## Review rule
 
 A report entry is a prioritization signal, not automatic authorization to add a primitive. Review the mapped backgrounds, define the smallest stable API, migrate at least one real background, and remove the resolved gap metadata only after behavior, RTL, accessibility, and visual checks pass.

package/docs/design-system/icons.md

@@ -40,13 +40,18 @@ Keep `Simple Icons` as a separate brand-logo source. It should not be the primar
 
 ## Decision Criteria
 
-- Button icon clarity at 16px and 20px.
+- Default UI glyph clarity at 18px, with the glyph centered in a 20px layout slot.
+- Small-control icon clarity at 16px without promoting those intentionally compact glyphs to the default size.
 - Menu, dropdown, and table icon legibility in dense rows.
 - Visual match with `default`, `rounded`, and `sharp` appearances.
 - Variant usefulness: filled states, two-tone states, sharp geometry, or rounded geometry.
 - Coverage for navigation, data, files, users, settings, alerts, billing, integrations, and brand logos.
 - Licensing and attribution obligations. Keep source license notices in the project when redistributing SVG/source files.
 
+## Default Geometry Contract
+
+Default UI icons use `--bh-icon-size-default` (`18px`) inside `--bh-icon-slot-size-default` (`20px`). The resulting `--bh-icon-slot-inset-default` is `1px` on each side. Components must preserve that slot so switching from the former 20px glyph does not change alignment, gaps, or control dimensions. Intentional 12px, 16px, 24px, brand-logo, avatar, spinner, and control-indicator sizes remain component-specific.
+
 ## Sources
 
 - Google Material Icons repository: https://github.com/google/material-design-icons

package/docs/design-system/installation.md

@@ -53,7 +53,7 @@ Without Vite, the CLI installs Tailwind and writes the configured global stylesh
 The generated stylesheet imports Inter weights 400–700 and IBM Plex Sans Arabic weights 400–700. Set document language and direction at the application boundary:
 
 ```tsx
-<html lang="ar" dir="rtl" data-theme="blue" data-radius="default">
+<html lang="ar" dir="rtl" data-theme="gray" data-radius="default">
 ```
 
 Wrap server-rendered component trees in `DirectionProvider` when request data already determines the direction; this keeps the first server and client snapshots identical. It is also the boundary for nested surfaces that differ from the document. Without it, components hydrate from a stable LTR snapshot and then synchronize from the document through one shared observer.