banhaten 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
 
+## Unreleased
+
+## 0.6.0 - 2026-10-28
+
+### Added
+
+- Sidebar `size="comfortable"` on `SidebarProvider` for application shells with 40px navigation rows. While expanded it uses 40px rows 8px apart, body-md labels, 16px shell padding, a 24px section gap, a heading-md brand, and 20px group labels. The collapsed rail and the default size are unchanged.
+- `SidebarHeaderBrand` accepts `subtitle` for a stacked module line and `logo={false}` for a text-only brand.
+- `SidebarFooterUser variant="card"` renders the signed-in user as an inset tinted block. Every footer variant accepts `avatar={false}` and `trailingIcon={false}`, and `SidebarFooter divider={false}` drops the top rule.
+- Sidebar tokens `--bh-sidebar-group-label-content`, `--bh-sidebar-user-card-bg`, `--bh-sidebar-user-card-bg-hover`, and seven `--bh-sidebar-comfortable-*` dimensions.
+- `AppHeader`, the workspace bar above page content in a sidebar shell, with `AppHeaderStart`, `AppHeaderEnd`, `AppHeaderSearch`, and `AppHeaderAction`. The bar is 72px with 24px padding and gaps. Actions are flush with their 24px icon or label at rest and keep a 40px pointer target; `size="sm"` text actions reserve 32px for a language code.
+- Breadcrumbs `size="sm"` for a 14/20 trail with a 12px separator, and the `--bh-breadcrumbs-current-content` token for the current item color. App Header sets it to its subtle location color.
+- Table `size="comfortable"` follows Table item 1.2: 44px headers in body-sm medium on the table-header fill, 64px rows with 8px cells and body-md text, no row dividers, and a 12px radius. `sm` and `lg` are unchanged.
+- The owned table elements take the same spec through `TableRoot size="comfortable"`, and the new `TableContainer` frames them with a 12px radius and a border drawn inside the edge. Without a size they stay unstyled.
+- Line + subline table cells from Table item 1.2 (`hasCaption`): `text`, `brandLogoText`, `payment`, and `image` items accept `caption`, as `avatarText` already did. The caption is body-2xs in `content/subtle` directly under the label, so the pair fills 40px of a 56px `lg` row. DataTable search also matches captions.
+- `TableCellText` gives owned `TableCell`s the same line + subline content, with `caption`, a `leading` icon or avatar 6px before the text, and `tone` and `weight` for the label. Long labels and captions end in an ellipsis inside the cell. Table tokens `--bh-table-caption-content` and `--bh-table-cell-text-gap`.
+- `TableCellLink`, a flush text action for a cell label that opens a record. It keeps the cell text style, underlines on hover and focus, and draws its focus ring outside the clipped text. It renders a button, or its child with `asChild`. Table now lists `@radix-ui/react-slot` as a direct dependency.
+
+- PageHeader `size="comfortable"` for the page heading inside an app shell whose header carries the breadcrumbs.
+  - No block padding; 8px between title and description, 24px between copy and actions, 12px between actions.
+  - 40px action Buttons with a 160px minimum width (176px for primary Buttons), and no icon or tabs unless passed.
+  - New tokens `--bh-page-header-comfortable-action-min-width` and `--bh-page-header-comfortable-primary-action-min-width`.
+  - `actions` also accepts your own nodes, `description` accepts inline content, and `children` add supporting content, such as a status badge, under the description.
+- Button renders `data-variant` with its variant (`default` for primary), so containers can style actions by variant.
+- Tabs `size="comfortable"` for view navigation in an app page: underline tabs 48px tall and 8px apart, the active indicator drawn inside the tab, and no divider under the row. Segment and rounded tabs render it like `md`.
+- Card and CardSurface `size="comfortable"` for panels in an app shell: the same surface and 1px inset edge with a 12px radius (`--bh-card-comfortable-radius`) instead of the library card's 16px. Both render `data-size`.
+- Alert `icon` replaces the status icon, and `descriptionColor="default"` sets the description in `content/default`, as the ATS360 frames do.
+- Menu `MenuRadioGroup` and `MenuRadioItem` for menus that set one value, such as a display time zone: items are `menuitemradio` with `aria-checked`, the chosen one shows a trailing check, and choosing one calls the group's `onValueChange`. They also render in `MenuPreview`.
+
+### Changed
+
+- Attribute `density="comfortable"` is now the app-shell detail row: no row padding, rows 16px apart, a body-sm label in a 176px column (`--bh-attribute-comfortable-label-width`) and 16px before the value, aligned to the top. It rendered like `default` before.
+- Alert descriptions use the status colour from the library (`content/{status}/default`) instead of the strong title colour, and an expandable Alert with a description now uses the expanded layout without actions, as the library allows with Actions Links off. Before, it fell back to the compact layout and hid the description.
+- Input `md` and `lg` text starts 12px from the field edge, as in the library Input frame: 8px content padding plus a 4px value inset, with trailing icons 8px from the edge. It was 10px in `lg` and 8px in `md`. New tokens `--bh-input-content-padding-x` and `--bh-input-value-inset`; `comfortable` is unchanged.
+- Input and Select docs explain the 320px default width, the library frame width, and how to make a field fill its form column.
+- Table `lg` rows use body-md (15/24) text, as the Figma `lg` cells do; `sm` keeps body-sm.
+- Table `avatarText` names, and the labels of `brandLogoText`, `payment`, `image`, and `file` items, use medium weight, as in Figma; `avatarText` names were semibold. The `avatarText` caption moves from `content/default` with a 1px gap to `content/subtle` with no gap.
+- Badge draws its border inside the side padding, as the library's inside stroke does, so a badge is its label plus 8px (12px at `lg`) on each side. Each side padding subtracts the border width (1px, or `--bh-badge-outline-border-width` for `outline`); badges were 2px wider than the library, and outline badges 3px. Heights are unchanged.
+- Sidebar `size="comfortable"` draws the expanded rail's 1px stroke inside on all four sides, an outline inset by its width in `--bh-sidebar-border`, instead of an end border, as the ATS360 shell frames do. It takes no width and stays visible above the header and footer fills; the collapsed rail keeps the end border.
+
+## 0.5.0 - 2026-10-16
+
+### Added
+
+- ECharts-backed `DataChart`, `EChart`, and `ChartBlock` APIs with eight chart families, 18 example blocks, token-driven themes, and interactive legends, tooltips, and brush controls. Existing Recharts wrappers remain supported.
+- AI conversation components built only from Banhaten primitives and tokens: `ThinkingState`, `ThinkingReasoning`, `StreamingText` with a `useTypewriter` hook for local reveals, `InlineCitations` composed from `CitationProse` and `CitationMark`, `TaskList` with `TaskListRoot`, `TaskListHeader`, `TaskListItems`, and `TaskListPreview` parts for static and folded lists, `AgentInput`, and the approval cards (`ApprovalQuestions`, `ApprovalCommand`, `ApprovalPlan`) with the `ApprovalFrame` shell they share for custom decisions, each with registry metadata, documentation, examples, playground pages, and tests.
+- `ShimmerText` for labels of work in progress and `RollingCount` for counts that roll each changed digit into place, general-purpose components the AI conversation components build on, each with registry metadata, documentation, examples, playground pages, and tests.
+- Foundation motion tokens `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-duration-slower`, and `--bh-easing-emphasized`; component tokens for the reasoning block, streaming caret, citation marks, agent input, shimmer text, and task list; and a `--bh-font-family-mono` family for command blocks.
+- Shared hooks installed with the base files: `use-motion-end` runs script work after the CSS motion it waits for instead of after copied timings, `use-controllable-state` backs controlled and uncontrolled props, `use-reduced-motion` follows the user's motion setting, and `use-listbox-navigation` gives Autocomplete and the Agent Input skill palette one keyboard model.
+- `CollapsiblePanel`, an unstyled Collapsible part that animates its height open and closed, and `asChild` support on `CollapsibleTrigger` for components with their own disclosure design.
+- Registry file entries accept `"internal": true`. An internal module installs and compiles with its component, but its exports stay out of the supported import contract, so a large component can be split into modules without publishing them.
+
+### Changed
+
+- Autocomplete moves the active option to the first enabled match when filtering removes the one that was active, instead of leaving no option active.
+- Input quantity steppers now update values using native number-input constraints and change events; button and dropdown compositions expose native action props.
+- Public depth tokens use the `--elevation-*` namespace, with seven numbered steps and semantic component aliases. Token graphs rebind at nested theme boundaries.
+- Sidebar collapse uses staged transitions and dedicated motion tokens.
+
+### Fixed
+
+- CLI writes detect concurrent edits before replacing consumer files.
+- Checked indicators retain contrast in dark themes; label-less Selects receive accessible names; Input exposes required semantics; Toolbar defaults to group semantics.
+- Breadcrumbs, keyboard shortcuts, Page Header, Tabs, and Table improve content direction, overflow handling, and pagination sizing.
+- Packed-artifact validation invokes npm directly through Node on Windows, avoiding the `spawn EINVAL` failure from launching `npm.cmd`.
+- Refreshed dependency resolutions for runtime and playground security fixes; Windows token-security fixtures use directory junctions, and browser tests include the Windows autofill workaround.
+
+### Migration
+
+- Replace `--shadow-xs`, `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`, and `--shadow-3xl` with `--elevation-01` through `--elevation-07`, respectively. Rename semantic `--shadow-*` references and overrides to their corresponding `--elevation-*` names; the old token names are no longer published.
+- Run `npx banhaten@0.5.0 diff` before `npx banhaten@0.5.0 update`. Review customized component files and token overrides before using `--force`.
+- Updating `chart` adds an `echarts` dependency alongside `recharts`; run the package-manager install command printed by the CLI. Existing Recharts compositions continue to work.
+- Quantity Input now renders a number input with working steppers. Review custom click handlers to avoid applying a second increment, and call `preventDefault()` in a stepper handler when overriding the built-in step.
+
 ## 0.4.0 - 2026-08-22
 
 ### Added
