banhaten 0.1.2 → 0.2.0

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

@@ -0,0 +1,72 @@
+# Radio Group
+
+Radio Group is the native-input single-choice primitive. It includes `Radio`, `RadioField`, `RadioGroup`, and `RadioGroupItem` for grouped labels, descriptions, errors, disabled state, controlled or uncontrolled values, and horizontal or vertical layout.
+
+## API
+
+```tsx
+<RadioGroup
+  label="Billing interval"
+  defaultValue="monthly"
+  orientation="vertical"
+>
+  <RadioGroupItem value="monthly" label="Monthly" />
+  <RadioGroupItem value="annual" label="Annual" />
+</RadioGroup>
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | controlled or uncontrolled value |
+| `orientation` | `vertical`, `horizontal` |
+| `state` | `default`, `error`, `disabled` |
+| `label`, `description`, `errorMessage` | `ReactNode` |
+| `controlPosition` | `start`, `end` on field/item rows |
+
+## Token Contract
+
+Radio Group uses Banhaten radio control, field gap, group spacing, text, helper, error, disabled, border, and focus tokens.
+
+## RTL
+
+`RadioField` and `RadioGroupItem` use logical start/end control placement. Labels, descriptions, and error text use `dir="auto"` and tokenized typography.
+
+## Accessibility
+
+The group uses `fieldset`, shared native radio names, label wrapping, and platform keyboard behavior. Provide visible error text when the group is invalid.
+
+## Install
+
+```bash
+npx banhaten add radio-group
+```
+
+## Examples
+
+Primary registry example: `examples/radio-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs radio-group` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: RadioField and RadioGroupItem use start/end control placement so the radio mirrors correctly in RTL.
+- `textDirection`: Group labels, item labels, descriptions, and error text use dir="auto" with tokenized body typography.
+- `semantics`: Uses native radio inputs with a shared group name, fieldset grouping, and label wrapping for platform keyboard and form behavior.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/radio-group.tsx: Radio, RadioField, RadioGroup, RadioGroupItem, radioControl, radioField, radioGroupItems, radioGroupRoot, radioRoot` |
+| `parts` | `Radio`, `RadioField`, `RadioGroup`, `RadioGroupItem` |
+| `registryDependencies` | None |
+| `controlPositions` | `start`, `end` |
+| `orientations` | `vertical`, `horizontal` |
+| `states` | `default`, `error`, `disabled` |
+| `tokens` | `--bh-bg-always-white`, `--bh-bg-default`, `--bh-bg-disabled`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-interactive-radiobutton-default`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radio-control-border`, `--bh-radio-group-message-max-width`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--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-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-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-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-raised`, `--shadow-button-focus`, `--shadow-radio-control` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,57 @@
+# Resizable
+
+Resizable wraps `react-resizable-panels` for split panes and workbench layouts.
+
+## API
+
+```tsx
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={30}>Sidebar</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={70}>Content</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## Token Contract
+
+Resizable uses Banhaten border, focus, raised surface, radius, and icon sizing tokens.
+
+## RTL
+
+Panel order follows DOM order. Use logical layout around the panel group for RTL shells.
+
+## Accessibility
+
+`react-resizable-panels` provides keyboard-adjustable resize handles.
+
+## Install
+
+```bash
+npx banhaten add resizable
+```
+
+## Examples
+
+Primary registry example: `examples/resizable-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs resizable` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Panel order follows DOM order; use logical shell layout for RTL workspaces.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/resizable.tsx: ResizableHandle, ResizablePanel, ResizablePanelGroup` |
+| `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` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,60 @@
+# Scroll Area
+
+Scroll Area wraps Radix ScrollArea with tokenized viewport, scrollbar, thumb, and corner styling.
+
+## API
+
+```tsx
+<ScrollArea className="h-48">
+  <div>Scrollable content</div>
+</ScrollArea>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `ScrollArea` | root and viewport |
+| `ScrollBar` | vertical or horizontal scrollbar |
+
+## Token Contract
+
+Scroll Area uses Banhaten radius, border, and neutral thumb tokens.
+
+## RTL
+
+Scroll Area inherits direction from its parent. Use logical padding inside the viewport content.
+
+## Accessibility
+
+Use Scroll Area for visual scrollbars around already accessible content, not for hiding essential controls.
+
+## Install
+
+```bash
+npx banhaten add scroll-area
+```
+
+## Examples
+
+Primary registry example: `examples/scroll-area-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs scroll-area` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Viewport content should use logical padding so scrollable regions mirror with document direction.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/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` |
+<!-- registry-contract:end -->

package/docs/design-system/components/segmented-control.md

@@ -0,0 +1,71 @@
+# Segmented Control
+
+Segmented Control presents a small set of related choices on one connected, content-width surface. It is the preferred primitive for view, density, period, and numeric display choices such as “Cards per row”.
+
+Use Select or Radio Group when labels are long or the option set is large. Use Button Group when the items are actions rather than values.
+
+## API
+
+Give the group an accessible name, give every item a stable value, and use `SegmentedControlLabel` only for non-interactive context.
+
+```tsx
+<SegmentedControl
+  aria-label="Cards per row"
+  density="default"
+  defaultValue="4"
+>
+  <SegmentedControlLabel>Cards / row</SegmentedControlLabel>
+  <SegmentedControlItem value="3">3</SegmentedControlItem>
+  <SegmentedControlItem value="4">4</SegmentedControlItem>
+  <SegmentedControlItem value="5">5</SegmentedControlItem>
+  <SegmentedControlItem value="6">6</SegmentedControlItem>
+</SegmentedControl>
+```
+
+The default density is `default` (36px). Use `compact` for 32px control rows and `comfortable` for 40px controls. Keep adjacent controls on the same density contract.
+
+## Install
+
+```bash
+npx banhaten add segmented-control
+```
+
+## Examples
+
+Primary registry example: `examples/segmented-control-demo.tsx`.
+
+The results-toolbar recipe demonstrates the labeled cards-per-row composition alongside a Select action.
+
+## Token Contract
+
+Segmented Control reuses Button Group surface, divider, interaction, typography, and density tokens. Do not replace its height, padding, radius, color, or shadow with local literal values.
+
+Covered source files: `components/segmented-control.tsx` and its `button-group` registry dependency.
+
+## RTL Rules
+
+- The group inherits document direction.
+- Content-width items and logical dividers follow inherited direction without alternate markup.
+- Horizontal arrow-key navigation resolves the computed direction through the underlying Toggle Group.
+
+## Accessibility
+
+Provide `aria-label` on every Segmented Control. Items expose pressed state through the underlying Toggle Group, support single or multiple selection, and retain Home, End, and direction-aware arrow-key navigation. The label segment is descriptive and never focusable.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/segmented-control.tsx: SegmentedControl, SegmentedControlItem, SegmentedControlLabel` |
+| `parts` | `SegmentedControl`, `SegmentedControlItem`, `SegmentedControlLabel` |
+| `registryDependencies` | `button-group` |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Uses the shared 32px, 36px, or 40px control height contract.` |
+| `props.type` | `"single" \| "multiple"; default "single"; Controls whether one or multiple item values may be active.` |
+| `props.aria-label` | `string; default null; Required accessible name for the complete selection group.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `selectionTypes` | `single`, `multiple` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,87 @@
+# Select
+
+Select is a Radix Select-backed field and menu system. It supports default and soft trigger styles, md/lg sizing, error, filled and disabled states, menu surfaces, checkbox or check selection, and item media for text, icons, avatars, companies, payment methods, and status dots.
+
+## API
+
+```tsx
+<Select label="Country" placeholder="Choose country">
+  <SelectMenuItem value="eg">Egypt</SelectMenuItem>
+  <SelectMenuItem value="sa">Saudi Arabia</SelectMenuItem>
+</Select>
+```
+
+| Prop | Type / values | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `default`, `soft` | `default` | Selects the trigger surface. |
+| `size` | `lg`, `md` | `lg` | Selects the trigger height. |
+| `state` | `default`, `filled`, `error`, `disabled` | `default` | Selects the visual state. |
+| `itemType` | `default`, `icon`, `avatar`, `company`, `payment`, `dot` | `default` | Selects menu-item media. |
+| `selectionType` | `default`, `checkbox` | `default` | Selects the menu-item selection indicator. |
+| `hasInformationIcon` | `boolean` | `false` | Shows an information icon beside the field label. |
+| `hasLeadingIcon` | `boolean` | `false` | Set true to show the default user icon. |
+| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the leading slot; false always removes it. |
+| `hasTrailingIcon` | `boolean` | `false` | Set true to show the default information icon inside the trigger. |
+| `trailingIcon` | `ReactNode \| false` | `null` | A node enables the trailing slot; false always removes it. |
+| `expandIcon` | `ReactNode \| false` | `chevron-down` | Replaces the expand icon, or removes it when false. |
+
+## Migration
+
+Select now renders only its expand chevron when optional trigger-icon props are omitted. Add `hasLeadingIcon` or `hasTrailingIcon` to retain the previous default user or information icon. A supplied icon enables its slot, while explicit `false` always removes it.
+
+## Token Contract
+
+Select consumes Banhaten field, trigger, menu, item, checkbox, status, avatar, payment, typography, spacing, border, radius, shadow, and focus tokens.
+
+## RTL
+
+Values, labels, helper text, and menu item text use `text-start` and `dir="auto"`. Trigger icons and selected checks use logical placement so they mirror in RTL.
+
+## Accessibility
+
+Radix provides listbox semantics, focus management, typeahead, selection state, and keyboard behavior. Use visible helper or error text for validation states.
+
+## Install
+
+```bash
+npx banhaten add select
+```
+
+## Examples
+
+Primary registry example: `examples/select-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs select` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" for values, labels, helper text, and menu item text.
+- `spacing`: Uses logical padding, start/end positioning, and inherited flex direction so trigger icons and selected checks mirror in RTL.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/select-content.tsx: SelectIcon, SelectItemAvatar, SelectItemCompanyLogo, SelectItemPaymentIcon, SelectItemStatusDot, getDefaultSelectItemMedia`, `components/select.tsx: Select, SelectCheckboxIndicator, SelectHelperText, SelectItemAvatar, SelectItemCompanyLogo, SelectItemPaymentIcon, SelectItemStatusDot, SelectLabel, SelectMenu, SelectMenuItem, SelectRoot, SelectTrigger, selectMenu, selectMenuItem, selectRoot, selectTrigger` |
+| `parts` | `Select`, `SelectRoot`, `SelectLabel`, `SelectTrigger`, `SelectHelperText`, `SelectMenu`, `SelectMenuItem`, `SelectCheckboxIndicator`, `SelectItemAvatar`, `SelectItemCompanyLogo`, `SelectItemPaymentIcon`, `SelectItemStatusDot` |
+| `registryDependencies` | None |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Preferred cross-component sizing contract. Overrides the legacy size prop with 32px, 36px, or 40px control heights.` |
+| `props.hasInformationIcon` | `boolean; default false; Shows an information icon beside the field label.` |
+| `props.hasLeadingIcon` | `boolean; default false; Shows the default user leading icon when no leadingIcon is supplied.` |
+| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom leading icon; false always removes the leading slot.` |
+| `props.hasTrailingIcon` | `boolean; default false; Shows the default information trailing icon when no trailingIcon is supplied.` |
+| `props.trailingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom trailing icon; false always removes the trailing slot.` |
+| `props.expandIcon` | `React.ReactNode \| false; default "chevron-down"; Uses the default expand chevron when omitted, accepts a replacement node, and hides the slot when false.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `itemTypes` | `default`, `icon`, `avatar`, `company`, `payment`, `dot` |
+| `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` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

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

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

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

