banhaten 0.1.3 → 0.3.0

package/docs/design-system/components/social-button.md

@@ -1,6 +1,6 @@
 # Social Button
 
-Social Button is the sign-in action primitive for supported identity providers. It includes Figma-matched platform styling, solid and outlined variants, icon-only mode, native focus-visible styling, and RTL labels.
+Social Button is the sign-in action primitive for supported identity providers. It includes Figma-matched platform styling, solid and outlined variants, icon-only mode, native focus-visible styling, RTL layout, and explicit localized messages.
 
 ## API
 
@@ -15,6 +15,7 @@ Social Button is the sign-in action primitive for supported identity providers.
 | `variant` | `solid`, `outline` |
 | `size` | `default`, `icon` |
 | `label` | localized label override |
+| `messages` | partial provider-label catalog selected by product locale |
 
 ## Token Contract
 
@@ -22,7 +23,7 @@ Social Button uses Banhaten control, typography, radius, focus, spacing, and sha
 
 ## RTL
 
-When direction is RTL, platform labels default to Arabic where provided. Icon and label spacing uses logical flex rhythm.
+Icon and label spacing uses logical flex rhythm in RTL. Labels remain English unless `messages`, `label`, or text children select another language; `arabicSocialButtonMessages` is available for an explicit Arabic locale.
 
 ## Accessibility
 
@@ -43,5 +44,22 @@ Open the live component page or run `npx banhaten docs social-button` to inspect
 ## RTL Rules
 
 - `inheritsDirection`: true
-- `labels`: Defaults to the Arabic platform label when the document direction is RTL, and accepts an explicit label for nested RTL surfaces.
+- `messages`: Direction controls layout only. Pass label, children, aria-label, or messages to localize provider names.
 - `spacing`: Uses logical label padding and flex gap so the icon/label order follows 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/social-button.tsx: SocialButton, arabicSocialButtonMessages, socialButtonVariants, socialPlatformConfig` |
+| `parts` | `SocialButton` |
+| `registryDependencies` | None |
+| `platforms` | `apple`, `facebook`, `google`, `linkedin`, `twitter`, `whatsapp` |
+| `sizes` | `default`, `icon` |
+| `tokens` | `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-width-default`, `--bh-content-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-opacity-50`, `--bh-social-apple-bg`, `--bh-social-apple-border`, `--bh-social-apple-fg`, `--bh-social-apple-hover`, `--bh-social-apple-icon`, `--bh-social-apple-icon-border`, `--bh-social-apple-outline-icon`, `--bh-social-apple-width`, `--bh-social-apple-width-rtl`, `--bh-social-button-bg`, `--bh-social-button-bg-hover`, `--bh-social-button-border`, `--bh-social-button-current-border`, `--bh-social-button-fg`, `--bh-social-button-focus-border`, `--bh-social-button-gap`, `--bh-social-button-height`, `--bh-social-button-icon`, `--bh-social-button-icon-size`, `--bh-social-button-label-padding-inline-end`, `--bh-social-button-padding-x`, `--bh-social-button-padding-y`, `--bh-social-button-radius`, `--bh-social-button-width`, `--bh-social-button-width-rtl`, `--bh-social-facebook-bg`, `--bh-social-facebook-fg`, `--bh-social-facebook-hover`, `--bh-social-facebook-icon`, `--bh-social-facebook-outline-icon`, `--bh-social-facebook-width`, `--bh-social-facebook-width-rtl`, `--bh-social-google-bg`, `--bh-social-google-border`, `--bh-social-google-fg`, `--bh-social-google-hover`, `--bh-social-google-width`, `--bh-social-google-width-rtl`, `--bh-social-linkedin-bg`, `--bh-social-linkedin-fg`, `--bh-social-linkedin-hover`, `--bh-social-linkedin-icon`, `--bh-social-linkedin-outline-icon`, `--bh-social-linkedin-width`, `--bh-social-linkedin-width-rtl`, `--bh-social-twitter-bg`, `--bh-social-twitter-border`, `--bh-social-twitter-fg`, `--bh-social-twitter-hover`, `--bh-social-twitter-icon`, `--bh-social-twitter-icon-border`, `--bh-social-twitter-outline-icon`, `--bh-social-twitter-width`, `--bh-social-twitter-width-rtl`, `--bh-social-whatsapp-bg`, `--bh-social-whatsapp-fg`, `--bh-social-whatsapp-hover`, `--bh-social-whatsapp-icon`, `--bh-social-whatsapp-outline-icon`, `--bh-social-whatsapp-width`, `--bh-social-whatsapp-width-rtl`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-component-default`, `--shadow-social-button`, `--shadow-social-button-focus` |
+| `variants` | `solid`, `outline` |
+<!-- registry-contract:end -->

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