@@ -14,12 +88,14 @@ All notable Banhaten changes are recorded here. Releases follow the policy in `d
 ### Changed
 
 - The default brand theme is now monochrome `gray`; `blue` remains available as an explicit alternate theme.
-- Elevation now publishes the complete seven-level Figma scale as `--shadow-xs` through `--shadow-3xl`, with dedicated reviewed light and dark values and updated token documentation.
+- Elevation now publishes the complete seven-level Figma scale as `--elevation-01` through `--elevation-07`, with dedicated reviewed light and dark values and updated token documentation.
 - Shared icon and icon-slot geometry is tokenized across controls, navigation, feedback, and data-display components for more consistent alignment.
 - Sidebar defaults now use a 280px expanded shell and a 48px collapsed rail, with logical placement and spacing throughout.
+- Button now publishes `success`, `warning`, and `link` as canonical variants across its catalog, documentation, examples, and playground.
 
 ### Fixed
 
+- `MenuItem.onSelect` now exposes Radix's `(event: Event) => void` contract without intersecting React's unrelated DOM selection handler, so explicit annotations and prevent-default multi-select flows compile correctly.
 - Sidebar focus, tooltip, collapse, nesting, active-state, narrow-layout, and RTL behavior across both controlled and uncontrolled compositions.
 - Component icon sizing, spacing, and state styling across Alert, Avatar, Button Group, Date Picker, Input, Item, Menu, Pagination, Select, Tag, Toolbar, and expanded compositions.
 - Playground token enforcement now uses explicit Banhaten shadow variables in every Test Lab surface.
@@ -28,6 +104,7 @@ All notable Banhaten changes are recorded here. Releases follow the policy in `d
 
 - To retain the previous blue default, set `data-theme="blue"` on the themed root; roots without `data-theme` now resolve to gray.
 - Review custom Sidebar shells before updating because the canonical expanded and collapsed widths and the recommended header, menu, and footer composition have changed. Run `npx banhaten diff sidebar` before `npx banhaten update sidebar`, and use `--force` only after reviewing local generated-file changes.
