banhaten 0.1.3 → 0.2.0

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

@@ -99,3 +99,19 @@ Covered source files: `components/divider.tsx`.
 
 - `inheritsDirection`: false
 - `geometry`: Direction maps to component orientation, not document text 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/divider.tsx: Divider, dividerVariants` |
+| `parts` | `Divider` |
+| `registryDependencies` | None |
+| `directions` | `horizontal`, `vertical` |
+| `tokens` | `--bh-border-subtle`, `--bh-space-15xl-224`, `--bh-space-xxs-2`, `--bh-space-xxxs-1` |
+| `types` | `solid`, `dotted` |
+<!-- registry-contract:end -->

package/docs/design-system/components/empty-state.md

@@ -53,3 +53,20 @@ Open the live component page or run `npx banhaten docs empty-state` to inspect s
 ## 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/expanded/EmptyState.tsx: EmptyState` |
+| `parts` | `EmptyState` |
+| `registryDependencies` | `button` |
+| `alignments` | `center`, `start` |
+| `features` | `neutral icon halo`, `title and description copy`, `primary and secondary actions`, `custom icon`, `RTL` |
+| `sizes` | `default`, `compact` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-empty-state-icon-stroke-width`, `--bh-font-family`, `--bh-radius-full`, `--bh-space-10xl-80`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-9xl-64`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-base-letter-spacing`, `--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-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-letter-spacing`, `--bh-text-heading-xs-semibold-line-height` |
+<!-- registry-contract:end -->

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

@@ -67,3 +67,20 @@ Open the live component page or run `npx banhaten docs field` to inspect source
 ## Accessibility
 
 This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
+<!-- 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/field.tsx: Field, FieldContent, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSet` |
+| `parts` | `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldContent` |
+| `registryDependencies` | `label` |
+| `features` | `generated ids`, `control slot`, `description text`, `error text`, `field groups`, `validation mapping` |
+| `orientations` | `vertical`, `horizontal`, `responsive` |
+| `states` | `default`, `invalid`, `disabled` |
+| `tokens` | `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-space-17xl-288`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-letter-spacing`, `--bh-text-body-md-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` |
+<!-- registry-contract:end -->

package/docs/design-system/components/file-upload.md

@@ -183,3 +183,17 @@ Covered source files: `components/expanded/fileUpload.css`, `components/expanded
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and 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/expanded/FileUpload.tsx: FileUpload` |
+| `parts` | `FileUpload` |
+| `registryDependencies` | `button` |
+| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--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-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--shadow-component-default`, `--shadow-xs` |
+<!-- registry-contract:end -->

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

@@ -44,3 +44,18 @@ Open the live component page or run `npx banhaten docs hover-card` to inspect so
 
 - `inheritsDirection`: true
 - `textDirection`: Content inherits direction and uses 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/hover-card.tsx: HoverCard, HoverCardContent, HoverCardPortal, HoverCardTrigger` |
+| `parts` | `HoverCard`, `HoverCardTrigger`, `HoverCardContent`, `HoverCardPortal` |
+| `registryDependencies` | None |
+| `features` | `hover preview`, `focus preview`, `open delay`, `close delay` |
+| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-radius-2xl-12`, `--bh-space-18xl-320`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-z-popover`, `--shadow-popover` |
+<!-- registry-contract:end -->

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

@@ -54,3 +54,20 @@ Open the live component page or run `npx banhaten docs input-group` to inspect s
 - `inheritsDirection`: true
 - `spacing`: Add-ons and input segments use logical borders and inherited direction.
 - `textDirection`: Input text uses text-start so mixed Arabic and English values align naturally.
+
+<!-- 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-group.tsx: InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, inputGroupVariants` |
+| `parts` | `InputGroup`, `InputGroupInput`, `InputGroupAddon`, `InputGroupButton` |
+| `registryDependencies` | `button` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `error` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-border`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--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-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`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-focus-ring` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

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

@@ -53,3 +53,21 @@ Open the live component page or run `npx banhaten docs input-otp` to inspect sou
 - `keyboard`: Arrow navigation mirrors for RTL: visual previous and next follow the inherited direction.
 - `spacing`: Slot groups, separators, labels, and helper text use inherited direction plus Input spacing tokens.
 - `composition`: Each slot reuses the Banhaten Input surface and control typography instead of a separate field style.
+
+<!-- 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-otp.tsx: InputOTP, InputOTPSeparator` |
+| `parts` | `InputOTP`, `InputOTPSeparator` |
+| `registryDependencies` | `input` |
+| `features` | `controlled value`, `uncontrolled value`, `paste distribution`, `hidden form value`, `masked slots`, `custom length`, `custom grouping` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-bg-brand-soft`, `--bh-border-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-helper-gap`, `--bh-input-inline-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-otp-group-gap`, `--bh-input-otp-separator-height`, `--bh-input-otp-separator-width`, `--bh-input-otp-slot-comfortable-width`, `--bh-input-otp-slot-gap`, `--bh-input-otp-slot-lg-width`, `--bh-input-otp-slot-md-width`, `--bh-input-otp-width`, `--bh-input-width`, `--bh-radius-full`, `--bh-space-none`, `--bh-text-body-md-medium-font-weight`, `--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` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

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

@@ -9,13 +9,21 @@ Input is the text-entry field primitive for forms, filters, search, numeric entr
 <Input state="error" label="Amount" message="Enter a valid amount" />
 ```
 