@@ -59,3 +59,19 @@ This component has no special RTL contract beyond inherited document direction a
 ## 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/spinner.tsx: DynamicSpinner, Spinner` |
+| `parts` | `Spinner`, `DynamicSpinner` |
+| `registryDependencies` | None |
+| `features` | `steady arc rotation`, `dynamic arc length`, `slower continuous rotation`, `text color inheritance`, `CSS variable sizing` |
+| `modes` | `steady`, `dynamic` |
+| `tokens` | `--bh-opacity-25`, `--bh-spinner-duration-dynamic`, `--bh-spinner-duration-steady`, `--bh-spinner-easing`, `--bh-spinner-size`, `--bh-spinner-stroke-width` |
+<!-- registry-contract:end -->

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

@@ -61,3 +61,22 @@ This component has no special RTL contract beyond inherited document direction a
 ## 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/Steps.tsx: HorizontalStepItem, ProgressSteps, Steps, VerticalStepItem` |
+| `parts` | `HorizontalStepItem`, `ProgressSteps`, `Steps`, `VerticalStepItem` |
+| `registryDependencies` | `button` |
+| `modes` | `steps`, `progress-steps`, `horizontal-item`, `vertical-item` |
+| `orientations` | `horizontal`, `vertical` |
+| `states` | `complete`, `active`, `todo` |
+| `tokens` | `--bh-bg-accent-purple-subtle`, `--bh-bg-inverse`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-content-default`, `--bh-content-inverse`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-steps-horizontal-width`, `--bh-steps-indicator-panel-width`, `--bh-steps-vertical-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size` |
+| `variants` | `icon`, `number` |
+<!-- registry-contract:end -->
+`ProgressSteps` covers compact bar progress and status-aware marker sequences used in setup and enrollment flows.

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

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

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

@@ -50,3 +50,20 @@ Open the live component page or run `npx banhaten docs tabs` to inspect source f
 - `keyboard`: Radix receives dir so arrow-key navigation follows the document direction.
 - `textDirection`: Trigger labels use dir="auto" by default for Arabic and English tab labels.
 - `spacing`: Uses inherited direction and logical inline spacing so underline, segmented, and rounded treatments mirror 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/tabs.tsx: Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger` |
+| `parts` | `Tabs`, `TabsRoot`, `TabsList`, `TabsTrigger`, `TabsContent` |
+| `registryDependencies` | None |
+| `features` | `Radix keyboard behavior`, `controlled active index`, `controlled value`, `optional panels`, `full-width tabs` |
+| `sizes` | `md`, `sm`, `xs` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-subtle`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-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`, `--shadow-button-soft` |
+| `variants` | `underline`, `segment`, `rounded` |
+<!-- registry-contract:end -->

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

@@ -76,3 +76,20 @@ Open the live component page or run `npx banhaten docs tag` to inspect source fi
 ## 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/tag.tsx: Tag, TagAvatar, TagCloseButton, TagDot, TagFlag, TagIcon, tagVariants` |
