banhaten 0.4.0 → 0.6.0

package/docs/design-system/components/thinking-reasoning.md

@@ -0,0 +1,72 @@
+# Thinking Reasoning
+
+`ThinkingReasoning` is an animated, collapsible reasoning block. While the agent thinks, a shimmering label sits above sentences that reveal in sequence and auto-scroll behind soft fades. Once the agent is done, the block folds into a "Thought for Ns" summary that unfolds the full, scrollable reasoning on demand.
+
+The component is data-driven: append sentences to `steps` as they arrive and flip `status` to `done` when the model stops. Scripted timers belong in examples, not in the component.
+
+## API
+
+```tsx
+import { ThinkingReasoning } from "@/components/ui/thinking-reasoning"
+
+<ThinkingReasoning
+  duration={5}
+  status={done ? "done" : "thinking"}
+  steps={sentences}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` | `readonly string[]` | – | Reasoning sentences in arrival order. Each row clamps to two lines. |
+| `status` | `"thinking" \| "done"` | `"thinking"` | Thinking keeps the block open and auto-scrolling; done folds it into the summary. |
+| `duration` | `number` | measured | Seconds shown in the summary. Measured from the first thinking render when omitted; a block that mounts already done shows the verb alone. |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | Controls whether the finished reasoning is unfolded. |
+| `reserveSpace` | `boolean` | `false` | Keeps the block height stable while folding so content below does not jump. |
+| `labels` | `Partial<ThinkingReasoningLabels>` | English | `thinking`, `thought`, and `duration(seconds)` copy. The finished summary also names the toggle. |
+
+## Install
+
+```bash
+npx banhaten add thinking-reasoning
+```
+
+## Examples
+
+Primary registry example: `examples/thinking-reasoning-demo.tsx`.
+
+## Token Contract
+
+Width and the capped viewport come from `--bh-thinking-reasoning-width`, `--bh-thinking-reasoning-max-height`, and `--bh-thinking-reasoning-fade`. Sentences use the `body-xs` scale, the header uses `body-xs-medium`, and colors resolve through `--bh-content-subtle` for the verb and sentences and `--bh-content-muted` for the duration and chevron. Motion uses the `--bh-duration-*` foundation tokens with `--bh-easing-emphasized`.
+
+Covered source files: `components/thinking-reasoning.tsx`, `components/thinking-reasoning.css`, and the `collapsible` and `shimmer-text` registry dependencies.
+
+## RTL Rules
+
+- The block inherits document direction; the header, chevron, and sentence text use logical alignment.
+- Auto-scroll, fades, and the fold are vertical and therefore direction-neutral.
+
+## Accessibility
+
+The header is a Collapsible trigger with `aria-expanded` and `aria-controls`, and folded reasoning unmounts after its closing animation. It is disabled while thinking, when there is nothing to toggle, and once done becomes the summary toggle, named by the summary it shows, such as "Thought for 5s". The live label announces the thinking state politely. When unfolded, the reasoning viewport is keyboard scrollable. The reveal, fade, and fold animations collapse to instant changes under `prefers-reduced-motion`.
+
+<!-- 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/thinking-reasoning.tsx: ThinkingReasoning` |
+| `parts` | `ThinkingReasoning` |
+| `registryDependencies` | `collapsible`, `shimmer-text` |
+| `props.steps` | `readonly string[]; default null; Reasoning sentences in arrival order; append to stream new ones.` |
+| `props.status` | `"thinking" \| "done"; default "thinking"; Thinking keeps the block open and auto-scrolling; done folds it into the summary.` |
+| `props.duration` | `number; default "measured"; Seconds shown in the summary; measured from mount when omitted.` |
+| `props.open` | `boolean; default "false"; Controls whether the finished reasoning is unfolded.` |
+| `props.reserveSpace` | `boolean; default "false"; Keeps the block height stable while folding so content below does not jump.` |
+| `props.labels` | `Partial<ThinkingReasoningLabels>; default "English"; Localized thinking, thought, and duration copy; the finished summary also names the toggle.` |
+| `states` | `thinking`, `done`, `open`, `closed` |
+| `tokens` | `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-fast`, `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-duration-slower`, `--bh-easing-emphasized`, `--bh-easing-standard`, `--bh-font-family`, `--bh-icon-stroke-180`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-sm-4`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--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-thinking-reasoning-fade`, `--bh-thinking-reasoning-max-height`, `--bh-thinking-reasoning-width`, `--elevation-component-focus-ring` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,67 @@
+# Thinking State
+
+`ThinkingState` is the smallest AI status surface: a shimmering label that tells the user the agent is working before its first token arrives. The shimmer comes from [Shimmer Text](./shimmer-text.md), so labels, active task rows, and enhancing prompts all move the same way.
+
+Use Thinking State for the pre-response beat in a conversation. Use Thinking Reasoning when the agent exposes intermediate reasoning, and Spinner for ordinary non-AI loading.
+
+## API
+
+```tsx
+import { ThinkingState } from "@/components/ui/thinking-state"
+
+<ThinkingState />
+<ThinkingState status="done">Thought</ThinkingState>
+<ThinkingState>جارٍ التفكير</ThinkingState>
+```
+
+`ThinkingState` renders a polite live region with `role="status"`. Its `status` prop matches Thinking Reasoning's, so one flag drives both.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `status` | `"thinking" \| "done"` | `"thinking"` | Thinking runs the brightness sweep; done leaves the label as static text. |
+| `tone` | `"subtle" \| "default"` | `"subtle"` | Secondary or primary text color pair for the sweep. |
+| `children` | `React.ReactNode` | `"Thinking"` | Localized label text. |
+
+## Install
+
+```bash
+npx banhaten add thinking-state
+```
+
+## Examples
+
+Primary registry example: `examples/thinking-state-demo.tsx`.
+
+## Token Contract
+
+Typography uses the `body-xs-medium` scale in `--bh-content-subtle`. The shimmer colors and sweep come from the `shimmer-text` registry dependency.
+
+Covered source files: `components/thinking-state.tsx`, `components/thinking-state.css`, and the `shimmer-text` registry dependency.
+
+## RTL Rules
+
+- The label inherits document direction.
+- The shine sweeps from the reading start to the reading end, so RTL text uses mirrored keyframes automatically.
+
+## Accessibility
+
+`ThinkingState` announces once through `aria-live="polite"`. The shimmer is purely decorative: under `prefers-reduced-motion` it renders as static text in the base color with no gradient.
+
+<!-- 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/thinking-state.tsx: ThinkingState` |
+| `parts` | `ThinkingState` |
+| `registryDependencies` | `shimmer-text` |
+| `props.status` | `"thinking" \| "done"; default "thinking"; Thinking runs the brightness sweep; done leaves the label as static text.` |
+| `props.tone` | `"subtle" \| "default"; default "subtle"; Secondary or primary text color pair for the sweep.` |
+| `props.children` | `React.ReactNode; default "\"Thinking\""; Localized label text.` |
+| `states` | `thinking`, `done` |
+| `tokens` | `--bh-content-subtle`, `--bh-font-family`, `--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` |
+| `tones` | `subtle`, `default` |
+<!-- registry-contract:end -->

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