+- Button's `destructive` and `soft-destructive` values remain accepted as deprecated compatibility aliases; migrate to `danger` and `soft-danger`, respectively.
 
 ## 0.3.0 - 2026-08-21
 

package/CONTRIBUTING.md

@@ -12,13 +12,15 @@ The full check validates schemas, CLI behavior, token generation, token-only com
 
 ## Component rules
 
-- Build component styling from canonical `--bh-*` and `--shadow-*` tokens. Add
-  new values to the appropriate owned fragment under `tokens/source/` before
-  using them in component source.
+- Build component styling from canonical `--bh-*` and `--elevation-*` tokens. Add
+  new values to the component's own fragment under
+  `tokens/source/components/<id>/`, or to a foundation fragment when several
+  components share them, before using them in component source.
 - Keep product copy, sample dates, and product actions in examples rather than production defaults.
 - Preserve inherited direction and use logical CSS properties. Test both LTR and RTL keyboard behavior.
 - Use native semantics or proven accessible primitives, and document the public API, examples, tokens, RTL behavior, and accessibility contract.
-- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab.
+- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab. A family built for one product surface, such as AI conversation, may have its own group; the general-purpose primitives it relies on still go in Components.
+- Split a component that nears 1,000 lines into modules by concern. Mark the modules that only serve its public module `"internal": true` in its catalog entry so the split does not publish them.
 
 ## Generated artifacts
 

package/README.md

@@ -156,11 +156,11 @@ completeness.
 
 ## Documentation
 
-Primary docs live in the playground and render live registry-backed previews, install commands, source snippets, API tables, registry files, RTL behavior, and copyable code panels.
+Primary docs live in the playground and render live registry-backed previews, install commands, source snippets, API tables, registry files, RTL behavior, and copyable code panels. The playground also includes a Templates tier with 60 searchable page, flow, and widget compositions built from current Banhaten tokens and components.
 
 Markdown docs live in `docs/design-system/components`. They are checked for install, API, examples, token contract, RTL rules, and accessibility sections.
 
-Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md).
+Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md). See the [template catalog contract](docs/design-system/templates.md) and the resulting [template gap audit](docs/design-system/template-gap-audit.md) for the composition layer.
 
 The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, the closed 910/910 contrast contract, and deliberate non-copying decisions.
 
@@ -178,6 +178,8 @@ The registry includes core primitives such as Button, Input, Select, Field, Moda
 
 Expanded components are larger app compositions. They are installed through the same CLI but documented as a separate tier because their layout contracts are broader than primitive controls.
 