+| `parts` | `Tag`, `TagDot`, `TagFlag`, `TagAvatar`, `TagIcon`, `TagCloseButton` |
+| `registryDependencies` | None |
+| `sizes` | `xs`, `md`, `lg` |
+| `states` | `default`, `active`, `disabled` |
+| `tokens` | `--bh-bg-accent-green-default`, `--bh-bg-always-dark`, `--bh-bg-always-white`, `--bh-bg-brand-subtle`, `--bh-bg-danger-default`, `--bh-bg-neutral-bold`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-neutral`, `--bh-control-default`, `--bh-control-md`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-opacity-30`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-tag-active-border-width`, `--bh-tag-focus-ring-inset`, `--bh-tag-focus-ring-width`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--bh-text-body-3xs-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-z-raised`, `--shadow-button-focus` |
+| `types` | `simple`, `dot`, `flag`, `avatar`, `icon` |
+<!-- registry-contract:end -->

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

@@ -46,3 +46,19 @@ Open the live component page or run `npx banhaten docs textarea` to inspect sour
 - `inheritsDirection`: true
 - `textAlignment`: Uses text-start and dir="auto" so Arabic and English content align naturally.
 - `spacing`: Uses inherited direction and flex order so labels, helper icons, and tag chips mirror without physical left/right rules.
+
+<!-- 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/textarea.tsx: Textarea` |
+| `parts` | `Textarea` |
+| `registryDependencies` | None |
+| `modes` | `default`, `tags` |
+| `states` | `placeholder`, `filled`, `disabled` |
+| `tokens` | `--bh-bg-accent-blue-soft`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-accent-blue-strong`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-font-weight-semibold`, `--bh-icon-stroke-225`, `--bh-icon-stroke-250`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-opacity-0`, `--bh-opacity-30`, `--bh-opacity-50`, `--bh-radius-full`, `--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`, `--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-textarea-border`, `--bh-textarea-close-button-size`, `--bh-textarea-close-icon-size`, `--bh-textarea-focus-ring-inset`, `--bh-textarea-focus-ring-width`, `--bh-textarea-gap`, `--bh-textarea-helper-icon-size`, `--bh-textarea-icon-size`, `--bh-textarea-inline-gap`, `--bh-textarea-min-height`, `--bh-textarea-padding`, `--bh-textarea-radius`, `--bh-textarea-tag-avatar-font-size`, `--bh-textarea-tag-avatar-size`, `--bh-textarea-tag-height`, `--bh-textarea-width`, `--shadow-component-default`, `--shadow-textarea` |
+<!-- registry-contract:end -->

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

@@ -79,3 +79,20 @@ This component has no special RTL contract beyond inherited document direction a
 ## 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/Timeline.tsx: Timeline, TimelineItem` |
+| `parts` | `Timeline`, `TimelineItem` |
+| `registryDependencies` | None |
+| `orientations` | `vertical`, `horizontal` |
+| `states` | `finished`, `active`, `inactive` |
+| `tokens` | `--bh-bg-brand-default`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-timeline-grid-width`, `--bh-timeline-narrow-width`, `--bh-timeline-sidebar-width`, `--shadow-component-focus-ring` |
+| `variants` | `default`, `icon` |
+<!-- registry-contract:end -->

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

@@ -54,3 +54,20 @@ Open the live component page or run `npx banhaten docs toast` to inspect source
 - `inheritsDirection`: true
 - `placement`: side="end" resolves to top-right in LTR and top-left in RTL; side="start" resolves to the opposite edge.
 - `textDirection`: Toast content inherits the Toaster direction and uses tokenized typography classes.
+
+<!-- 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/toast.tsx: Toaster, toast` |
+| `parts` | `Toaster` |
+| `registryDependencies` | None |
+| `features` | `semantic shortcuts`, `action slot`, `close button`, `logical placement`, `toast promise support` |
+| `intents` | `default`, `success`, `danger`, `warning`, `info` |
+| `sides` | `start`, `end` |
+| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-danger-subtle`, `--bh-bg-info-subtle`, `--bh-bg-neutral-soft`, `--bh-bg-raised`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-border-danger-subtle`, `--bh-border-info-subtle`, `--bh-border-subtle`, `--bh-border-success-subtle`, `--bh-border-warning-subtle`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-default`, `--bh-control-default`, `--bh-font-family`, `--bh-interactive-brand-default`, `--bh-radius-xl-10`, `--bh-space-lg-10`, `--bh-space-xs-4`, `--bh-text-body-sm-semibold-font-size`, `--bh-text-body-sm-semibold-font-weight`, `--bh-text-body-sm-semibold-letter-spacing`, `--bh-text-body-sm-semibold-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-toast-accent`, `--bh-toast-accent-bg`, `--shadow-component-default` |
+<!-- registry-contract:end -->

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

@@ -77,3 +77,20 @@ Covered source files: `components/toggle.tsx`.
 ## Accessibility
 
 This component relies on `@radix-ui/react-switch` 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/toggle.tsx: Toggle, ToggleField, toggleFieldVariants, toggleVariants` |
