banhaten 0.1.3 → 0.2.0

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

@@ -79,3 +79,17 @@ 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 |
+| `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` |
+<!-- 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-component-default`, `--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-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-component-default` |
+| `variants` | `dark`, `default` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,44 @@
+# 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.
+
+Components consume the semantic alias that describes purpose rather than selecting a visual step directly. The Shadows documentation groups aliases under their canonical effect and distinguishes surface elevation, control strokes, focus rings, overlay elevation, and intentional `none` values.

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.

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

@@ -0,0 +1,166 @@
+# Gap promotion report
+
+This file is generated from background scenario gap metadata. A candidate appears when the same normalized need occurs in at least three distinct backgrounds. Heuristics cover common shells, navigation, tables, steps, composers, timelines, assets, and elevation; use `promotionKey` on a gap when an explicit cross-background grouping is more accurate.
+
+Scanned 194 gaps across 36 backgrounds. Found 8 promotion candidates at the 3-background threshold.
+
+## Application/workspace shell
+
+Key: `application-workspace-shell` · 20 backgrounds
+
+Backgrounds: `accounting-workspace-setup`, `acme-finance-advisor`, `ai-node-detail`, `audit-log`, `bauhow-room-planning`, `benefits-enrollment`, `data-source-browser`, `debt-payoff`, `delivery-tracking`, `hooch-storefront-dashboard`, `inference-providers`, `marcohr-people`, `order-shipment-timeline`, `people-add-member`, `quran-audio-add-employee`, `recent-orders`, `school-assignments`, `shipment-list`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `accounting-workspace-setup` | onboarding workspace shell (`setup-onboarding-shell`) | layout/composition pattern | missing |
+| `acme-finance-advisor` | finance advisor workspace shell (`acme-finance-workspace-shell`) | layout/composition pattern | missing |
+| `ai-node-detail` | node graph workspace shell (`node-graph-workspace-shell`) | layout/composition pattern | missing |
+| `audit-log` | audit browser workspace shell (`audit-browser-workspace-shell`) | layout/composition pattern | missing |
+| `bauhow-room-planning` | room-planning workspace shell (`room-planning-workspace-shell`) | layout/composition pattern | missing |
+| `benefits-enrollment` | benefits enrollment screen shell (`angled-benefits-screen-shell`) | layout/composition pattern | missing |
+| `data-source-browser` | desktop browser and app-shell scene (`desktop-browser-and-app-shell-scene`) | layout/composition pattern | missing |
+| `debt-payoff` | finance workspace shell (`finance-workspace-shell`) | layout/composition pattern | missing |
+| `delivery-tracking` | delivery tracking dashboard shell (`delivery-tracking-dashboard-shell`) | layout/composition pattern | missing |
+| `hooch-storefront-dashboard` | storefront dashboard workspace shell (`hooch-workspace-shell`) | layout/composition pattern | missing |
+| `inference-providers` | inference settings workspace shell (`settings-workspace-shell`) | layout/composition pattern | missing |
+| `marcohr-people` | HR workspace shell (`marcohr-workspace-shell`) | layout/composition pattern | missing |
+| `order-shipment-timeline` | cropped order workspace shell (`cropped-order-workspace-shell`) | layout/composition pattern | missing |
+| `people-add-member` | HR workspace shell (`people-hr-workspace-shell`) | layout/composition pattern | missing |
+| `quran-audio-add-employee` | people-and-culture workspace shell (`quran-audio-workspace-shell`) | layout/composition pattern | missing |
+| `recent-orders` | orders dashboard workspace shell (`recent-orders-workspace-shell`) | layout/composition pattern | missing |
+| `school-assignments` | school app workspace shell (`school-app-workspace-shell`) | layout/composition pattern | missing |
+| `shipment-list` | shipment management workspace shell (`shipment-list-workspace-shell`) | layout/composition pattern | missing |
+| `sku-management` | SKU management workspace shell (`sku-management-workspace-shell`) | layout/composition pattern | missing |
+| `stripe-demo-account` | payments dashboard shell (`payments-dashboard-shell`) | layout/composition pattern | missing |
+
+## Brand and product icon assets
+
+Key: `brand-icon-assets` · 16 backgrounds
+
+Backgrounds: `ai-growth-marketing`, `ai-node-detail`, `bauhow-room-planning`, `crm-intelligence`, `data-source-browser`, `debt-payoff`, `email-compose`, `inference-providers`, `investor-profile`, `model-overview`, `mora-attio-integration`, `order-shipment-timeline`, `profile-menu`, `refund-simulation`, `shipment-list`, `sku-management`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `ai-growth-marketing` | AI provider and company marks (`ai-provider-and-company-marks`) | icon asset | missing |
+| `ai-node-detail` | node and action icon assets (`node-directional-provider-icons`) | icon asset | approximation |
+| `bauhow-room-planning` | Bauhow brand and navigation glyphs (`room-planning-brand-glyphs`) | icon asset | approximation |
+| `crm-intelligence` | brand logo mark (`brand-logo-mark`) | icon asset | missing |
+| `data-source-browser` | Programa and vendor glyphs (`programa-and-vendor-glyphs`) | icon asset | missing |
+| `debt-payoff` | finance brand and navigation glyphs (`finance-brand-glyphs`) | icon asset | approximation |
+| `email-compose` | verified badge and model mark (`verified-badge-and-model-mark`) | icon asset | missing |
+| `inference-providers` | provider brand marks (`provider-brand-marks`) | icon asset | approximation |
+| `investor-profile` | verification and brand marks (`verification-and-brand-marks`) | icon asset | missing |
+| `model-overview` | Mistral logo (`mistral-logo`) | icon asset | missing |
+| `mora-attio-integration` | Mora and Attio brand marks (`mora-attio-brand-assets`) | icon asset | approximation |
+| `order-shipment-timeline` | carrier mark (`carrier-mark`) | icon asset | missing |
+| `profile-menu` | reference icon family (`reference-icon-family`) | icon asset | missing |
+| `refund-simulation` | customer identity glyph (`customer-identity-glyph`) | icon asset | missing |
+| `shipment-list` | carrier brand mark (`shipment-carrier-brand-mark`) | icon asset | approximation |
+| `sku-management` | product and assistant icon set (`sku-product-icons`) | icon asset | approximation |
+
+## Sidebar navigation
+
+Key: `sidebar-navigation` · 11 backgrounds
+
+Backgrounds: `acme-finance-advisor`, `ai-growth-marketing`, `audit-log`, `bauhow-room-planning`, `data-source-browser`, `debt-payoff`, `marcohr-people`, `people-add-member`, `shipment-list`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `acme-finance-advisor` | compact app sidebar navigation (`acme-sidebar-navigation`) | component | missing |
+| `ai-growth-marketing` | report sidebar navigation (`report-sidebar-navigation`) | component | missing |
+| `audit-log` | audit sidebar navigation (`audit-sidebar-navigation`) | component | missing |
+| `bauhow-room-planning` | planning sidebar navigation (`room-planning-sidebar-navigation`) | component | missing |
+| `data-source-browser` | sidebar navigation with pinned list (`sidebar-navigation-with-pinned-list`) | component | missing |
+| `debt-payoff` | planning sidebar navigation (`planning-sidebar-navigation`) | component | missing |
+| `marcohr-people` | HR sidebar navigation (`marcohr-sidebar-navigation`) | component | missing |
+| `people-add-member` | HR sidebar navigation (`people-sidebar-navigation`) | component | missing |
+| `shipment-list` | shipment sidebar navigation (`shipment-sidebar-navigation`) | component | missing |
+| `sku-management` | cropped app sidebar navigation (`sku-sidebar-navigation`) | component | missing |
+| `stripe-demo-account` | payments sidebar navigation (`payments-sidebar-navigation`) | component | missing |
+
+## Data table pattern
+
+Key: `data-table-pattern` · 10 backgrounds
+
+Backgrounds: `audit-log`, `debt-payoff`, `inference-providers`, `marcohr-people`, `people-add-member`, `recent-orders`, `school-assignments`, `share-of-voice`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `audit-log` | audit activity table (`audit-activity-table`) | component | missing |
+| `debt-payoff` | debt table and pagination (`debt-table-and-pagination`) | component | approximation |
+| `inference-providers` | expandable provider configuration table (`expandable-provider-table`) | component | missing |
+| `marcohr-people` | employee policy table (`marcohr-employee-table`) | component | approximation |
+| `people-add-member` | people table with status rows (`people-table-and-status-rows`) | component | approximation |
+| `recent-orders` | orders table controls and rows (`orders-table-region`) | component | approximation |
+| `school-assignments` | assignments table (`assignments-table`) | component | missing |
+| `share-of-voice` | analytics table density (`share-of-voice-analytics-table`) | component | approximation |
+| `sku-management` | SKU data table and pagination (`sku-data-table`) | component | approximation |
+| `stripe-demo-account` | metric table cards (`metric-table-cards`) | component | approximation |
+| `stripe-demo-account` | sales tabs and table (`sales-tabs-and-table`) | component | approximation |
+
+## Elevation/blur semantic effects
+
+Key: `elevation-effects` · 10 backgrounds
+
+Backgrounds: `ai-growth-marketing`, `audit-log`, `data-source-browser`, `email-compose`, `investor-profile`, `model-overview`, `profile-menu`, `refund-simulation`, `school-assignments`, `share-of-voice`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `ai-growth-marketing` | near-black overlay and chart glow (`near-black-overlay-and-chart-glow`) | token | missing |
+| `audit-log` | audit blur and elevation (`audit-blur-and-elevation`) | token | missing |
+| `data-source-browser` | browser chrome radius and elevation (`browser-chrome-radius-and-elevation`) | token | missing |
+| `email-compose` | large composer radius/elevation (`large-composer-radius-elevation`) | token | missing |
+| `investor-profile` | large card radius and soft elevation (`large-card-radius-and-soft-elevation`) | token | missing |
+| `model-overview` | backdrop blur and modal elevation (`backdrop-blur-and-modal-elevation`) | token | missing |
+| `profile-menu` | large radius and reflection elevation (`large-radius-and-reflection-elevation`) | token | missing |
+| `refund-simulation` | warm canvas and large elevation (`warm-canvas-and-large-elevation`) | token | missing |
+| `school-assignments` | warm dark backdrop and oversized shadow (`warm-dark-backdrop-and-oversized-shadow`) | token | missing |
+| `share-of-voice` | dark translucent elevation and reflection (`share-of-voice-dark-elevation`) | token | approximation |
+
+## Avatar image assets
+
+Key: `avatar-image-assets` · 9 backgrounds
+
+Backgrounds: `delivery-tracking`, `investor-profile`, `mcp-settings`, `profile-menu`, `recent-orders`, `refund-simulation`, `remove-model`, `school-assignments`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `delivery-tracking` | courier avatar asset (`delivery-courier-avatar-asset`) | image asset | approximation |
+| `investor-profile` | avatar artwork (`avatar-artwork`) | image asset | missing |
+| `mcp-settings` | account avatar badge (`account-avatar-badge`) | image asset | missing |
+| `profile-menu` | avatar and hand cursor (`avatar-and-hand-cursor`) | image asset | missing |
+| `recent-orders` | brand mark and customer avatar (`recent-orders-brand-avatar-assets`) | image asset | approximation |
+| `refund-simulation` | agent blue mosaic avatar (`agent-blue-mosaic-avatar`) | image asset | missing |
+| `remove-model` | user and provider avatar crops (`remove-model-provider-assets`) | image asset | approximation |
+| `school-assignments` | teacher avatar (`teacher-avatar`) | image asset | missing |
+| `stripe-demo-account` | Stripe mark and account avatar (`stripe-brand-and-avatar-assets`) | image asset | approximation |
+
+## Progress/step indicator
+
+Key: `progress-step-indicator` · 5 backgrounds
+
+Backgrounds: `accounting-workspace-setup`, `benefits-enrollment`, `mcp-settings`, `quran-audio-add-employee`, `refund-simulation`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `accounting-workspace-setup` | step progress indicator (`setup-progress-indicator`) | component | approximation |
+| `benefits-enrollment` | enrollment progress header (`enrollment-progress-header`) | component | missing |
+| `mcp-settings` | numbered setup steps (`numbered-setup-steps`) | component | missing |
+| `quran-audio-add-employee` | three-step employee progress indicator (`quran-audio-progress-stepper`) | component | approximation |
+| `refund-simulation` | refund progress timeline (`refund-progress-timeline`) | component | missing |
+
+## Composer pattern
+
+Key: `composer-pattern` · 3 backgrounds
+
+Backgrounds: `acme-finance-advisor`, `email-compose`, `order-shipment-timeline`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `acme-finance-advisor` | advisor prompt composer (`acme-advisor-composer`) | component | approximation |
+| `email-compose` | compose modal shell (`compose-modal-shell`) | layout/composition pattern | missing |
+| `order-shipment-timeline` | note composer (`note-composer`) | component | missing |
+
+## Review rule
+
+A report entry is a prioritization signal, not automatic authorization to add a primitive. Review the mapped backgrounds, define the smallest stable API, migrate at least one real background, and remove the resolved gap metadata only after behavior, RTL, accessibility, and visual checks pass.

package/docs/design-system/installation.md

@@ -0,0 +1,68 @@
+# Installation
+
+## Requirements
+
+Banhaten installs source into a React 18.2/19 project using Tailwind CSS 4. Use Node 18.18 or newer.
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+```
+
+Run the package-manager command printed by the CLI. It detects npm, pnpm, Yarn, and Bun from `packageManager` or lockfiles.
+
+Dependency declarations are validated with npm-compatible semantic-version
+ranges. A consumer range is kept only when every version it allows satisfies the
+Banhaten requirement. If the Banhaten range is wholly contained by a broader
+consumer range, the CLI safely narrows the declaration in its existing package
+section, updates `package.json`, and prints an install command so the package
+manager can reconcile its lockfile. Partial overlaps, disjoint ranges, mutable
+tags, workspace protocols, aliases, Git URLs, and local file specs fail without
+writing. Banhaten deliberately does not treat a current lockfile resolution as a
+durable compatibility guarantee. When the manifest is already safe, the CLI also
+checks package versions inside the target project or declared workspace boundary.
+For npm lockfiles v2 and v3 it verifies the importer declarations and exact locked
+resolutions; stale, missing, incompatible, or opaque lock state keeps the install
+action visible. Machine-readable output exposes the same
+`{ required, command, cwd }` state, including the project or workspace directory
+where the command must run.
+
+## Vite
+
+Before writing, the CLI resolves a canonical install plan from
+`banhaten.config.json`, the TypeScript `@/*` path, and the Vite `@` alias. If
+TypeScript and Vite agree, that root is used even when another `src` directory
+exists. If only one side declares the alias, the CLI mirrors it to the other.
+Conflicting roots, multi-target TypeScript paths, destination-overlapping aliases,
+inherited TypeScript aliases without local `baseUrl`/`paths`, and Vite aliases
+that cannot be inspected statically fail without changing the project. When a
+supported Vite config exists, `init` also adds the Tailwind Vite plugin while
+preserving its existing structure.
+
+CLI commands use strict schemas. Unknown or duplicate flags, missing values, and
+unexpected positional arguments are rejected before project discovery. The
+install receipt pins the resolved destinations; changing roots later requires
+moving or removing the old generated files and receipt first.
+
+## Next.js and other frameworks
+
+Without Vite, the CLI installs Tailwind and writes the configured global stylesheet, aliases, `cn` utility, and direction hook. Import the generated global stylesheet from the framework root layout and ensure the `@/*` TypeScript alias resolves to the source directory.
+
+## Fonts and direction
+
+The generated stylesheet imports Inter weights 400–700 and IBM Plex Sans Arabic weights 400–700. Set document language and direction at the application boundary:
+
+```tsx
+<html lang="ar" dir="rtl" data-theme="blue" data-radius="default">
+```
+
+Wrap server-rendered component trees in `DirectionProvider` when request data already determines the direction; this keeps the first server and client snapshots identical. It is also the boundary for nested surfaces that differ from the document. Without it, components hydrate from a stable LTR snapshot and then synchronize from the document through one shared observer.
+
+## Updating safely
+
+```bash
+npx banhaten diff
+npx banhaten update
+```
+
+The receipt records generated hashes. Unmodified files update automatically. Locally modified files and token blocks stop without writing; pass `--force` only after reviewing the unified diff. Put product overrides outside the marked token block and product composition in wrapper components.