@@ -0,0 +1,83 @@
+# Sidebar
+
+Sidebar is a composable app navigation surface with collapse state, grouped menu items, logical start/end placement, and generated `--bh-sidebar-*` tokens.
+
+## API
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>
+      Workspace
+      <SidebarToggle />
+    </SidebarHeader>
+    <SidebarBody>
+      <SidebarGroup>
+        <SidebarGroupLabel>Main</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton active>Overview</SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarBody>
+  </Sidebar>
+</SidebarProvider>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `SidebarProvider` | controlled or uncontrolled collapsed state |
+| `Sidebar` | navigation surface |
+| `SidebarHeader`, `SidebarBody`, `SidebarFooter` | layout regions |
+| `SidebarGroup`, `SidebarGroupLabel` | grouped navigation |
+| `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton` | menu structure |
+| `SidebarToggle`, `SidebarRail` | collapse controls |
+| `SidebarTrigger` | shadcn-compatible alias for `SidebarToggle` |
+| `SidebarInset` | main content wrapper for app-shell layouts |
+
+## Token Contract
+
+Sidebar uses generated `--bh-sidebar-width`, `--bh-sidebar-width-collapsed`, `--bh-sidebar-item-height`, `--bh-sidebar-padding`, `--bh-sidebar-bg`, `--bh-sidebar-border`, and `--shadow-sidebar` tokens.
+
+## RTL
+
+Use `dir="rtl"` on `SidebarProvider` and `side="start"` or `side="end"` for logical placement.
+
+## Accessibility
+
+Use clear labels for collapsed icon-only menu buttons. `SidebarToggle` announces the pressed collapse state.
+Sidebar composition parts must be rendered inside `SidebarProvider`.
+
+## Install
+
+```bash
+npx banhaten add sidebar
+```
+
+## Examples
+
+Primary registry example: `examples/sidebar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs sidebar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: Use side="start" or side="end" with dir on SidebarProvider for logical placement.
+- `spacing`: Menu item icon and label spacing uses flex gaps and logical text alignment.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/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` |
+<!-- registry-contract:end -->

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

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