+| `parts` | `Toggle`, `ToggleField` |
+| `registryDependencies` | None |
+| `features` | `optional handle icons`, `leading label`, `trailing label`, `supporting text` |
+| `sizes` | `sm`, `md` |
+| `states` | `unchecked`, `checked`, `hover`, `focused`, `disabled` |
+| `tokens` | `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-light`, `--bh-content-subtle`, `--bh-icon-stroke-250`, `--bh-interactive-switch-active`, `--bh-interactive-switch-active-disabled`, `--bh-interactive-switch-active-hover`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-interactive-switch-hover`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-toggle-handle-size`, `--bh-toggle-icon-size-md`, `--bh-toggle-icon-size-sm`, `--bh-toggle-offset`, `--shadow-md`, `--shadow-social-button-focus-ring` |
+<!-- registry-contract:end -->

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

@@ -61,7 +61,7 @@ Set `dir="rtl"` on `Toolbar` or inherit it from the document. Sections, fields,
 
 ## API
 
-Public exports: `Toolbar`, `ToolbarSection`, `ToolbarSearch`, `ToolbarSelect`, `ToolbarButton`, `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`, `ToolbarBadge`, `ToolbarText`, `ToolbarSpacer`.
+Supported runtime exports: `Toolbar`, `ToolbarBadge`, `ToolbarButton`, `ToolbarFilterButton`, `ToolbarIconButton`, `ToolbarMoreButton`, `ToolbarSearch`, `ToolbarSection`, `ToolbarSelect`, `ToolbarSpacer`, `ToolbarText`, `toolbarBadgeVariants`, `toolbarButtonVariants`, `toolbarSearchVariants`, `toolbarSectionVariants`, `toolbarSelectVariants`, `toolbarVariants`.
 
 | Contract | Values |
 | --- | --- |
@@ -83,3 +83,23 @@ Open the live component page or run `npx banhaten docs toolbar` to inspect sourc
 ## 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/toolbar.tsx: Toolbar, ToolbarBadge, ToolbarButton, ToolbarFilterButton, ToolbarIconButton, ToolbarMoreButton, ToolbarSearch, ToolbarSection, ToolbarSelect, ToolbarSpacer, ToolbarText, toolbarBadgeVariants, toolbarButtonVariants, toolbarSearchVariants, toolbarSectionVariants, toolbarSelectVariants, toolbarVariants` |