@@ -93,6 +93,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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` |
+| `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`, `--elevation-component-focus-ring` |
 | `variants` | `default`, `icon` |
 <!-- registry-contract:end -->

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

@@ -69,5 +69,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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` |
+| `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`, `--elevation-component-default` |
 <!-- registry-contract:end -->

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

@@ -45,7 +45,7 @@ Toggle uses the existing Banhaten switch aliases:
 | Disabled track | `--bh-interactive-switch-disabled` |
 | Handle | `--bh-interactive-switch-handle` |
 | Disabled handle | `--bh-interactive-switch-handle-disabled` |
-| Focus ring | `--shadow-social-button-focus-ring` |
+| Focus ring | `--elevation-social-button-focus-ring` |
 
 Text uses body-md for labels and body-xs for supporting text. ToggleField uses logical start/end placement so label order and thumb motion mirror in RTL.
 
@@ -92,5 +92,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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` |
+| `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`, `--elevation-03`, `--elevation-social-button-focus-ring` |
 <!-- registry-contract:end -->

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

@@ -1,6 +1,6 @@
 # Toolbar
 
-Toolbar is the token-built implementation of the Figma `Filter Toolbar` component set. It supports eight filter/action layouts, desktop and mobile wrapping, and inherited LTR/RTL direction.
+Toolbar is the token-built implementation of the Figma `Filter Toolbar` component set. It supports eight filter/action layouts, desktop and mobile wrapping, inherited LTR/RTL direction, and layout-group semantics that preserve each control's native Tab and arrow-key behavior.
 
 ## Install
 
@@ -10,7 +10,7 @@ npx banhaten add toolbar
 
 ## Anatomy
 
-- `Toolbar`: root layout surface with `inline`, `split`, `stack`, and `wrap` modes.
+- `Toolbar`: root layout surface with `inline`, `split`, `stack`, and `wrap` modes. It defaults to `role="group"`, not the composite-widget `toolbar` role.
 - `ToolbarSection`: grouped start, end, wrapped, or stacked control regions.
 - `ToolbarSearch`: tokenized search input using Banhaten input height, radius, typography, and focus ring.
 - `ToolbarSelect`: button-backed filter trigger using select/input tokens.
@@ -34,7 +34,7 @@ import {
 
 export function Example() {
   return (
-    <Toolbar layout="split" wrap>
+    <Toolbar aria-label="Object filters and actions" layout="split" wrap>
       <ToolbarSection grow wrap>
         <ToolbarSearch aria-label="Search objects" />
         <ToolbarSelect value="Status" />
@@ -53,7 +53,7 @@ export function Example() {
 
 ## Token Contract
 
-Toolbar styling is derived from the existing control tokens: `--bh-input-lg-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-select-width`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-control-default`, input/select/button shadows, and semantic content/interactive tokens.
+Toolbar styling is derived from the existing control tokens: `--bh-input-lg-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-select-width`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-control-default`, input/select/button elevation, and semantic content/interactive tokens.
 
 ## RTL
 
@@ -67,6 +67,7 @@ Supported runtime exports: `Toolbar`, `ToolbarBadge`, `ToolbarButton`, `ToolbarF
 | --- | --- |
 | `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
 | `layouts` | `inline`, `split`, `stack`, `wrap` |
+| `role` | Defaults to `group`; explicit overrides are forwarded. |
 
 ## Examples
 
@@ -82,7 +83,9 @@ 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.
+`Toolbar` defaults to `role="group"` because it is a flexible layout surface, not a composite widget. The root is not a tab stop, every enabled control remains in the native Tab sequence, and the component does not intercept arrow keys used by search fields, selects, or nested widgets. Give the group an accessible name when its purpose is not already clear from surrounding content.
+
+Only override the root with `role="toolbar"` when the application also implements the complete [W3C Toolbar Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/): one Tab stop into the widget, managed arrow-key focus between controls, an accessible name, and orientation behavior. The role override alone does not add that keyboard model.
 
 <!-- registry-contract:start -->
 ## Registry Contract
@@ -97,9 +100,11 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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.` |
+| `props.role` | `React.AriaRole; default "group"; Uses layout-group semantics and native Tab order by default. Applications that override this to toolbar own the complete roving-focus and arrow-key contract.` |
 | `breakpoints` | `desktop`, `mobile` |
 | `densities` | `compact`, `default`, `comfortable` |