+Templates sit above those reusable components and patterns. They demonstrate realistic page, flow, and widget assemblies without claiming product behavior or generated-file ownership; candidates become installable blocks only after their APIs and state contracts stabilize.
+
 ## Development
 
 ```bash

package/docs/design-spacing.md

@@ -0,0 +1,13 @@
+# Design spacing
+
+Applies to templates (Pages, Flows, Widgets), Test Lab compositions, and background designs.
+
+Use existing Banhaten spacing tokens for padding, margin, and gaps. Ordinary content groups, headings with actions, and footers use explicit gaps with start alignment. Avoid `space-between`, `space-around`, `space-evenly`, and auto margins to spread ordinary grouped content. These turn leftover width into arbitrary gaps, including fractional pixels. Wrap groups at narrow widths rather than compressing their gaps.
+
+Keep fluid distribution only where it serves the layout: aligned table/detail values, transaction amounts, schedule columns, chart/slider endpoints, pagination at table edges, standard field affordances, and bottom-anchored sidebar sections. Responsive grid tracks and chart geometry remain fluid. Original reference reproductions remain references.
+
+Whole spacing tokens do not guarantee that every measured dimension is an integer. Font shaping can give text a fractional width, and responsive tracks, centering, zoom, or scale can create fractional coordinates. Do not change typography, round measurements, or add invisible filler to conceal that. The inspector continues to report real rendered measurements. A fractional text width is not a fractional CSS gap.
+
+Preserve intentional edge alignment through explicit layout tracks. The music footer uses a flexible text column, a 160px token-width action column, and an exact 8px token gap. The music card uses an even-pixel width so its centered controls and equal timeline columns also have whole-pixel spacing. This changes the actual layout, not the inspector output; the button remains at the trailing edge.
+
+Validation for spacing changes: inspect the affected layout and measure its actual gap; check a narrow viewport when wrapping is affected. Preserve fluid exceptions for their specific purpose, rather than applying a global pixel-snapping script.

package/docs/design-system/README.md

@@ -12,6 +12,8 @@ Use these docs with the live playground.
 - [Support Matrix](./support-matrix.md): framework, runtime, browser, font, and package-manager baseline.
 - [Release Policy](./release-policy.md): stability tiers, versioning, deprecation, and launch gates.
 - [Roadmap](./roadmap.md): explicitly deferred product-specific components and promotion gates.
+- [Templates](./templates.md): 60 page, flow, and widget compositions built from Banhaten tokens and components.
+- [Template Gap Audit](./template-gap-audit.md): composition friction and prioritized candidates revealed by the template catalog.
 - [Launch Comparison](./launch-comparison-shadcn.md): the complete shadcn/ui benchmark, remediation register, and deliberate differences.
 - [Component Docs Pattern](./component-docs-pattern.md): the Base / Anatomy / Alternatives shape every playground component page follows.
 - [Components](./components/README.md): component markdown catalog.

package/docs/design-system/appearances/default.md

@@ -10,7 +10,7 @@ It should feel practical, calm, and balanced: a gray application background, whi
 - Cards and primary content areas are white.
 - Actions and controls have a modest radius.
 - Spacing is comfortable but compact enough for daily product use.
-- Shadows are subtle and used only to separate floating or raised elements.
+- Elevation is subtle and used only to separate floating or raised elements.
 
 ## Token Direction
 

package/docs/design-system/appearances/rounded.md

@@ -11,7 +11,7 @@ It should feel open, approachable, and more polished: a white application backgr
 - Primary actions can be pill-shaped.
 - Panels and cards have visibly larger radius.
 - Spacing is a little more relaxed than `default`.
-- Shadows are soft and optional.
+- Elevation is soft and optional.
 
 ## Token Direction
 

package/docs/design-system/appearances/sharp.md

@@ -11,7 +11,7 @@ It should feel structured, architectural, and efficient: square edges, tighter s
 - Radius is zero or nearly zero across most UI.
 - Spacing is tighter than `default`.
 - Borders carry most of the separation work.
-- Shadows are reserved for overlays only.
+- Elevation is reserved for overlays only.
 
 ## Token Direction
 

package/docs/design-system/component-showcase-consistency-report.md

@@ -74,15 +74,15 @@ Every public component page should use this consistent pattern:
 ### What Button Is Missing Or Inconsistent
 
 - Registry size metadata now matches the implementation and examples, including `xl` and `icon-xl`.
-- Source supports compatibility variants that are not part of the visible registry contract: `destructive`, `soft-destructive`, `success`, `warning`, and `link`. Decide whether these are public aliases, deprecated aliases, or should be removed.
+- The visible contract now publishes `success`, `warning`, and `link` as canonical variants. `destructive` and `soft-destructive` remain documented compatibility aliases for `danger` and `soft-danger`.
 - Button now has a component markdown page and is listed in the component docs index.
 - The interactive inspector has been removed from the Button page, matching the new page direction.
 - The page is a high-quality bespoke file rather than a scalable shared template. Copying it component by component would increase drift.
-- Test coverage only smoke-renders a basic Button. It does not assert the variant/size contract, `asChild`, loading composition, icon sizing, or source/metadata parity.
+- Focused parity coverage now locks Button's runtime variant union, canonical catalog/index/spec values, manual API and example lists, distinct recipes, and exact compatibility aliases. Broader behavior such as `asChild`, loading composition, and icon sizing remains covered by shared component and browser checks rather than this focused contract test.
 
 ### Verdict
 
-Button should be the content-quality model, not the code-shape model. Its opening preview, registry size metadata, and component markdown docs now match the proposed standard. The remaining work is the source-supported alias policy and a metadata parity check.
+Button should be the content-quality model, not the code-shape model. Its opening preview, registry metadata, canonical variant policy, component markdown docs, and source parity check now match the proposed standard.
 
 ## Presentation Families
 
@@ -145,8 +145,8 @@ Button should be the content-quality model, not the code-shape model. Its openin
 
 ### P0: Fix Contract Drift
 
-- Decide the public/deprecated status of Button compatibility variants: `destructive`, `soft-destructive`, `success`, `warning`, and `link`.
-- Add a parity check that compares registry metadata values against obvious exported spec/example usage for variants and sizes.
+- Button's variant policy is resolved: `success`, `warning`, and `link` are canonical; `destructive` and `soft-destructive` are deprecated aliases for `danger` and `soft-danger`.
+- Button now has a focused parity check across its runtime types, registry metadata, generated index, playground spec, Markdown API, and examples. Apply that pattern to other components when drift is found.
 
 ### P0: Pick One Page Standard
 

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

@@ -9,6 +9,7 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Activity Heatmap](./activity-heatmap.md): token-only seven-day activity grid with five intensity levels, responsive overflow, and RTL support.
 - [Alert](./alert.md): compact and expandable contextual feedback with semantic status colors, action links, close control, and RTL support.
 - [Alert Dialog](./alert-dialog.md): Radix AlertDialog-backed confirmation surface for destructive or consequential actions with semantic intent styling.
+- [App Header](./app-header.md): workspace bar above page content with a location region, search landmark, and flush icon or text actions with 40px targets.
 - [Aspect Ratio](./aspect-ratio.md): Radix AspectRatio wrapper for fixed-format media, previews, and product surfaces.
 - [Attribute](./attribute.md): semantic key-value description lists with alignment variants, density, bordered rows, rich value slots, and RTL support.
 - [Autocomplete](./autocomplete.md): searchable combobox field composed from Input, Select menu rows, and Tag chips for single or multiple selection.
@@ -55,7 +56,9 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Select](./select.md): Radix Select-backed field and menu item system with item media, selection styles, validation states, and RTL layout.
 - [Segmented Control](./segmented-control.md): content-width single or multiple selection control with semantic density, an optional label segment, keyboard navigation, and RTL support.
 - [Resizable](./resizable.md): react-resizable-panels-backed split pane primitive with tokenized resize handle.
+- [Rolling Count](./rolling-count.md): tabular figures that roll each changed digit into place like an odometer while assistive technology reads the plain value.
 - [Sheet](./sheet.md): Radix Dialog-based edge panel with logical start/end placement, top/bottom placement, size variants, and RTL support.
+- [Shimmer Text](./shimmer-text.md): text with a brightness sweep in reading direction for labels of work in progress.
 - [Sidebar](./sidebar.md): composable app sidebar with collapse state, grouped menu items, logical placement, and sidebar tokens.
 - [Slideout](./slideout.md): desktop and mobile side panel with header/footer actions, scrollable slots, example content, and RTL support.
 - [Scroll Area](./scroll-area.md): Radix ScrollArea wrapper with tokenized viewport, scrollbar, thumb, and corner styling.
@@ -74,3 +77,15 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Toolbar](./toolbar.md): filter and action toolbar with search, select triggers, icon buttons, chips, summaries, desktop/mobile styles, and RTL support.
 - [Tooltip](./tooltip.md): Radix Tooltip-backed help surface with dark/default variants, pointer positions, shortcut/close slots, and RTL support.
 - [Typography](./typography.md): documentation for existing `.bh-text-*` token utility classes.
+
+## AI Conversation
+
+Components for agent conversations: thinking states, streaming responses, citations, task progress, the prompt composer, and human-in-the-loop approvals. They compose the core components above, including Rolling Count and Shimmer Text, and move on the shared `--bh-duration-*` and `--bh-easing-*` foundation tokens.
+
+- [Agent Input](./agent-input.md): AI prompt composer with an auto-growing editor, slash-command skill palette, skill and attachment chips, add menu, prompt enhancement, and send action.
+- [Approval Card](./approval-card.md): human-in-the-loop decision cards for questions, shell command approval, and plan sign-off with an opt-in auto-approve countdown.
+- [Inline Citations](./inline-citations.md): prose with linked superscript citation chips, hover reference names, and a compact source list.
+- [Streaming Text](./streaming-text.md): token-by-token text reveal with a slim caret that stays solid while streaming and blinks when complete.
+- [Task List](./task-list.md): collapsible agent progress tracker with pending, active, and done rows, a list-to-pie-to-check header icon, and rolling counters.
+- [Thinking Reasoning](./thinking-reasoning.md): animated, collapsible reasoning block that reveals sentences as they arrive and folds into a Thought for Ns summary.
+- [Thinking State](./thinking-state.md): shimmering status label for the pre-response beat.

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

@@ -62,6 +62,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` |
 | `registryDependencies` | None |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-accordion`, `--bh-duration-default`, `--bh-easing-out`, `--bh-opacity-50`, `--bh-radius-md-6`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--shadow-accordion-item`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-accordion`, `--bh-duration-default`, `--bh-easing-out`, `--bh-opacity-50`, `--bh-radius-md-6`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--elevation-accordion-item`, `--elevation-button-focus` |
 | `variants` | `default`, `bordered`, `cards`, `soft` |
 <!-- registry-contract:end -->