+| `parts` | `Toolbar`, `ToolbarSection`, `ToolbarSearch`, `ToolbarSelect`, `ToolbarButton`, `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`, `ToolbarBadge`, `ToolbarText`, `ToolbarSpacer` |
+| `registryDependencies` | `kbd` |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Aligns Toolbar Search, Select, Text, and Button controls to the shared 32px, 36px, or 40px control contract.` |
+| `props.shortcutKeys` | `readonly string[]; default null; Adds shared, platform-aware Kbd keycaps to ToolbarSearch without rebuilding a shortcut badge locally.` |
+| `breakpoints` | `desktop`, `mobile` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `layouts` | `inline`, `split`, `stack`, `wrap` |
+| `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
+| `tokens` | `--bh-bg-brand-subtle`, `--bh-bg-default-hover`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-label-padding-x`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-radius-full`, `--bh-select-icon-size`, `--bh-select-icon-slot-size`, `--bh-select-trigger-padding-x`, `--bh-select-width`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-soft`, `--shadow-input`, `--shadow-input-focus-ring`, `--shadow-select-trigger` |
+<!-- registry-contract:end -->

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

@@ -59,7 +59,7 @@ Tooltip content uses inherited direction and `dir="auto"` text. Top and bottom l
 
 ## API
 
-Public exports: `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`, `TooltipPortal`, `TooltipShortcut`, `TooltipCloseButton`.
+Supported runtime exports: `Tooltip`, `TooltipCloseButton`, `TooltipContent`, `TooltipPortal`, `TooltipProvider`, `TooltipRoot`, `TooltipShortcut`, `TooltipTrigger`, `tooltipContentVariants`.
 
 | Contract | Values |
 | --- | --- |
@@ -88,3 +88,20 @@ Covered source files: `components/tooltip.tsx`.
 ## Accessibility
 
 This component relies on `@radix-ui/react-tooltip` 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/tooltip.tsx: Tooltip, TooltipCloseButton, TooltipContent, TooltipPortal, TooltipProvider, TooltipRoot, TooltipShortcut, TooltipTrigger, tooltipContentVariants` |