+| `features` | `native Tab-order layout grouping` |
 | `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-icon-slot-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` |
+| `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-icon-slot-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`, `--elevation-button-danger-focus`, `--elevation-button-focus`, `--elevation-button-raised`, `--elevation-button-soft`, `--elevation-input`, `--elevation-input-focus-ring`, `--elevation-select-trigger` |
 <!-- registry-contract:end -->

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

@@ -1,6 +1,6 @@
 # Tooltip
 
-Tooltip is a Radix Tooltip-backed help surface matched to the Figma tooltip matrix. It supports dark and default surfaces, small and large sizes, shortcut and close slots, logical pointer positions, tokenized shadows, and RTL-safe layout.
+Tooltip is a Radix Tooltip-backed help surface matched to the Figma tooltip matrix. It supports dark and default surfaces, small and large sizes, shortcut and close slots, logical pointer positions, tokenized elevation, and RTL-safe layout.
 
 ## Install
 
@@ -14,7 +14,7 @@ npx banhaten add tooltip
 - `Tooltip`: root tooltip wrapper.
 - `TooltipTrigger`: trigger element.
 - `TooltipContent`: positioned surface with pointer, title, support text, shortcut, and close affordance.
-- `TooltipShortcut`: shortcut slot.
+- `TooltipShortcut`: direction-isolated physical shortcut slot.
 - `TooltipCloseButton`: optional close affordance.
 
 ## Example