package/docs/design-system/components/activity-feed.md

@@ -103,6 +103,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `ActivityFeed`, `ActivityFeedItem` |
 | `registryDependencies` | `button` |
 | `states` | `default`, `with-status`, `with-link`, `with-actions` |
-| `tokens` | `--bh-activity-feed-compact-width`, `--bh-bg-accent-purple-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--shadow-button-raised`, `--shadow-component-default` |
+| `tokens` | `--bh-activity-feed-compact-width`, `--bh-bg-accent-purple-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--elevation-button-raised`, `--elevation-component-default` |
 | `variants` | `caption`, `slot` |
 <!-- registry-contract:end -->

package/docs/design-system/components/activity-heatmap.md

@@ -69,5 +69,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `props.dir` | `ltr \| rtl; default "inherited"; Places the first activity column at the logical start edge.` |
 | `props.items` | `readonly ActivityHeatmapItem[]; default "[]"; Column-major cells grouped into seven-day weeks, each with a level from zero through four.` |
 | `states` | `level-0`, `level-1`, `level-2`, `level-3`, `level-4` |
-| `tokens` | `--bh-bg-accent-purple-default`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-purple-subtle`, `--bh-bg-neutral-medium`, `--bh-content-accent-purple-strong`, `--bh-content-default`, `--bh-font-family`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-xs-4`, `--shadow-component-focus-ring` |
+| `tokens` | `--bh-bg-accent-purple-default`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-purple-subtle`, `--bh-bg-neutral-medium`, `--bh-content-accent-purple-strong`, `--bh-content-default`, `--bh-font-family`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-xs-4`, `--elevation-component-focus-ring` |
 <!-- registry-contract:end -->

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