-| Prop | Values |
-| --- | --- |
-| `kind` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` |
-| `variant` | `default`, `soft` |
-| `size` | `md`, `lg` |
-| `state` | `default`, `filled`, `error`, `disabled` |
-| `label`, `message` | `ReactNode` |
+| 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
 
@@ -46,3 +54,31 @@ Open the live component page or run `npx banhaten docs input` to inspect source
 - `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

@@ -42,3 +42,21 @@ Open the live component page or run `npx banhaten docs kbd` to inspect source fi
 
 - `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

@@ -46,3 +46,19 @@ Open the live component page or run `npx banhaten docs label` to inspect source
 - `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

@@ -57,3 +57,20 @@ Open the live component page or run `npx banhaten docs menu` to inspect source f
 - `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

@@ -43,3 +43,18 @@ Open the live component page or run `npx banhaten docs menubar` to inspect sourc
 
 - `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

@@ -17,7 +17,7 @@ The implementation covers the six-node Modal matrix from Figma:
 
 ```tsx
 <Modal size="default" />
-<Modal dir="rtl" size="lg" />
+<Modal dir="rtl" messages={arabicModalMessages} size="lg" />
 <ConfirmModal intent="danger" confirmLabel="Delete project" />
 ```
 
@@ -25,8 +25,10 @@ The implementation covers the six-node Modal matrix from Figma:
 | --- | --- |
 | `size` | `sm` |
 | `dir` | inherited |
-| `title` | localized demo title |
-| `description` | localized demo description |
+| `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` |
@@ -39,7 +41,8 @@ The implementation covers the six-node Modal matrix from Figma:
 | Prop | Default |
 | --- | --- |
 | `intent` | `danger` |
-| `confirmLabel` / `cancelLabel` | localized |
+| `messages` | partial localized ConfirmModal message catalog |
+| `confirmLabel` / `cancelLabel` | English; direct props override `messages` |
 | `confirmLoading` | `false` |
 | `confirmDisabled` | `false` |
 | `preventOutsideDismiss` | `true` |
@@ -77,6 +80,7 @@ The component consumes existing Banhaten variables:
 - 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
 
@@ -95,4 +99,21 @@ Open the live component page or run `npx banhaten docs modal` to inspect source
 - `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

@@ -50,3 +50,21 @@ Open the live component page or run `npx banhaten docs native-select` to inspect
 - `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 -->

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

@@ -46,3 +46,18 @@ Open the live component page or run `npx banhaten docs navigation-menu` to inspe
 
 - `inheritsDirection`: true
 - `spacing`: Triggers, links, and content use logical layout and inherited 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/navigation-menu.tsx: NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport` |
+| `parts` | `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuViewport`, `NavigationMenuIndicator` |
+| `registryDependencies` | None |
+| `features` | `top navigation`, `viewport`, `indicator`, `dropdown content` |
+| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-content-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-radius-2xl-12`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--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-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-z-popover`, `--bh-z-raised`, `--shadow-popover` |
+<!-- registry-contract:end -->

package/docs/design-system/components/onboarding-step-list-item.md

@@ -38,7 +38,7 @@ Code uses lowercase semantic state values: `finished`, `active`, and `inactive`.
 
 ## Token Contract
 
-The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
 
 - Backgrounds: `--bh-bg-raised`
 - Borders: `--bh-border-brand-strong`, `--bh-border-default`
@@ -78,3 +78,17 @@ Open the live component page or run `npx banhaten docs onboarding-step` to inspe
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and 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/expanded/OnboardingStepListItem.tsx: OnboardingStepListItem` |
+| `parts` | `OnboardingStepListItem` |
+| `registryDependencies` | None |
+| `tokens` | `--bh-bg-raised`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-control-default`, `--bh-font-family`, `--bh-icon-stroke-225`, `--bh-space-17xl-288`, `--bh-space-2xl-14`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--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`, `--shadow-component-default` |
+<!-- registry-contract:end -->