@@ -55,7 +55,7 @@ export function Example() {
 
 ## RTL
 
-Tooltip content uses inherited direction and `dir="auto"` text. Top and bottom left/right positions map to logical start/end in RTL, while center-left and center-right remain physical sides to match the Figma matrix.
+Tooltip content uses inherited direction and `dir="auto"` text. `TooltipShortcut` defaults to `dir="ltr"` so physical modifiers and keys do not reorder inside RTL tooltips. Top and bottom left/right positions map to logical start/end in RTL, while center-left and center-right remain physical sides to match the Figma matrix.
 
 ## API
 
@@ -84,6 +84,7 @@ Covered source files: `components/tooltip.tsx`.
 - `spacing`: Uses inherited direction with flex layout so label/shortcut and text/close order mirror naturally.
 - `pointerPlacement`: Top and bottom left/right positions map to logical start/end in RTL. Center-left and center-right remain physical sides to match the Figma matrix.
 - `textDirection`: Labels and support text use dir="auto" for Arabic and English copy.
+- `shortcutDirection`: TooltipShortcut defaults to dir="ltr" so physical key order remains stable inside RTL content.
 
 ## Accessibility
 
@@ -100,8 +101,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/tooltip.tsx: Tooltip, TooltipCloseButton, TooltipContent, TooltipPortal, TooltipProvider, TooltipRoot, TooltipShortcut, TooltipTrigger, tooltipContentVariants` |
 | `parts` | `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`, `TooltipPortal`, `TooltipShortcut`, `TooltipCloseButton` |
 | `registryDependencies` | None |
+| `props.dir` | `"ltr" \| "rtl" \| "auto"; default "ltr"; TooltipShortcut only: keeps key glyphs in physical order inside RTL tooltips. Override only for localized non-shortcut text.` |
 | `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` |
+| `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-elevation`, `--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-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`, `--elevation-04`, `--elevation-button-focus` |
 | `variants` | `dark`, `default` |
 <!-- registry-contract:end -->

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

@@ -36,10 +36,10 @@ not silently resize navigation, cards, typography, or unrelated layout spacing.
 
 ## Elevation
 
-Elevation uses two layers:
+Elevation uses two layers in one public namespace:
 
-- General steps: `--shadow-xs` through `--shadow-3xl`.
-- Semantic component aliases: `--shadow-component-*`, focus/danger rings, menus, controls, and component-specific aliases.
+- General steps: `--elevation-01` through `--elevation-07`.
+- Semantic aliases: `--elevation-component-*`, focus/danger rings, menus, controls, and component-specific treatments.
 
 The seven general steps mirror the current Figma `elevation/01` through
 `elevation/07` effect styles in [Shadow tests → With Variables](https://www.figma.com/design/LVAWtr5A5oEcAvsBmk6vdt/Banhaten-Design-system-3.0?node-id=6436-13190).
@@ -47,19 +47,19 @@ The geometry is shared across modes. Figma's bound shadow color variables make
 the dark-mode drops, rings, and highlights stronger, so Banhaten publishes a
 separate exact recipe for each mode.
 
-| CSS step | Figma style | Current component roles |
+| CSS token | Figma style | Current component roles |
 | --- | --- | --- |
-| `xs` | `elevation/01` | Flat surfaces with an ambient ring only |
-| `sm` | `elevation/02` | Subtle lift for inner cards, inset panels, and compact raised details |
-| `md` | `elevation/03` | Cards, surfaces, slider thumbs, and toggle handles |
-| `lg` | `elevation/04` | Menus, select menus, popovers, tooltips, and date surfaces |
-| `xl` | `elevation/05` | Sticky and floating surfaces, including floating banners |
-| `2xl` | `elevation/06` | Modals and dialogs |
-| `3xl` | `elevation/07` | Full-overlay surfaces that require maximum depth |
+| `--elevation-01` | `elevation/01` | Flat surfaces with an ambient ring only |
+| `--elevation-02` | `elevation/02` | Subtle lift for inner cards, inset panels, and compact raised details |
+| `--elevation-03` | `elevation/03` | Cards, surfaces, slider thumbs, and toggle handles |
+| `--elevation-04` | `elevation/04` | Menus, select menus, popovers, tooltips, and date surfaces |
+| `--elevation-05` | `elevation/05` | Sticky and floating surfaces, including floating banners |
+| `--elevation-06` | `elevation/06` | Modals and dialogs |
+| `--elevation-07` | `elevation/07` | Full-overlay surfaces that require maximum depth |
 
 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.
+selecting a visual step directly. Focus rings and inset borders remain distinct
+effect recipes, but they share the `--elevation-*` public namespace so there is
+no parallel shadow-token API. CSS `box-shadow` is only the browser rendering
+mechanism. The Elevation documentation distinguishes surface depth, control
+strokes, focus rings, overlay elevation, and intentional `none` values.

package/docs/design-system/design-system-test-missing-items.md

@@ -27,7 +27,7 @@ Date logged: 2026-06-07
 
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
-| 2026-06-07 | Red | layout/composition pattern | onboarding workspace shell | Closest look: a local app shell using raised surfaces, border/radius/shadow tokens, and background gradients until an onboarding shell pattern exists. |
+| 2026-06-07 | Red | layout/composition pattern | onboarding workspace shell | Closest look: a local app shell using raised surfaces, border/radius/elevation tokens, and background gradients until an onboarding shell pattern exists. |
 | 2026-06-07 | Purple | component | step progress indicator | Closest look: Steps or ButtonGroup-style primitives with tokenized pill bars. |
 | 2026-06-07 | Purple | layout/composition pattern | setup form step card | Closest look: actual Banhaten Input, Select, Textarea, RadioCard, and Button primitives inside a local raised form layout. |
 | 2026-06-07 | Purple | layout/composition pattern | inferred cropped continuation | Closest look: infer the cropped lower setup fields with Banhaten Select, RadioCard, and Button primitives. |
@@ -55,11 +55,11 @@ Date logged: 2026-06-07
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
 | 2026-06-07 | Purple | image asset | scenic meadow backdrop | Closest look: a tokenized CSS scenic approximation until a final raster background asset exists. |
-| 2026-06-07 | Red | layout/composition pattern | floating report dashboard scene | Closest look: a local absolute-positioned app shell using Banhaten dark surfaces, borders, spacing, radius, and shadow tokens. |
+| 2026-06-07 | Red | layout/composition pattern | floating report dashboard scene | Closest look: a local absolute-positioned app shell using Banhaten dark surfaces, borders, spacing, radius, and elevation tokens. |
 | 2026-06-07 | Red | component | report sidebar navigation | Closest look: Menu, Badge, Avatar, Button, typography, and icon wrappers composed into a sidebar until an app-sidebar component exists. |
 | 2026-06-07 | Red | component | AI report dashboard cards | Closest look: tokenized surfaces plus local chart/table compositions until dashboard cards and chart components are first-class. |
 | 2026-06-07 | Purple | icon asset | AI provider and company marks | Closest look: Lucide or CSS placeholders inside tokenized icon wrappers until the exact brand/provider assets are added. |
-| 2026-06-07 | Purple | token | near-black overlay and chart glow | Closest look: existing dark theme surfaces, subtle borders, brand/sky accents, and component shadow tokens. |
+| 2026-06-07 | Purple | token | near-black overlay and chart glow | Closest look: existing dark theme surfaces, subtle borders, brand/sky accents, and component elevation tokens. |
 
 ## Benefits Enrollment Background
 
@@ -69,7 +69,7 @@ Date logged: 2026-06-07
 
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
-| 2026-06-07 | Red | layout/composition pattern | angled benefits screen shell | Closest look: local rotated stage using Banhaten background, border, radius, and shadow tokens. |
+| 2026-06-07 | Red | layout/composition pattern | angled benefits screen shell | Closest look: local rotated stage using Banhaten background, border, radius, and elevation tokens. |
 | 2026-06-07 | Red | component | enrollment progress header | Closest look: Steps-style composition with tokenized markers, connector lines, and label typography. |
 | 2026-06-07 | Red | component | personal details review card | Closest look: raised surface, header row, Button action, and nested definition-list panel composed with Banhaten tokens. |
 | 2026-06-12 | Purple | component | definition-list review rows | Closest look: Banhaten Attribute rows inside a tokenized review card surface. |
@@ -82,7 +82,7 @@ Date logged: 2026-06-07
 
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
-| 2026-06-07 | Red | layout/composition pattern | background shell | Closest look: layout primitives with background, border, radius, and shadow tokens; no reusable background shell yet. |
+| 2026-06-07 | Red | layout/composition pattern | background shell | Closest look: layout primitives with background, border, radius, and elevation tokens; no reusable background shell yet. |
 | 2026-06-07 | Red | layout/composition pattern | deal card | Closest look: card-like surface composed from Avatar, Badge, Button, typography, and spacing tokens. |
 | 2026-06-07 | Red | component | icon tile | Closest look: icon-only Button or a small Badge/Icon wrapper using radius, border, and background tokens. |
 | 2026-06-07 | Purple | icon asset | brand logo mark | Closest look: Lucide/CSS placeholder in a tokenized icon tile until the brand asset exists. |
@@ -100,7 +100,7 @@ Date logged: 2026-06-07
 
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
-| 2026-06-07 | Red | layout/composition pattern | modal-over-background scene | Closest look: centered raised surface with local overlay/backdrop CSS, radius, and shadow tokens. |
+| 2026-06-07 | Red | layout/composition pattern | modal-over-background scene | Closest look: centered raised surface with local overlay/backdrop CSS, radius, and elevation tokens. |
 | 2026-06-07 | Red | component | model overview detail panel | Closest look: PageHeader, Badge, Button, Table/list rows, and tokenized surface. |
 | 2026-06-07 | Purple | icon asset | Mistral logo | Closest look: token-colored icon tile or CSS mark until the exact provider asset is added. |
 | 2026-06-07 | Purple | image asset | blurred hero and provider list | Closest look: background image slot or Avatar/icon placeholders inside a muted surface. |
@@ -200,7 +200,7 @@ Date logged: 2026-06-07
 
 | Date logged | Mark | Type | Item | Alternative / closest look |
 | --- | --- | --- | --- | --- |
-| 2026-06-07 | Red | component | transaction detail sheet | Closest look: a raised surface composed from Button, Badge, Avatar, typography, spacing, radius, and shadow tokens until a reusable transaction-detail component exists. |
+| 2026-06-07 | Red | component | transaction detail sheet | Closest look: a raised surface composed from Button, Badge, Avatar, typography, spacing, radius, and elevation tokens until a reusable transaction-detail component exists. |
 | 2026-06-07 | Purple | layout/composition pattern | purple composed detail pieces | Closest look: existing primitives and local tokenized wrappers. Purple marks identify pieces that are acceptable compositions, not red missing components. |
 
 ## Refund Simulation Background
@@ -304,7 +304,7 @@ Date logged: 2026-06-07
 | 2026-06-07 | Red | component | log details modal | Closest look: raised surface using Button, Badge, Avatar, typography, dividers, and local definition-table rows. |
 | 2026-06-07 | Purple | icon asset | audit chrome and sidebar glyphs | Closest look: Lucide icons and CSS browser marks in tokenized icon wrappers. |
 | 2026-06-07 | Purple | image asset | audit author avatars | Closest look: Avatar fallback until production portrait assets are supplied. |
-| 2026-06-07 | Purple | token | audit blur and elevation | Closest look: background, border, radius, opacity, and component-shadow tokens plus local backdrop blur. |
+| 2026-06-07 | Purple | token | audit blur and elevation | Closest look: background, border, radius, opacity, and component-elevation tokens plus local backdrop blur. |
 
 ## Order Shipment Timeline Background
 

package/docs/design-system/installation.md

@@ -66,3 +66,5 @@ 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.
+
+The CLI also checks the original contents of every write target and the files used for ownership checks and merges before and after staging. An intervening edit, creation, or deletion aborts the plan, even with `--force`. Re-run the command after concurrent edits have finished.

package/docs/design-system/tabs.md

@@ -49,5 +49,6 @@ The component consumes Banhaten semantic tokens and component aliases. Do not ha
 - `sm` segment and rounded tabs are `36px` tall inside a `40px` container.
 - `xs` segment and rounded tabs are `32px` tall inside a `36px` container.
 - `md` underline rows are `56px`; `sm` and `xs` underline rows are `48px`.
-- Full-width tabs stretch equally inside their parent width.
+- Full-width tabs stretch equally while every label fits. Intrinsic label width is the minimum; narrower rows scroll horizontally instead of shrinking triggers beneath their copy.
+- Hug-content tabs keep their intrinsic widths and use the same local horizontal overflow behavior under pressure.
 - RTL uses `dir="rtl"` on the tablist so the active first item appears on the right edge.

package/docs/design-system/template-gap-audit.md

@@ -0,0 +1,32 @@
+# Template Gap Audit
+
+Last updated: 2026-08-23
+
+This audit records repeated friction encountered while composing the 60-template catalog. It does not automatically promote every local composition into a component. Candidates should pass the roadmap's reuse, accessibility, direction, and API-stability gates.
+
+## Prioritized findings
+
+| Priority | Missing capability | Evidence from the catalog | Current workaround | Recommended ownership |
+| --- | --- | --- | --- | --- |
+| P1 | Responsive app-shell and layout primitives | Nearly every dashboard, settings, data, and operations page needed the same container, split-pane, metric-grid, and responsive collapse rules | Local CSS grids using spacing and surface tokens | Add documented `Container`, `Stack`, `Cluster`, `Grid`, and `AppShell` layout patterns plus breakpoint/container tokens |
+| P1 | Stat / KPI card pattern | Executive, product, sales, commerce, finance, campaign, and widget designs repeat label/value/change anatomy | Local Card composition with Badge and trend icon | Promote a `StatCard` pattern with value, comparison, intent, sparkline slot, loading state, and RTL-safe trend semantics |
+| P1 | Key-value and summary rows | Checkout, billing, profile, resource detail, transfers, and review flows need dense label/value groupings | Card, Attribute, Divider, and bespoke rows | Add a responsive `DescriptionList` / `SummaryList` pattern with actions, status, truncation, and stacked mode |
+| P1 | Data-visualization recipes | Dashboards and finance screens repeatedly need sparklines, time series, funnels, comparison bars, legends, and no-data states | Raw Recharts composition inside ChartContainer | Publish chart recipes and defaults for sparkline, KPI trend, time series, bar comparison, funnel, legend, tooltip, empty, and loading states |
+| P1 | Amount and currency field | Send money, FX quote, wallets, savings, billing, and checkout all need amount, currency, decimal, and locale behavior | Generic Input plus nearby Badge/Button | Add an `AmountInput` pattern with currency selector, precision rules, localized formatting, min/max, fees, and RTL QA |
+| P2 | Structured commerce form recipes | Checkout and billing need address, card, delivery, tax, and order-summary structures | Generic Input, Checkbox, Card, and Divider composition | Document `AddressForm`, `PaymentMethod`, and `OrderSummary` patterns before considering dedicated components |
+| P2 | Schedule and board patterns | Schedule planner, editorial calendar, hiring pipeline, project board, and room planner could only approximate their core layouts | Cards and lists arranged in local grids | Add accessible calendar/schedule and board patterns with keyboard navigation, overflow, selection, drag alternatives, and mobile behavior |
+| P2 | Rich text and message composer | Shared inbox, conversation, email campaign, and content workflows need recipients, formatting, attachments, variables, and send state | Textarea, Toolbar, Tag, File Upload, and Button assembled locally | Define a `Composer` pattern with slots for recipients, toolbar, variable chips, attachments, drafts, validation, and send status |
+| P2 | Media and asset browser | Product detail and content library need aspect-ratio thumbnails, selection, metadata, upload progress, and preview | Card, Aspect Ratio, File Upload, and generic image assets | Add `MediaCard`, selectable asset grid, and preview-detail patterns; keep storage and transformation product-owned |
+| P2 | Status and health summary | Infrastructure, incidents, shipment, integrations, and widgets repeat status icon, message, metric, and history anatomy | Badge, Alert, Progress, and local icon wrappers | Add `StatusSummary` and `ServiceHealthRow` patterns with severity, timestamp, trend, actions, and accessible non-color cues |
+| P3 | Map and spatial slot guidance | Shipment tracking and room planning cannot express a real map or floor plan with current components | List/detail summaries only | Document a neutral map/canvas host contract and overlay controls; keep the mapping engine and spatial assets outside the design system |
+| P3 | Product illustration and empty-state asset guidance | Authentication, onboarding, commerce, and zero-data moments need richer owned visuals | One existing abstract image plus icon-led Empty State | Define approved illustration ratios, theming, cropping, alt-text, and loading rules; maintain real assets separately from component code |
+
+## What is not missing
+
+Table, File Upload, Empty State, ChartContainer, Page Header, Steps, Sidebar, Modal, Tabs, Toolbar, and the core form controls already provide useful foundations. The friction above is primarily at the composition, recipe, and responsive-layout layers; duplicating those existing primitives would make the system harder to maintain.
+
+## Suggested sequence
+
+1. Stabilize layout primitives, StatCard, SummaryList, chart recipes, and AmountInput because they recur across the largest number of templates.
+2. Validate commerce forms, schedules/boards, Composer, media browser, and status summaries in two real product flows each.
+3. Keep map engines and illustration assets as integration guidance unless repeated product usage reveals a stable design-system API.

package/docs/design-system/templates.md

@@ -0,0 +1,59 @@
+# Templates
+
+Templates are Banhaten's composition tier: reusable page, flow, and widget starting points assembled from the existing token and component contracts. They sit above Components and Patterns, and below product-specific implementation.
+
+The live catalog is available at `#templates` in the playground. It uses a text-first, single-column directory so full application screens are not compressed into competing thumbnails. Search, category, and type filters lead to a dedicated hash route for each template, where one design is shown at full content width with previous/next navigation, composition notes, and starter-code copying. Templates are examples rather than stable registry packages; product data, routing, validation, and domain behavior remain application-owned.
+
+## Tier boundaries
+
+| Tier | Purpose | Examples |
+| --- | --- | --- |
+| Tokens | Visual decisions and modes | Color, type, spacing, radius, elevation |
+| Components | Reusable interaction primitives | Button, Input, Table, Modal, Chart |
+| Patterns | Repeated task-level combinations | Page Header, File Upload, Empty State, Steps |
+| Templates | Page, flow, and widget starting points | Checkout, analytics dashboard, exchange-rate widget |
+| Lab | Screenshot-driven visual and quality experiments | Background tests and comparison workspaces |
+
+Templates do not introduce a second visual language. Every surface, border, state, radius, type style, spacing decision, and shadow resolves through Banhaten's semantic tokens or an existing component contract.
+
+## Research basis
+
+The catalog uses the breadth and taxonomy of established libraries as research inputs, without copying their styling or exact layouts:
+
+- [shadcn/ui Blocks](https://ui.shadcn.com/blocks) separates larger dashboard, authentication, and sidebar compositions from individual components.
+- [Tailwind Plus Application UI](https://tailwindcss.com/plus/ui-blocks/application-ui), [Ecommerce](https://tailwindcss.com/plus/ui-blocks/ecommerce), and marketing collections cover task-specific sections and screens.
+- [Material UI Templates](https://mui.com/material-ui/getting-started/templates/) includes sign-in, checkout, CRUD, dashboard, and marketing starting points.
+- [Carbon Patterns](https://carbondesignsystem.com/patterns/overview/) defines patterns as reusable combinations that help users complete goals and flows.
+- [Shopify App Home patterns](https://shopify.dev/docs/api/app-home/patterns) distinguishes full-page templates from smaller compositions.
+- [Ant Design](https://ant.design/docs/spec/overview/) demonstrates both base components and business-oriented examples.
+
+## Catalog inventory
+
+| Category | Type | Included templates |
+| --- | --- | --- |
+| Authentication | Flow | Centered sign in, Split sign in, Create account, Invite acceptance, Password recovery, Two-step verification |
+| Dashboards | Page | Executive overview, Product analytics, Sales pulse, Support operations, Infrastructure health, Team workload |
+| Finance | Flow | Wallet overview, Send money, Foreign exchange quote, Crypto portfolio, Card controls, Savings plan |
+| Commerce | Page | Storefront overview, Product detail, Catalog manager, Cart summary, Checkout flow, Order tracking |
+| Data | Page | Resource index, Resource detail, Data source browser, Import mapping, Audit log, Approval queue |
+| Collaboration | Page | Team directory, Activity center, Shared inbox, Conversation detail, Project board, Meeting agenda |
+| Operations | Page | Shipment tracking, Schedule planner, Incident response, Hiring pipeline, Benefits enrollment, Room planner |
+| Settings & Admin | Page | Profile settings, Security settings, Billing settings, Notification preferences, Workspace members, Integrations hub |
+| Marketing & Content | Page | Campaign overview, Email composer, Editorial calendar, Content library, Launch checklist, Customer story |
+| Widgets | Widget | Metric comparison, Conversion funnel, Task progress, Exchange rate, Server status, Recent transactions |
+
+Total: 60 templates across 10 categories.
+
+## Quality contract
+
+- A template must remain legible in LTR and RTL and in light and dark modes.
+- The catalog must show template names and descriptions as a directory; full template canvases appear only on their dedicated pages.
+- Template chrome and previews use Banhaten tokens; raw colors, bespoke shadows, and copied external CSS are not allowed.
+- Inputs and other form controls inherit Banhaten's default `lg` density. Compact controls are reserved for genuinely constrained desktop tables and toolbars, never as a way to squeeze a template into its preview.
+- Product imagery must come from a real owned asset. Icons use the supported icon family.
+- Visible controls in the gallery's main journey work: search, filters, pagination, preview, close, mode selection, and copy.
+- Repeated composition friction is recorded in the [template gap audit](./template-gap-audit.md) before a new component or pattern is proposed.
+
+## Promotion path
+
+A template can become an installable `registry:block` only after it has a stable public composition API, realistic data and empty/loading/error states, accessibility and direction tests, documentation, and evidence of reuse in more than one product context. Until then, the catalog remains an exploration and adoption aid rather than generated source ownership.

package/docs/design-system/token-governance.md

@@ -17,7 +17,14 @@ Do not add raw component styling literals directly to `registry/components`:
 - Component-local `color-mix()` percentages.
 - Legacy `--ds-*` fallbacks.
 
-`npm run tokens:check` enforces the generated CSS contract and component token usage.
+`npm run tokens:check` enforces the public token schema, generated CSS contract,
+and component token usage. `schema/tokens.schema.json#/$defs/cssVariableName`
+owns the naming rule for published variables and alias targets: `--bh-*` and
+`--elevation-*`. The compiler, CSS generator, component metadata scanner, and CSS
+reference checks share that contract through `scripts/token-schema.mjs`.
+Compilation and direct CSS generation validate the full catalog before comparing
+or writing artifacts, so schema failures stop both `tokens:check` and
+`contracts:check`.
 
 Structured tokens and aliases are authored in the domain and component-owned
 fragments under `tokens/source/`. `tokens/banhaten.tokens.json` is output-only
@@ -27,7 +34,13 @@ keyframes, global and accessibility rules, and typography utilities live in
 `registry/styles/globals.css` is regenerated from the compiled token catalog and
 that authored CSS source.
 
-The generator emits the complete default-theme graph once, then emits only declarations whose values differ for each alternate theme. Dark mode and alternate themes inherit unchanged scoped aliases through the cascade. This keeps the live graph auditable without duplicating identical declarations.
+Each theme boundary emits its complete palette, semantic aliases, effects, and
+dependent component aliases. Dark mode rebinds the semantic and component graph
+both on `.dark` elements and on themed descendants. CSS custom properties inherit
+computed values, so identical `var()` declarations must be repeated at these
+boundaries to resolve against the local theme. Other typography and layout tokens
+retain their existing inheritance behavior. The token contract check verifies
+these graphs for every supported light and dark theme scope.
 
 The default appearance uses `gray` for both brand roles and the neutral ramp.
 As a result, product surfaces, links, focus states, and primary actions are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "banhaten",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Banhaten design system: an Arabic and English-first React design system with shadcn-style component installation.",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "start": "node playground/scripts/serve-static.mjs playground/dist",
     "check": "node --check src/cli/index.js && node --check src/cli/command-line.js && node --check src/cli/doctor.js && node --check src/cli/config-editors.js && node --check src/cli/source-scanner.js && node --check src/cli/jsonc.js && node --check src/cli/vite-config.js && node --check src/cli/install-plan.js && node --check src/cli/install-receipt.js && node --check src/cli/package-install-state.js && node --check src/cli/package-manager.js && node --check src/cli/package-plan.js && node --check src/cli/package-version.js && node --check scripts/compile-token-catalog.mjs && node --check scripts/sync-default-theme-neutral-values.mjs && node --check scripts/token-catalog-test.mjs && node --check scripts/registry-catalog.mjs && node --check scripts/generate-registry-index.mjs && node --check scripts/generate-shadcn-registry.mjs && node --check scripts/normalize-component-docs.mjs && node --check scripts/package-artifact.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/select-react-compatibility.mjs && npm run contracts:check && npm run cli:test && npm run tokens:check && npm run components:ownership:check && npm run registry:check && npm run docs:check && npm run package:check && npm run playground:build && npm run playground:test:browser && npm run playground:audit",
     "contracts:check": "node scripts/validate-contracts.mjs",
-    "cli:test": "node scripts/cli-argument-test.mjs && node scripts/cli-dependency-test.mjs && node scripts/cli-install-plan-test.mjs && node scripts/cli-integration-test.mjs && node scripts/cli-doctor-test.mjs",
+    "cli:test": "node scripts/cli-argument-test.mjs && node scripts/cli-file-transaction-test.mjs && node scripts/cli-dependency-test.mjs && node scripts/cli-install-plan-test.mjs && node scripts/cli-integration-test.mjs && node scripts/cli-doctor-test.mjs",
     "playground:build": "npm --prefix playground run build",
     "playground:dev": "npm --prefix playground run dev",
     "playground:test": "npm --prefix playground run test",