@@ -0,0 +1,85 @@
+# Agent Input
+
+`AgentInput` is the prompt composer for agent conversations. One frame holds an auto-growing editor, skill and attachment chips, an add menu for photos, files, skills, and models, a slash-command skill palette, an optional Enhance Prompt action with a sweeping accent ring, and the send button.
+
+It composes Button, Menu, Tag, Spinner, and Shimmer Text rather than restyling them, so density, focus, and RTL behavior match the rest of the system.
+
+## API
+
+```tsx
+import { AgentInput } from "@/components/ui/agent-input"
+
+<AgentInput
+  models={models}
+  onEnhance={enhancePrompt}
+  onSend={({ text, attachments, skills, model }) =>
+    submit({ files: attachments.map((attachment) => attachment.file), model, skills, text })
+  }
+  skills={skills}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` / `onValueChange` | `string` | `""` | Prompt text. |
+| `onSend` | `(payload: AgentInputPayload) => void` | – | Receives `text`, `attachments`, selected `skills`, and the `model`. Enter sends; Shift+Enter inserts a line break; an Enter that confirms an IME composition never sends. |
+| `onEnhance` | `(prompt, signal) => Promise<string>` | – | Enables Enhance Prompt. Resolve with the rewritten prompt; if it rejects, the original prompt returns. The signal aborts when the field unmounts, and a late result is ignored. |
+| `models` | `readonly AgentInputModel[]` | `[]` | Selectable models with `name`, optional `description`, `meta`, and `icon`. |
+| `model` / `defaultModel` / `onModelChange` | `string` | first model | Selected model id. |
+| `skills` | `readonly AgentInputSkill[]` | `[]` | Skills available from the add menu and by typing `/`. |
+| `selectedSkills` / `defaultSelectedSkills` / `onSelectedSkillsChange` | `readonly string[]` | `[]` | Selected skill ids, shown as chips. |
+| `attachments` / `onAttachmentsChange` | `readonly AgentInputAttachment[]` | internal | Attachment chips `{ id, kind, name, file? }`; omit to let the field own picked files. A picked file's kind follows its MIME type; the picker it came from decides only for files without one. |
+| `disabled` | `boolean` | `false` | Disables editing and actions. |
+| `labels` | `Partial<AgentInputLabels>` | English | Placeholder, menu, action, and remove copy. |
+
+Keyboard: `/` opens the skill palette, arrow keys move, Enter or Tab inserts, Escape closes.
+
+Files picked through the add menu keep their `File` on `attachment.file`, so you can upload them as soon as they arrive in `onAttachmentsChange` or when `onSend` fires. Attachments you pass in yourself, such as ones restored from a saved draft, can leave `file` out.
+
+## Install
+
+```bash
+npx banhaten add agent-input
+```
+
+## Examples
+
+Primary registry example: `examples/agent-input-demo.tsx`.
+
+## Token Contract
+
+The frame uses `--bh-bg-raised`, `--bh-radius-2xl-12`, and `--elevation-02`. The editor uses the `body-sm-regular` scale, `--bh-content-muted` placeholders, and caps at `--bh-agent-input-field-max-height`. The palette reuses Menu tokens (`--bh-menu-bg`, `--bh-menu-radius`, `--bh-menu-item-radius`, `--bh-menu-item-hover-bg`, `--elevation-menu`) at `--bh-agent-input-palette-width`. The enhancing ring is `--bh-agent-input-ring-width` wide and cycles the blue, purple, fuchsia, and aqua accent content tokens on `--bh-agent-input-ring-duration`. Chips, the enhance pill, and the palette move on the shared `--bh-duration-*` and `--bh-easing-emphasized` foundation tokens, and removed chips and the pill unmount when their exit animation ends.
+
+Covered source files: `components/agent-input.tsx`, the internal `components/agent-input-parts.tsx` and `components/agent-input-state.ts`, `components/agent-input.css`, and the `button`, `menu`, `shimmer-text`, `spinner`, and `tag` registry dependencies.
+
+## RTL Rules
+
+- The editor, chips, palette, and action row inherit direction and use logical spacing.
+- The add menu and slash palette open toward the logical start; Menu resolves keyboard direction through its own boundary.
+
+## Accessibility
+
+The editor is a native textarea labelled by the placeholder. Typing / opens a listbox of skills that the field drives through `aria-activedescendant`, `aria-controls`, `aria-autocomplete`, and `aria-haspopup`; arrow keys move the active option with wrapping and Enter or Tab inserts it. The palette shares its keyboard model with Autocomplete through the `use-listbox-navigation` hook. Chips expose remove buttons named after their item, the add menu is a Radix menu with roving focus, and a status region that stays mounted announces the `enhancing` label when a request starts. 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/agent-input.tsx: AgentInput` |
+| `parts` | `AgentInput` |
+| `registryDependencies` | `button`, `menu`, `shimmer-text`, `spinner`, `tag` |
+| `props.value` | `string; default null; Controlled prompt text; use defaultValue for uncontrolled usage.` |
+| `props.onSend` | `(payload: AgentInputPayload) => void; default null; Receives text, attachments, skills, and the selected model; picked attachments carry their File for upload.` |
+| `props.onEnhance` | `(prompt: string, signal: AbortSignal) => Promise<string>; default null; Enables the Enhance Prompt action; resolves to the rewritten prompt.` |
+| `props.models` | `readonly AgentInputModel[]; default "[]"; Selectable models with name, description, meta, and icon.` |
+| `props.skills` | `readonly AgentInputSkill[]; default "[]"; Skills available from the add menu and the slash palette.` |
+| `props.attachments` | `readonly AgentInputAttachment[]; default null; Controlled attachment chips; omit to let the field own picked files.` |
+| `props.onAttachmentsChange` | `(attachments: AgentInputAttachment[]) => void; default null; Called when chips are added or removed; picked files arrive with their File, so uploads can start right away.` |
+| `props.labels` | `Partial<AgentInputLabels>; default "English"; Localized placeholder, menu, action, and remove copy.` |
+| `states` | `idle`, `enhancing`, `enhanced` |
+| `tokens` | `--bh-agent-input-field-max-height`, `--bh-agent-input-palette-width`, `--bh-agent-input-ring-duration`, `--bh-agent-input-ring-width`, `--bh-bg-raised`, `--bh-button-xs-height`, `--bh-content-accent-aqua-default`, `--bh-content-accent-blue-default`, `--bh-content-accent-fuchsia-default`, `--bh-content-accent-purple-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-default`, `--bh-duration-moderate`, `--bh-easing-emphasized`, `--bh-font-family`, `--bh-menu-bg`, `--bh-menu-item-hover-bg`, `--bh-menu-item-radius`, `--bh-menu-radius`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-2xl-12`, `--bh-space-2xl-14`, `--bh-space-6xl-32`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-z-popover`, `--elevation-02`, `--elevation-menu` |
+<!-- registry-contract:end -->

package/docs/design-system/components/alert-dialog.md

@@ -83,5 +83,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `alert-dialog semantics`, `cancel focus pattern`, `safe cancel action`, `destructive action`, `semantic intent icon` |
 | `intents` | `default`, `warning`, `danger` |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-alert-dialog-border`, `--bh-alert-dialog-width`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-2xl`, `--shadow-modal` |
+| `tokens` | `--bh-alert-dialog-border`, `--bh-alert-dialog-width`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--elevation-06`, `--elevation-modal` |
 <!-- registry-contract:end -->

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

