banhaten 0.1.2 → 0.2.0

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

@@ -0,0 +1,84 @@
+# Input
+
+Input is the text-entry field primitive for forms, filters, search, numeric entry, tags, shortcuts, add-ons, and action-adorned fields. It supports default and soft variants, md/lg sizing, helper and error text, and RTL-safe slot placement.
+
+## API
+
+```tsx
+<Input label="Email" placeholder="name@example.com" />
+<Input state="error" label="Amount" message="Enter a valid amount" />
+```
+
+| Prop | Type / values | Default | Notes |
+| --- | --- | --- | --- |
+| `kind` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` | `default` | Selects the input composition. |
+| `variant` | `default`, `soft` | `default` | Selects the input surface. |
+| `size` | `md`, `lg` | `lg` | Selects the control height. |
+| `state` | `default`, `filled`, `error`, `disabled` | `default` | Selects the visual state. |
+| `label`, `message` | `ReactNode` | `null` | Their presence enables the corresponding text rows unless explicitly disabled. |
+| `hasLeadingIcon` | `boolean` | `false` | Set true to show the default at-sign icon. |
+| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the leading slot; false always removes it. |
+| `hasInformationIcon` | `boolean` | `false` | Set true to show the default information icon. |
+| `trailingIcon` | `ReactNode \| false` | `null` | A node enables the trailing slot; false always removes it. |
+
+## Migration
+
+Input no longer adds the default at-sign or information icon when their props are omitted. Add `hasLeadingIcon` or `hasInformationIcon` to retain either previous default, or supply a custom `leadingIcon` or `trailingIcon` to enable that slot. Explicit `false` always removes the corresponding slot.
+
+## Token Contract
+
+Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Add-on and button segments should use logical borders and shared field tokens.
+
+## RTL
+
+Input uses logical start/end slots and `text-start`. Labels, values, add-ons, tags, and helper text use `dir="auto"` where string copy is rendered.
+
+## Accessibility
+
+Connect labels and helper/error text through the component props when possible. Use `state="error"` with visible error copy instead of relying only on red borders.
+
+## Install
+
+```bash
+npx banhaten add input
+```
+
+## Examples
+
+Primary registry example: `examples/input-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English labels, values, add-ons, tags, and helper text align naturally.
+- `spacing`: Uses logical start/end borders and inherited direction so leading and trailing segments 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/input-content.ts: getInputDefaultValue, getInputHelperText, getInputPlaceholder, getInputTags, inputCopy`, `components/input.tsx: Input, inputContent, inputControl, inputRoot, inputSurface` |
+| `parts` | `Input` |
+| `registryDependencies` | `kbd` |
+| `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.hasLeadingIcon` | `boolean; default false; Deprecated compatibility alias for showAtSign.` |
+| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom leading icon; false always removes the leading slot.` |
+| `props.hasInformationIcon` | `boolean; default false; Deprecated compatibility alias for showInfo.` |
+| `props.trailingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom trailing icon; false always removes the information slot.` |
+| `props.showAtSign` | `boolean; default false; Explicitly shows the semantic at-sign affordance when no leadingIcon is supplied.` |
+| `props.showInfo` | `boolean; default false; Explicitly shows the semantic information affordance when no trailingIcon is supplied.` |
+| `props.shortcutKeys` | `readonly string[]; default "Mod,K"; Renders the shortcut kind with shared Kbd keycaps. Use Mod for a platform-aware primary modifier.` |
+| `props.shortcut` | `React.ReactNode; default null; Deprecated single-keycap escape hatch. Prefer shortcutKeys for a structured shortcut chord.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `kinds` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` |
+| `sizes` | `md`, `lg`, `comfortable` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-icon-stroke-225`, `--bh-input-border`, `--bh-input-chevron-size`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-helper-gap`, `--bh-input-icon-size`, `--bh-input-info-icon-size`, `--bh-input-inline-gap`, `--bh-input-inline-tags-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-segment-gap`, `--bh-input-segment-padding-x`, `--bh-input-stepper-icon-size`, `--bh-input-stepper-width`, `--bh-input-tag-height`, `--bh-input-tag-padding-x`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-interactive-input-soft-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--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-raised`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-disabled-overlay`, `--shadow-input-focus-overlay`, `--shadow-input-focus-ring`, `--shadow-input-focus-surface`, `--shadow-input-overlay`, `--shadow-input-surface` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,72 @@
+# Item
+
+Item is Banhaten’s composable row primitive for lists, settings, search results, files, and compact summaries. It keeps media, copy, and actions on one logical layout contract without embedding product behavior or placeholder content.
+
+## API
+
+```tsx
+<ItemGroup aria-label="Recent documents">
+  <Item role="listitem" variant="outline">
+    <ItemMedia><FileTextIcon aria-hidden="true" /></ItemMedia>
+    <ItemContent>
+      <ItemTitle>Launch checklist</ItemTitle>
+      <ItemDescription>Updated five minutes ago</ItemDescription>
+    </ItemContent>
+    <ItemActions>{/* real controls */}</ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+Use `asChild` when the whole row should be a native link or button. Interactive controls inside `ItemActions` must retain their own accessible names.
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `default`, `muted`, `outline` |
+| `size` | `sm`, `md`, `lg` |
+| `disabled` | `boolean` |
+| `ItemMedia variant` | `icon`, `avatar`, `image` |
+
+## Install
+
+```bash
+npx banhaten add item
+```
+
+## Accessibility
+
+`ItemGroup` defaults to `role="list"`; give rows `role="listitem"` when using the default non-semantic `div`. Prefer native anchors or buttons through `asChild` for interactive rows. Disabled styling maps to `aria-disabled` and does not invent click behavior.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: media, content, and actions follow logical flex order.
+- `textDirection`: title and description use `dir="auto"`.
+
+## Token Contract
+
+Every dimension, surface, color, radius, type style, focus treatment, and transition resolves through Banhaten tokens. Covered source file: `components/item.tsx`.
+
+## Examples
+
+Primary registry example: `examples/item-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs item` to inspect source files, install command, and examples.
+
+<!-- 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/item.tsx: Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemSeparator, ItemTitle, itemVariants` |
+| `parts` | `Item`, `ItemGroup`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, `ItemSeparator` |
+| `registryDependencies` | None |
+| `features` | `media slot`, `content slots`, `action slot`, `asChild composition`, `disabled semantics` |
+| `sizes` | `sm`, `md`, `lg` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-interactive-ghost-hover`, `--bh-item-actions-gap`, `--bh-item-content-gap`, `--bh-item-gap`, `--bh-item-group-gap`, `--bh-item-icon-size`, `--bh-item-media-radius`, `--bh-item-media-size`, `--bh-item-min-height-lg`, `--bh-item-min-height-md`, `--bh-item-min-height-sm`, `--bh-item-padding-x`, `--bh-item-padding-y`, `--bh-item-radius`, `--bh-radius-full`, `--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-button-focus` |
+| `variants` | `default`, `muted`, `outline` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,62 @@
+# Kbd
+
+Kbd renders compact keyboard hints for shortcuts, command rows, and form help text.
+
+## API
+
+```tsx
+<Kbd>⌘</Kbd>
+<Kbd>K</Kbd>
+<Kbd size="md">Shift</Kbd>
+```
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `md` |
+
+## Token Contract
+
+Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button shadow tokens.
+
+## RTL
+
+Kbd is direction-neutral. Use surrounding text direction for shortcut descriptions.
+
+## Accessibility
+
+Use Kbd as supporting text, not as the only label for an action.
+
+## Install
+
+```bash
+npx banhaten add kbd
+```
+
+## Examples
+
+Primary registry example: `examples/kbd-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs kbd` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `semantics`: Kbd is direction-neutral and should be paired with surrounding text labels.
+
+<!-- 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/kbd.tsx: Kbd, KbdShortcut, kbdVariants` |
+| `parts` | `Kbd`, `KbdShortcut` |
+| `registryDependencies` | None |
+| `props.keys` | `readonly string[]; default null; Required by KbdShortcut. Each entry renders as its own keycap; use Mod for the platform primary modifier.` |
+| `props.platform` | `"auto" \| "mac" \| "windows" \| "linux"; default "auto"; Resolves Mod to Command on Apple platforms and Control elsewhere.` |
+| `props.disabled` | `boolean; default false; Uses disabled border, surface, content, and shadow tokens for shortcuts inside disabled controls.` |
+| `sizes` | `sm`, `md` |
+| `tokens` | `--bh-border-default`, `--bh-border-disabled`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-font-family`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-radius-md-6`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-soft` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,64 @@
+# Label
+
+Label renders accessible control labels with Banhaten typography, required markers, optional text, tone variants, and RTL-safe copy. It is backed by Radix Label.
+
+## API
+
+```tsx
+<Label htmlFor="email" required>
+  Email address
+</Label>
+```
+
+| Prop | Values |
+| --- | --- |
+| `htmlFor` | target control id |
+| `tone` | `default`, `subtle`, `danger` |
+| `required` | `boolean` |
+| `optionalText` | `ReactNode` |
+
+## Token Contract
+
+Label consumes Banhaten body-sm, body-xs, content, danger, spacing, and disabled-state tokens.
+
+## RTL
+
+Label uses logical inline spacing and `dir="auto"` for label and optional text.
+
+## Accessibility
+
+Use `htmlFor` for native controls. For complete form rows with description and error text, use `Field`.
+
+## Install
+
+```bash
+npx banhaten add label
+```
+
+## Examples
+
+Primary registry example: `examples/label-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs label` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Label and optional text use dir="auto" so Arabic and English labels resolve naturally.
+- `spacing`: Uses logical inline spacing between label text, required marker, and optional text.
+
+<!-- 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/label.tsx: Label, labelVariants` |
+| `parts` | `Label` |
+| `registryDependencies` | None |
+| `features` | `required marker`, `optional text`, `disabled styling` |
+| `tokens` | `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--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-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height` |
+| `tones` | `default`, `subtle`, `danger` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,76 @@
+# Menu
+
+Menu is a Radix DropdownMenu-backed action surface for contextual commands, navigation, progress rows, labels, captions, call-to-action rows, submenus, and rich item media.
+
+## API
+
+```tsx
+<MenuRoot>
+  <MenuTrigger>Open menu</MenuTrigger>
+  <MenuContent width="menu">
+    <MenuItem>Profile</MenuItem>
+    <MenuSeparator />
+    <MenuItem kind="button">Upgrade plan</MenuItem>
+  </MenuContent>
+</MenuRoot>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal` | Radix-backed menu shell |
+| `MenuItem`, `MenuItemContent`, media slots | interactive rows |
+| `MenuSub`, `MenuSubTrigger`, `MenuSubContent` | nested menus |
+| `MenuLabel`, `MenuCaption`, `MenuSeparator` | non-interactive structure |
+
+| Prop | Values |
+| --- | --- |
+| `width` | `menu`, `default`, `multiline`, `action`, `auto` |
+| `kind` | `default`, `multiline`, `action`, `progress`, `button` |
+
+## Token Contract
+
+Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens.
+
+## RTL
+
+Menu uses logical padding and flex direction so leading icons, trailing actions, badges, switches, meta text, and submenus mirror naturally. Directional icons should use `data-rtl-flip="true"`.
+
+## Accessibility
+
+Radix provides menu roles, focus management, typeahead, keyboard navigation, Escape handling, and outside dismissal. Keep non-command copy in labels or captions, not disabled menu items.
+
+## Install
+
+```bash
+npx banhaten add menu
+```
+
+## Examples
+
+Primary registry example: `examples/menu-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs menu` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical padding and flex direction so leading, trailing, badge, switch, right text, and action slots mirror naturally.
+- `directionalIconFlip`: Use data-rtl-flip="true" on chevrons and arrows that should mirror.
+- `textDirection`: Text slots use dir="auto" by default for Arabic and English labels.
+
+<!-- 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/menu.tsx: Menu, MenuCaption, MenuContent, MenuItem, MenuItemAction, MenuItemAvatar, MenuItemBadge, MenuItemContent, MenuItemDescription, MenuItemIcon, MenuItemMeta, MenuItemSwitch, MenuItemText, MenuItemTitle, MenuLabel, MenuPortal, MenuPreview, MenuProgress, MenuRoot, MenuSeparator, MenuSub, MenuSubContent, MenuSubTrigger, MenuSurface, MenuTrigger, menuItemContentVariants, menuItemIconVariants, menuItemVariants, menuVariants` |
+| `parts` | `Menu`, `MenuPreview`, `MenuSurface`, `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal`, `MenuSub`, `MenuSubTrigger`, `MenuSubContent`, `MenuItem`, `MenuItemContent`, `MenuItemIcon`, `MenuItemAvatar`, `MenuItemText`, `MenuItemTitle`, `MenuItemDescription`, `MenuItemMeta`, `MenuItemBadge`, `MenuItemSwitch`, `MenuItemAction`, `MenuProgress`, `MenuSeparator`, `MenuLabel`, `MenuCaption` |
+| `registryDependencies` | None |
+| `itemKinds` | `default`, `multiline`, `action`, `progress`, `button` |
+| `states` | `default`, `disabled` |
+| `tokens` | `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-icon-stroke-300`, `--bh-interactive-indicator-default`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-hover`, `--bh-interactive-switch-active`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-menu-action-gap`, `--bh-menu-action-height`, `--bh-menu-action-padding-x`, `--bh-menu-badge-height`, `--bh-menu-badge-padding-x`, `--bh-menu-bg`, `--bh-menu-divider-padding-y`, `--bh-menu-gap`, `--bh-menu-icon-padding`, `--bh-menu-item-action-height`, `--bh-menu-item-action-width`, `--bh-menu-item-bg`, `--bh-menu-item-button-height`, `--bh-menu-item-caption-height`, `--bh-menu-item-content-compact-padding-y`, `--bh-menu-item-content-padding`, `--bh-menu-item-default-height`, `--bh-menu-item-default-width`, `--bh-menu-item-divider-height`, `--bh-menu-item-gap`, `--bh-menu-item-hover-bg`, `--bh-menu-item-label-height`, `--bh-menu-item-multiline-height`, `--bh-menu-item-multiline-width`, `--bh-menu-item-padding-x`, `--bh-menu-item-progress-height`, `--bh-menu-item-radius`, `--bh-menu-item-slot-gap`, `--bh-menu-label-padding-x`, `--bh-menu-leading-icon-size`, `--bh-menu-padding-y`, `--bh-menu-progress-gap`, `--bh-menu-progress-height`, `--bh-menu-radius`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-menu-trailing-icon-size`, `--bh-menu-width`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-medium-font-size`, `--bh-text-body-3xs-medium-font-weight`, `--bh-text-body-3xs-medium-letter-spacing`, `--bh-text-body-3xs-medium-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-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`, `--shadow-menu` |
+| `widths` | `menu`, `default`, `multiline`, `action`, `auto` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,60 @@
+# Menubar
+
+Menubar wraps Radix Menubar for application-style top menus.
+
+## API
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## Token Contract
+
+Menubar uses Banhaten menu, surface, border, shadow, hover, spacing, and body typography tokens.
+
+## RTL
+
+Triggers, menu items, and shortcuts use logical spacing and inherited direction.
+
+## Accessibility
+
+Radix provides menubar roles, keyboard navigation, open state, and submenu behavior.
+
+## Install
+
+```bash
+npx banhaten add menubar
+```
+
+## Examples
+
+Primary registry example: `examples/menubar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs menubar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Triggers, items, and shortcuts use logical spacing.
+
+<!-- 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/menubar.tsx: Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarTrigger` |
+| `parts` | `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarCheckboxItem`, `MenubarRadioItem`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut` |
+| `registryDependencies` | None |
+| `features` | `top menu`, `keyboard navigation`, `checkbox items`, `radio items`, `shortcuts` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-menu-item-default-height`, `--bh-menu-item-hover-bg`, `--bh-menu-width`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--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-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-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-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-popover`, `--shadow-component-default`, `--shadow-menu` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,119 @@
+# Modal
+
+`Modal` presents a focused dialog surface for decisions and blocking workflows. `ConfirmModal` adds the constrained alert-dialog/confirm pattern for consequential actions.
+
+Figma reference: `Design system 3.0 Copy / Modal`, node `227:5480`.
+
+## Variants
+
+The implementation covers the six-node Modal matrix from Figma:
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `default`, `lg` |
+| `dir` | `ltr`, `rtl` |
+
+## API
+
+```tsx
+<Modal size="default" />
+<Modal dir="rtl" messages={arabicModalMessages} size="lg" />
+<ConfirmModal intent="danger" confirmLabel="Delete project" />
+```
+
+| Prop | Default |
+| --- | --- |
+| `size` | `sm` |
+| `dir` | inherited |
+| `title` | English default; overrides `messages.title` |
+| `description` | English default; overrides `messages.description` |
+| `messages` | partial localized Modal message catalog |
+| `closeLabel` | overrides `messages.closeLabel` |
+| `showIcon` | `true` |
+| `showCloseButton` | `true` |
+| `showDivider` | `true` |
+| `showFooter` | `true` |
+| `showCheckbox` | `true` |
+| `footer` | none |
+
+`ConfirmModal` also accepts:
+
+| Prop | Default |
+| --- | --- |
+| `intent` | `danger` |
+| `messages` | partial localized ConfirmModal message catalog |
+| `confirmLabel` / `cancelLabel` | English; direct props override `messages` |
+| `confirmLoading` | `false` |
+| `confirmDisabled` | `false` |
+| `preventOutsideDismiss` | `true` |
+| `closeOnConfirm` / `closeOnCancel` | `true` |
+| `onConfirm` / `onCancel` | none |
+
+## Pixel Rules
+
+- Small, Default, and Large modal widths are `440px`, `560px`, and `700px`.
+- The shell uses `--bh-radius-2xl-12`.
+- Header padding is `20px 20px 8px`, with logical end padding reserved for the close button.
+- Body padding is `10px 20px 20px`.
+- Footer padding is `16px 20px`, with a `10px` gap.
+- Actions reuse `Button` with `size="sm"`, `variant="soft"` for the secondary action, and the default variant for the primary action.
+- Confirm actions reuse `Button` with `variant="danger"`, `variant="warning"`, or `variant="default"` from the selected intent.
+- The opt-out control reuses `Checkbox`.
+- Loading confirm actions reuse the Banhaten `Spinner` component.
+
+## Token Contract
+
+The component consumes existing Banhaten variables:
+
+- Surface: `--bh-bg-raised`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-warning-subtle`
+- Border: `--bh-border-subtle`
+- Content: `--bh-content-default`, `--bh-content-subtle`, `--bh-content-danger-default`, `--bh-content-warning-default`
+- Shape: `--bh-radius-2xl-12`, `--bh-radius-full`
+- Space: `--bh-space-xs-4`, `--bh-space-sm-6`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`
+- Type: `--bh-text-heading-sm-semibold-*`, `--bh-text-body-md-regular-*`
+- Elevation: `--shadow-component-default`, `--shadow-button-focus`, `--shadow-button-danger-focus`
+
+## Accessibility
+
+- `ModalContent` is backed by Radix Dialog for focus trap, Escape, outside-click dismissal, and ARIA dialog semantics.
+- `ModalTitle` and `ModalDescription` map to Radix dialog title and description primitives.
+- The close affordance is a real button through `ModalCloseButton`.
+- `ConfirmModal` sets `role="alertdialog"`, focuses the cancel action first when present, disables outside-pointer dismissal by default, and can optionally prevent Escape dismissal.
+- `ModalSurface` is presentational and intended for static documentation or visual comparison, not live modal behavior.
+- Direction never selects modal copy. Choose `messages` from the product locale; direct title, description, action, and close-label props have highest precedence.
+
+## Install
+
+```bash
+npx banhaten add modal
+```
+
+## Examples
+
+Primary registry example: `examples/modal-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs modal` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `closePlacement`: Close uses logical inline-end placement so it moves to the left side in RTL.
+- `footerOrder`: The checkbox and action cluster use inherited direction and logical gaps so their order mirrors naturally.
+- `messages`: Direction does not select language. Modal and ConfirmModal accept explicit message catalogs plus direct label overrides.
+- `textDirection`: Title, description, checkbox label, confirm labels, and actions use dir="auto" for Arabic and English copy.
+
+<!-- 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/modal.tsx: ConfirmModal, Modal, ModalActionButton, ModalActions, ModalBody, ModalClose, ModalCloseButton, ModalContent, ModalDescription, ModalDivider, ModalFooter, ModalFooterCheckbox, ModalHeader, ModalHeaderIcon, ModalOverlay, ModalPortal, ModalRoot, ModalSurface, ModalTitle, ModalTrigger, arabicConfirmModalMessages, arabicModalMessages, modalContentVariants, modalSurfaceVariants` |
+| `parts` | `Modal`, `ConfirmModal`, `ModalRoot`, `ModalTrigger`, `ModalContent`, `ModalPortal`, `ModalOverlay`, `ModalHeader`, `ModalHeaderIcon`, `ModalTitle`, `ModalDescription`, `ModalBody`, `ModalDivider`, `ModalFooter`, `ModalFooterCheckbox`, `ModalActions`, `ModalActionButton`, `ModalClose`, `ModalCloseButton`, `ModalSurface` |
+| `registryDependencies` | `alert-dialog`, `button`, `checkbox`, `spinner` |
+| `intents` | `default`, `warning`, `danger` |
+| `sizes` | `sm`, `default`, `lg` |
+| `tokens` | `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-modal-action-label-padding-x`, `--bh-modal-border`, `--bh-modal-width`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--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-sm-6`, `--bh-space-xs-4`, `--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-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`, `--shadow-modal` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,70 @@
+# Native Select
+
+Native Select is a tokenized native `<select>` field for platform forms, mobile fallback, and lightweight option sets.
+
+## API
+
+```tsx
+<NativeSelect
+  label="Workspace"
+  options={[
+    { label: "Design", value: "design" },
+    { label: "Engineering", value: "engineering" },
+  ]}
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `lg` |
+| `variant` | `default`, `soft` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+| `options` | array of `{ label, value, disabled }` |
+
+## Token Contract
+
+Native Select reuses Banhaten select width, label, helper, trigger, border, focus, icon, and validation tokens.
+
+## RTL
+
+Native Select accepts `dir` and uses logical padding plus an inline-end chevron.
+
+## Accessibility
+
+Prefer `label` or an external `<Label htmlFor>` and use helper or error copy for validation context.
+
+## Install
+
+```bash
+npx banhaten add native-select
+```
+
+## Examples
+
+Primary registry example: `examples/native-select-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs native-select` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical padding and inline-end chevron placement.
+- `textDirection`: Label and helper copy use dir="auto" through Label and helper text.
+
+<!-- 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/native-select.tsx: NativeSelect, nativeSelectControlVariants, nativeSelectRootVariants` |
+| `parts` | `NativeSelect` |
+| `registryDependencies` | `label` |
+| `features` | `options array`, `native children`, `label`, `helper text`, `error text` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-input-lg-height`, `--bh-input-md-height`, `--bh-select-field-gap`, `--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-icon-color`, `--bh-select-trigger-padding-x`, `--bh-select-trigger-radius`, `--bh-select-width`, `--bh-space-3xl-16`, `--bh-space-8xl-48`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--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`, `--shadow-component-default`, `--shadow-select-danger-focus-ring`, `--shadow-select-focus-ring`, `--shadow-select-trigger` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->