+| `parts` | `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`, `TooltipPortal`, `TooltipShortcut`, `TooltipCloseButton` |
+| `registryDependencies` | None |
+| `pointerPositions` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-right`, `center-left`, `none` |
+| `sizes` | `sm`, `lg` |
+| `tokens` | `--bh-bg-always-dark`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-inverse-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-font-family`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-tooltip-bg`, `--bh-tooltip-border`, `--bh-tooltip-close-fg`, `--bh-tooltip-close-icon-size`, `--bh-tooltip-close-size`, `--bh-tooltip-fg`, `--bh-tooltip-lg-padding`, `--bh-tooltip-lg-radius`, `--bh-tooltip-lg-width`, `--bh-tooltip-max-width`, `--bh-tooltip-pointer-border-depth`, `--bh-tooltip-pointer-border-half-width`, `--bh-tooltip-pointer-border-offset`, `--bh-tooltip-pointer-depth`, `--bh-tooltip-pointer-half-width`, `--bh-tooltip-pointer-inline-offset`, `--bh-tooltip-pointer-offset`, `--bh-tooltip-pointer-width`, `--bh-tooltip-shadow`, `--bh-tooltip-shortcut-bg`, `--bh-tooltip-shortcut-border`, `--bh-tooltip-shortcut-height`, `--bh-tooltip-shortcut-min-width`, `--bh-tooltip-sm-padding-x`, `--bh-tooltip-sm-padding-y`, `--bh-tooltip-sm-radius`, `--bh-z-overlay`, `--bh-z-raised`, `--shadow-button-focus`, `--shadow-lg` |
+| `variants` | `dark`, `default` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,61 @@
+# Density and Elevation
+
+## Density
+
+Banhaten exposes one semantic density contract for controls that must align in a
+product surface:
+
+| Density | Height | Typical use |
+| --- | ---: | --- |
+| `compact` | 32px | Dense desktop tables and constrained toolbars |
+| `default` | 36px | Standard forms, search, filters, and actions |
+| `comfortable` | 40px | Prominent forms and less dense product areas |
+
+Use `density` when Input, Select, Date Picker, Button, Button Group, Segmented
+Control, or Toolbar controls sit in the same row. The semantic prop overrides
+the component's legacy `size` prop. Existing `size` values remain supported for
+compatibility and for component-specific variants outside the shared 32/36/40
+control family.
+
+```tsx
+<Input density="default" />
+<Select density="default" />
+<DatePicker density="default" />
+<Button density="default">Apply</Button>
+<ToggleGroup density="default" />
+```
+
+Do not align controls by adding raw `h-*`, padding, radius, or font-size
+utilities. Choose one semantic density at the containing form or toolbar and
+pass it to every control. Compact controls are intended for pointer-led desktop
+interfaces; products with touch requirements should prefer `comfortable` or
+provide a larger interaction target around the control.
+
+This is a component composition contract, not a global scale transform. It does
+not silently resize navigation, cards, typography, or unrelated layout spacing.
+
+## Elevation
+
+Elevation uses two layers:
+
+- General steps: `--shadow-xs` through `--shadow-xl`.
+- Semantic component aliases: `--shadow-component-*`, focus/danger rings, menus, controls, and component-specific aliases.
+
+The five general steps mirror the Figma `Shadow/xs`, `Shadow/sm`, `Shadow/md`,
+`Shadow/lg`, and `Shadow/xl` effect styles. They have no mode-specific bindings
+in Figma, so the same recipes are used in light and dark modes.
+
+| Step | Current component roles |
+| --- | --- |
+| `xs` | Compact raised details and file-upload error surfaces |
+| `sm` | Quiet cards, panels, and staged content surfaces |
+| `md` | Slider and toggle handles and floating banners |
+| `lg` | Menus, select menus, popovers, tooltips, date surfaces, and dialogs |
+| `xl` | Reserved for surfaces that need more separation than current dialogs |
+
+Components consume the semantic alias that describes purpose rather than
+selecting a visual step directly. Focus rings, inset borders, and the Figma
+`Shadow/component/*` control effects remain separate from surface elevation.
+The Shadows documentation groups aliases under their canonical effect and
+distinguishes surface elevation, control strokes, focus rings, overlay
+elevation, and intentional `none` values.

package/docs/design-system/direction-and-localization.md

@@ -0,0 +1,23 @@
+# Direction and Localization
+
+Banhaten is Arabic and English-first, but text direction and language are separate contracts. Components resolve direction from an explicit `dir`, `DirectionProvider`, the nearest valid `[dir]` ancestor, or the document root—in that order. Direction changes layout, icon mirroring, and keyboard geometry; it never selects translated UI or accessibility copy.
+
+Use a request-known direction provider for server rendering so the server markup, hydration snapshot, and first paint agree:
+
+```tsx
+import { DirectionProvider } from "@/hooks/use-direction"
+import {
+  arabicPaginationMessages,
+  Pagination,
+} from "@/components/ui/pagination"
+
+<DirectionProvider dir="rtl">
+  <Pagination messages={arabicPaginationMessages} />
+</DirectionProvider>
+```
+
+`DirectionProvider dir="rtl"` works equally well with English, Arabic, Hebrew, Persian, or Urdu. Choose a component's `messages` catalog from the product locale, or pass its direct label props. The exported Arabic catalogs are conveniences, not RTL defaults.
+
+Without an explicit prop or provider, server output uses a stable LTR snapshot. After hydration, one shared subscription per document synchronizes consumers with the nearest nested boundary or document root. This avoids hydration mismatches and per-component document observers. For an RTL first paint, provide the request-known direction during SSR.
+
+Use logical CSS properties (`start`, `end`, `margin-inline`, `padding-inline`) and `dir="auto"` for user-authored copy. Test mixed-language content, punctuation, numbers, icon mirroring, arrow-key behavior, focus order, portal content, and screen-reader names in every supported direction and locale combination.

package/docs/design-system/form-recipes.md

@@ -0,0 +1,73 @@
+# Form Recipes
+
+## Labeled field with validation
+
+Compose `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, and `FieldError`. Associate the input with its label, keep help text stable, and announce errors only when validation has run.
+
+```tsx
+<Field invalid={Boolean(error)}>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <FieldControl>
+    <Input id="email" state={error ? "error" : "default"} />
+  </FieldControl>
+  <FieldDescription>Use your work email.</FieldDescription>
+  {error ? <FieldError>{error}</FieldError> : null}
+</Field>
+```
+
+## Selection and dates
+
+Use `Select` for a bounded option set, `Autocomplete` for searchable options, and `DatePicker`/`DateRangePicker` for calendar input. Controlled values are preferred when validation, persistence, or URL state owns the result.
+
+Do not emulate a date field with `Input`, a typed `@`, or a generic trailing icon. The Date Picker owns the calendar affordance, keyboard behavior, formatted value, and the same semantic density contract as the surrounding controls.
+
+## Golden recipe: collection filter bar
+
+Use the complete [`CollectionFilterBarDemo`](../../registry/examples/collection-filter-bar-demo.tsx) recipe for collection and search screens. It establishes the approved composition:
+
+- `ToolbarSearch` is full width and uses `shortcutKeys={["Mod", "F"]}` so Command and Control resolve by platform.
+- `DatePicker` owns the From and To fields.
+- `Select` owns Type and Order; `ToolbarSelect` is only a trigger-shaped primitive and is not a complete menu.
+- Every control declares `density="default"`; responsive width classes do not replace component height, padding, radius, or typography.
+- The Reset action uses the same density and resets all composed controls.
+
+```tsx
+<form aria-label="Collection filters" data-recipe="collection-filter-bar">
+  <ToolbarSearch
+    aria-label="Search bookmarks"
+    density="default"
+    shortcutKeys={["Mod", "F"]}
+    width="full"
+  />
+  <div className="flex flex-wrap items-end gap-3">
+    <DatePicker density="default" triggerProps={{ "aria-label": "From" }} />
+    <DatePicker density="default" triggerProps={{ "aria-label": "To" }} />
+    <Select density="default" value="Everything">{/* items */}</Select>
+    <Select density="default" value="Recently bookmarked">{/* items */}</Select>
+    <ToolbarButton density="default" type="reset" variant="link">Reset</ToolbarButton>
+  </div>
+</form>
+```
+
+## Golden recipe: results toolbar
+
+Use the complete [`ResultsToolbarDemo`](../../registry/examples/results-toolbar-demo.tsx) recipe for result counts, layout selection, and batch actions. `SegmentedControl` is the approved content-width primitive for small mutually exclusive values such as cards per row.
+
+```tsx
+<Toolbar aria-label="Bookmark results" layout="split" wrap>
+  <ToolbarText density="default"><strong>5,371</strong>&nbsp;bookmarks</ToolbarText>
+  <ToolbarSection align="end" wrap>
+    <SegmentedControl aria-label="Cards per row" defaultValue="4" density="default">
+      <SegmentedControlLabel>Cards / row</SegmentedControlLabel>
+      {[3, 4, 5, 6].map((count) => (
+        <SegmentedControlItem key={count} value={String(count)}>{count}</SegmentedControlItem>
+      ))}
+    </SegmentedControl>
+    <ToolbarButton density="default" variant="outline">Select</ToolbarButton>
+  </ToolbarSection>
+</Toolbar>
+```
+
+## RTL forms
+
+Set direction at the form or application boundary. Labels and helper text use logical alignment; OTP, calendar, pagination, and selection keyboard movement resolve the inherited direction. Localize labels, placeholders, validation messages, date formatting, and number formatting in the product layer.

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

@@ -0,0 +1,21 @@
+# Gap promotion policy
+
+Every visual-QA background records missing components, assets, composition patterns, and tokens as structured gap metadata. The promotion report groups recurring needs across backgrounds and flags any normalized need seen in three or more distinct scenarios.
+
+Run:
+
+```sh
+npm --prefix playground run report:gap-promotions
+```
+
+The generated [Gap Promotion Report](./gap-promotion-report.md) is checked during background tests. Common needs are classified automatically; add `promotionKey` to a gap when two differently worded gaps represent the same reusable need or when a heuristic would group unrelated needs.
+
+A candidate does not automatically become a component. Promotion requires:
+
+1. Evidence from at least three backgrounds.
+2. A smallest-stable API and explicit fit/avoid guidance.
+3. Semantic density, state, accessibility, and RTL contracts where applicable.
+4. Migration of at least one real background away from its local fallback.
+5. Behavior and visual tests before resolved gap metadata is removed.
+
+The first application of this policy produced `SegmentedControl`, migrated the CRM Intelligence background to the shared primitive, and removed its former local segmented-control gap.