@@ -12,6 +12,7 @@ The implementation covers the Alert matrix from Figma:
 | --- | --- |
 | `status` | `danger`, `success`, `warning`, `info`, `neutral` |
 | `isExpandable` | `false`, `true` |
+| `descriptionColor` | `status`, `default` |
 | `dir` | `ltr`, `rtl` |
 
 ## API
@@ -30,10 +31,12 @@ The implementation covers the Alert matrix from Figma:
 | Prop | Default |
 | --- | --- |
 | `status` | `neutral` |
-| `isExpandable` | `false`; requires at least one visible action |
+| `isExpandable` | `false`; expands when there is a description or a visible action |
 | `dir` | inherited |
 | `title` | none |
 | `description` | none |
+| `descriptionColor` | `status`: the description in the status colour; `default` sets it in `content/default`, as the ATS360 frames do |
+| `icon` | the status icon; pass a node to replace it |
 | `messages` | English close-button message; accepts partial localized overrides |
 | `closeLabel` | overrides `messages.close` |
 | `actions` | none |
@@ -45,7 +48,7 @@ The implementation covers the Alert matrix from Figma:
 
 - Compact alerts are `470px` wide and `56px` tall with `16px` padding.
 - Expandable alerts are `500px` wide, content-sized, and use `20px 16px` padding.
-- `isExpandable` falls back to the compact layout when no action is visible.
+- `isExpandable` falls back to the compact layout when there is no description and no visible action. A description without actions matches the library Alert with Actions Links turned off.
 - Compact rows use `8px` radius; expandable rows use `10px` radius.
 - Status glyphs are `18px` in `20px` slots; close controls are `20px` with a `16px` close glyph.
 - Compact content uses `8px` between icon and title.
@@ -55,7 +58,7 @@ The implementation covers the Alert matrix from Figma:
 - Expanded action rows retain `20px` of block-end padding.
 - Expanded height grows with title and description content; direction does not select a height.
 - Titles use `15px / 24px` medium text.
-- Descriptions use `14px / 20px` regular text at `80%` opacity.
+- Descriptions use `14px / 20px` regular text in the status colour (`content/{status}/default`, as in the library), or `content/default` with `descriptionColor="default"`. Titles use the strong status colour.
 
 ## Token Contract
 
@@ -63,7 +66,7 @@ The component consumes Banhaten semantic tokens and component aliases. Do not ha
 
 - Backgrounds: `--bh-bg-danger-subtle`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-bg-info-subtle`, `--bh-bg-neutral-subtle`
 - Borders: `--bh-border-danger-subtle`, `--bh-border-success-subtle`, `--bh-border-warning-subtle`, `--bh-border-info-subtle`, `--bh-border-subtle`, `--bh-border-default`
-- Content: `--bh-content-danger-strong`, `--bh-content-success-strong`, `--bh-content-warning-strong`, `--bh-content-brand-strong`, `--bh-content-default`
+- Content: `--bh-content-danger-strong`, `--bh-content-success-strong`, `--bh-content-warning-strong`, `--bh-content-brand-strong` for titles; `--bh-content-danger-default`, `--bh-content-success-default`, `--bh-content-warning-default`, `--bh-content-brand-default` for descriptions and icons; `--bh-content-default`
 - Shape: `--bh-radius-lg-8`, `--bh-radius-xl-10`, `--bh-radius-full`
 - Space: `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-space-4xl-20`
 
@@ -106,6 +109,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/alert.tsx: Alert, alertVariants, arabicAlertMessages` |
 | `parts` | `Alert` |
 | `registryDependencies` | `button` |
+| `props.Alert.descriptionColor` | `"status" \| "default"; default "status"; status sets the description in the status colour, as in the library; default sets it in content/default, as the ATS360 frames do.` |
+| `props.Alert.icon` | `ReactNode; default null; Replaces the status icon in its 20px slot.` |
+| `props.Alert.isExpandable` | `boolean; default false; Uses the expanded layout when the alert has a description or a visible action; otherwise it stays compact.` |
 | `tokens` | `--bh-alert-compact-height`, `--bh-alert-compact-padding`, `--bh-alert-compact-radius`, `--bh-alert-compact-width`, `--bh-alert-expanded-padding-x`, `--bh-alert-expanded-padding-y`, `--bh-alert-expanded-radius`, `--bh-alert-expanded-width`, `--bh-alert-icon-size`, `--bh-alert-icon-slot-size`, `--bh-bg-danger-subtle`, `--bh-bg-info-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-border-danger-subtle`, `--bh-border-default`, `--bh-border-info-subtle`, `--bh-border-subtle`, `--bh-border-success-subtle`, `--bh-border-warning-subtle`, `--bh-border-width-default`, `--bh-content-brand-default`, `--bh-content-brand-strong`, `--bh-content-danger-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-success-strong`, `--bh-content-warning-default`, `--bh-content-warning-strong`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-icon-stroke-225`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-underline-font-size`, `--bh-text-body-md-underline-font-weight`, `--bh-text-body-md-underline-letter-spacing`, `--bh-text-body-md-underline-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height` |
 | `variants` | `danger`, `success`, `warning`, `info`, `neutral` |
 <!-- registry-contract:end -->

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