package/docs/design-system/components/page-header.md

@@ -42,7 +42,7 @@ The implementation follows the Figma hierarchy:
 
 ## Token Contract
 
-The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
 
 - Borders: `--bh-border-default`
 - Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-heading`, `--bh-content-muted`, `--bh-content-subtle`
@@ -82,3 +82,17 @@ Open the live component page or run `npx banhaten docs page-header` to inspect s
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and 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/expanded/PageHeader.tsx: PageHeader` |
+| `parts` | `PageHeader` |
+| `registryDependencies` | `tabs` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-icon-stroke-190`, `--bh-interactive-secondary-default`, `--bh-opacity-muted`, `--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-lg-10`, `--bh-space-md-8`, `--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-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--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-heading-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-line-height`, `--shadow-button-secondary` |
+<!-- registry-contract:end -->

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

@@ -1,21 +1,27 @@
 # Pagination
 
-Pagination navigates paged result sets, tables, and long lists. It supports numeric, simple, and summary layouts, soft and ghost styles, exact control geometry, captions, and RTL labels.
+Pagination navigates paged result sets, tables, and long lists. It supports numeric, simple, and summary layouts, soft and ghost styles, exact control geometry, captions, RTL layout, and explicit localized messages.
 
 ## API
 
 ```tsx
-<Pagination page={3} totalPages={12} type="numeric" />
-<Pagination dir="rtl" page={2} totalPages={8} type="summary" />
+<Pagination page={3} pages={[1, 2, 3, "ellipsis", 12]} type="numeric" />
+<Pagination
+  dir="rtl"
+  messages={{ previous: "הקודם", next: "הבא" }}
+  page={2}
+  type="summary"
+/>
 ```
 
 | Prop | Values | Default |
 | --- | --- | --- |
 | `type` | `numeric`, `simple`, `summary` | `numeric` |
 | `variant` | `soft`, `ghost` | `soft` |
-| `page` | number | `1` |
-| `totalPages` | number | required |
-| `labels` | localized label overrides | direction-aware defaults |
+| `page` | number | `2` |
+| `pages` | page numbers, page descriptors, `ellipsis` | built-in demo sequence |
+| `messages` | partial localized message catalog | English defaults |
+| `caption`, `summary`, previous/next label and ARIA props | direct overrides | matching message value |
 
 ## Token Contract
 
@@ -23,7 +29,7 @@ Pagination uses Banhaten control height, radius, border, background, content, fo
 
 ## RTL
 
-Passing `dir="rtl"` switches default labels to Arabic and mirrors previous/next directional icons with `data-rtl-flip="true"`.
+Passing `dir="rtl"` mirrors previous/next directional icons with `data-rtl-flip="true"` and leaves the selected message catalog unchanged. Use `arabicPaginationMessages` or product-owned messages when the locale is Arabic.
 
 ## Accessibility
 
@@ -44,6 +50,22 @@ Open the live component page or run `npx banhaten docs pagination` to inspect so
 ## RTL Rules
 
 - `inheritsDirection`: true
-- `labels`: Defaults to Arabic labels when dir="rtl" is provided or the document direction is RTL.
+- `messages`: Direction does not select language. English defaults are stable; pass messages for Arabic, Hebrew, Persian, Urdu, or another locale.
 - `directionalIconFlip`: Inline Figma arrow vectors use data-rtl-flip="true" so previous and next controls mirror in RTL.
 - `spacing`: Uses logical flex direction, gap, and text direction so English and Arabic captions align naturally.
+
+<!-- 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/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` |
+| `types` | `numeric`, `simple`, `summary` |
+| `variants` | `soft`, `ghost` |
+<!-- registry-contract:end -->