@@ -0,0 +1,97 @@
+# App Header
+
+App Header is the workspace bar above page content in a sidebar shell. It holds the reader's location at the start and workspace tools such as search, notifications, help, or language at the end.
+
+Use Page Header inside the page for the page title, description, and page actions. Use Toolbar for controls that act on a selection or a document.
+
+## API
+
+Put Breadcrumbs or a short location label in `AppHeaderStart`, and search and actions in `AppHeaderEnd`. Give the nested Input and every icon-only action an accessible name.
+
+```tsx
+<AppHeader>
+  <AppHeaderStart>
+    <Breadcrumbs
+      aria-label="Breadcrumb"
+      items={[{ label: "Recruiting", href: "#overview" }, { label: "Overview" }]}
+      size="sm"
+    />
+  </AppHeaderStart>
+  <AppHeaderEnd>
+    <AppHeaderSearch onSubmit={search}>
+      <Input
+        aria-label="Search workspace"
+        hasHelperText={false}
+        hasLabel={false}
+        placeholder="Search workspace"
+        type="search"
+      />
+    </AppHeaderSearch>
+    <AppHeaderAction aria-label="Notifications" icon={<BellIcon />} />
+    <AppHeaderAction aria-label="EN, switch language to Arabic" size="sm">
+      EN
+    </AppHeaderAction>
+  </AppHeaderEnd>
+</AppHeader>
+```
+
+The bar is 72px tall with 24px inline padding, a 24px gap between items, and a subtle bottom border inside that height. `AppHeaderStart` fills the free space, so the end group stays on the content edge. When space runs short, the start keeps at least 160px and the search narrows first. The bar does not wrap, so on phone widths hide the search or render a compact mobile bar.
+
+`AppHeaderAction` is flush: at rest it takes only the space of its icon or label, so it lines up with the design. Padding and a matching negative margin give it a 40px pointer target and hover surface without moving it.
+
+- Icon-only: pass `icon` and `aria-label`. The icon is 24px.
+- `size="md"`, the default: a text action in body-md medium.
+- `size="sm"`: a quieter text action in body-sm medium subtle content. It reserves 32px and aligns its label to the end edge, so a language code can change without moving the controls before it.
+- `asChild`: renders the action styles on a link.
+
+`AppHeaderSearch` is a form with the search landmark role. It sets the nested Input to the 320px search width.
+
+Breadcrumbs inside App Header show their current item in the same subtle color as the rest of the trail. Use `size="sm"` so the trail matches the 14/20 location text.
+
+## Install
+
+```bash
+npx banhaten add app-header
+```
+
+Add Breadcrumbs and Input separately when the header uses them.
+
+## Examples
+
+Primary registry example: `examples/app-header-demo.tsx`.
+
+## Token Contract
+
+App Header owns `--bh-app-header-*` tokens for its height, inline padding, gaps, start minimum width, background, border, location color, search width, icon size, and action content, hover, radius, and pointer-target inset. It sets `--bh-breadcrumbs-current-content` to the location color and `--bh-input-width` to fill the search landmark. Do not replace these values with local literals.
+
+Covered source file: `components/app-header.tsx`.
+
+## RTL Rules
+
+- The header inherits document direction.
+- Start and End regions, inline padding, and the reserved end-aligned width of small text actions use logical layout and mirror without alternate markup.
+- Breadcrumb separators and labels follow the Breadcrumbs RTL contract.
+
+## Accessibility
+
+The root is a `header` element. `AppHeaderSearch` is a search landmark and needs a labeled Input. Icon-only actions require `aria-label`. When a text action has an `aria-label`, start it with the visible label, such as “EN, switch language to Arabic”. Actions keep a 40px pointer target and a visible focus ring.
+
+<!-- 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/app-header.tsx: AppHeader, AppHeaderAction, AppHeaderEnd, AppHeaderSearch, AppHeaderStart` |
+| `parts` | `AppHeader`, `AppHeaderStart`, `AppHeaderEnd`, `AppHeaderSearch`, `AppHeaderAction` |
+| `registryDependencies` | None |
+| `props.AppHeaderAction.icon` | `ReactNode; default null; Icon content. Without children the action is icon-only and needs aria-label; the icon occupies 24px and the pointer target is 40px.` |
+| `props.AppHeaderAction.size` | `"sm" \| "md"; default "md"; md uses body-md medium default content. sm uses body-sm medium subtle content and reserves 32px at the end edge, so a short label such as a language code can change without moving earlier controls.` |
+| `props.AppHeaderAction.asChild` | `boolean; default false; Renders the action styles on the child element, such as a link.` |
+| `props.AppHeaderSearch.role` | `string; default "search"; Search landmark role on the wrapping form. Nest an Input with an accessible name; the header sets its width to the 320px search token.` |
+| `features` | `72px bar with 24px inline padding, a 24px item gap, and a subtle bottom border`, `flexible start region for Breadcrumbs or a location label in body-sm medium subtle content`, `Breadcrumbs inside the header render their current item in the location color`, `search landmark that sizes a nested Input to 320px`, `flush icon actions with a 24px footprint and a 40px target`, `flush text actions in md and sm sizes`, `logical layout that mirrors in RTL` |
+| `sizes` | `md`, `sm` |
+| `tokens` | `--bh-app-header-action-bg-hover`, `--bh-app-header-action-content`, `--bh-app-header-action-hit-inset`, `--bh-app-header-action-radius`, `--bh-app-header-action-sm-content`, `--bh-app-header-action-sm-min-width`, `--bh-app-header-bg`, `--bh-app-header-border`, `--bh-app-header-gap`, `--bh-app-header-height`, `--bh-app-header-icon-size`, `--bh-app-header-location-content`, `--bh-app-header-padding-x`, `--bh-app-header-search-width`, `--bh-app-header-start-gap`, `--bh-app-header-start-min-width`, `--bh-border-width-default`, `--bh-breadcrumbs-current-content`, `--bh-content-default`, `--bh-content-disabled`, `--bh-input-width`, `--bh-space-xs-4`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--elevation-button-focus` |
+<!-- registry-contract:end -->