banhaten 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
+
+## 0.2.0 - 2026-08-08
+
+### Added
+
+- Canonical JSON-driven token generation and strict component token enforcement.
+- Color Contrast documentation covering every audited theme, mode, foreground, and background scenario.
+- Item and Toggle Group primitives, inherited direction context, Arabic font installation, and named categorical chart tokens.
+- Receipt-backed CLI drift protection, unified diffs, and isolated compilation for every registry component.
+- Documentation search, token search/copy, stable component and pattern separation, and dedicated lab navigation.
+- `SegmentedControl` and `KbdShortcut` primitives with accessibility, RTL, registry metadata, examples, and tests.
+- Semantic `compact`, `default`, and `comfortable` density across Button, Input, Select, DatePicker, ButtonGroup, SegmentedControl, and Toolbar controls.
+- Canonical collection-filter, results-toolbar, and control-density recipes with accessibility and visual-regression coverage.
+- Install-time coding-agent guidance, a read-only `banhaten doctor` adoption audit, and recurring-gap promotion reporting.
+
+### Changed
+
+- Production components no longer invent demo content, fake actions, or fixed sample dates.
+- Input and Select no longer invent optional leading, information, or trailing icons when those props are omitted; explicit flags retain the previous built-in adornments.
+- Registry component metadata now publishes machine-readable prop types, rendered defaults, and descriptions for optional visual slots.
+- Registry component token metadata is generated from source references.
+- Pagination, OTP, Carousel, Alert, and Toast direction behavior now resolves from explicit props, provider context, or the nearest document boundary.
+- The default appearance keeps blue brand roles but now composes all neutral surfaces, borders, content, and interaction roles from the reviewed gray ramp in light and dark modes.
+- Registry metadata now declares capability defaults, recommended uses, avoid guidance, recipes, and deprecated props instead of inferring defaults from array order.
+- Toolbar controls default to the shared 36px density; use `density="comfortable"` for the previous 40px toolbar height.
+
+### Fixed
+
+- Undefined token references, raw component values, inaccessible progress semantics, no-op controls, and the Arabic Pagination “Previous” label.
+- Documentation section anchors, narrow Input preview overflow, Popover arrow sizing, Slideout icon geometry, and playground bundle chunking.
+- High-severity playground advisories in Nano ID, PostCSS, and Undici through patched lockfile versions.
+
+### Migration
+
+- Prefer `density` over legacy component-specific sizes when controls share a row. Legacy size props continue to work.
+- Replace Input `hasLeadingIcon` and `hasInformationIcon` with explicit `leadingIcon`/`trailingIcon`, or use `showAtSign`/`showInfo` for those exact affordances. The legacy flags remain supported for this deprecation window.
+- Replace single-glyph Input shortcuts with `shortcutKeys={["Mod", "K"]}` or `KbdShortcut` for platform-aware keycaps.
+- Run `npx banhaten init` to install `.banhaten/USAGE.md`, then run `npx banhaten doctor` and `npx banhaten diff` before updating consumer components.
+
+## 0.1.3
+
+- Pre-launch registry and documentation baseline.

package/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Banhaten
+
+## Local checks
+
+Use Node 18.18 or newer, install the root and playground dependencies, then run:
+
+```bash
+npm run check
+```
+
+The full check validates schemas, CLI behavior, token generation, token-only component styling, registry mirrors, isolated installs, documentation coverage, browser tests, and the production bundle.
+
+## 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.
+- 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.
+
+## Generated artifacts
+
+Edit the owned fragments under `tokens/source/` for structured tokens and
+aliases, and edit `registry/catalog/components/<id>.json` for component registry
+metadata. `tokens/banhaten.tokens.json` and `registry/index.json` are compiled
+publication artifacts. Edit `tokens/banhaten.utilities.css` for authored
+Tailwind mappings, keyframes, global rules, accessibility rules, and typography
+utilities. The generated `registry/styles/globals.css` is rebuilt from the
+compiled token catalog and that authored CSS source.
+
+After token or registry metadata changes, run:
+
+```bash
+npm run tokens:build
+npm run components:tokens:metadata -- --write
+npm run registry:export
+npm run docs:normalize
+```
+
+Do not hand-edit `tokens/banhaten.tokens.json`, `registry/index.json`,
+`registry/styles/globals.css`, `registry.json`, or generated registry contract
+tables.

package/README.md

@@ -26,6 +26,7 @@ bun install
 
 - `banhaten.config.json` with schema-backed aliases.
 - The base `cn` utility and `use-direction` hook.
+- `.banhaten/USAGE.md` with agent-readable defaults, recipes, and component-selection rules.
 - The generated Banhaten token stylesheet in your configured CSS file.
 - Tailwind v4 and Vite alias setup when those files are detected.
 - Required package dependencies.
@@ -35,36 +36,57 @@ bun install
 ## CLI
 
 ```bash
-npx banhaten init [--cwd <path>] [--force] [--dry-run]
-npx banhaten add <component...> [--cwd <path>] [--force] [--dry-run]
-npx banhaten diff [component...] [--cwd <path>] [--force]
-npx banhaten update [component...] [--cwd <path>] [--force] [--dry-run]
+npx banhaten init [--cwd <path>] [--force] [--dry-run] [--json]
+npx banhaten add <component...> [--cwd <path>] [--force] [--dry-run] [--json]
+npx banhaten diff [component...] [--cwd <path>] [--json]
+npx banhaten update [component...] [--cwd <path>] [--force] [--dry-run] [--json]
 npx banhaten list [--json]
 npx banhaten search <query> [--json]
 npx banhaten docs <component> [--json]
 npx banhaten view <component> [--file <registry-source>] [--json]
+npx banhaten doctor [--cwd <path>] [--json]
 npx banhaten version
 ```
 
+The CLI validates each command before doing project work: unknown flags, missing
+flag values, duplicate flags, and unexpected arguments fail without writing.
+Mutating commands then compute one install plan from the configured destinations
+and the existing TypeScript/Vite root aliases. An alias declared on only one side
+is mirrored to the other; conflicting, ambiguous, or dynamic aliases stop before
+files are staged. The install receipt records the resolved destinations so later
+runs cannot silently create a second generated tree.
+
+Dependency ranges follow a guarantee policy: every version admitted by the
+consumer declaration must satisfy Banhaten's requirement. Broader semver ranges
+are safely narrowed when possible and trigger an install hint; partial overlaps,
+disjoint ranges, and opaque package protocols fail without writes. A lockfile is
+never accepted instead of that manifest guarantee. When the manifest is already
+safe, the CLI verifies the bounded installed resolution and npm lock state;
+stale or unverifiable lock state keeps a project-rooted install action visible.
+
+Command flags:
+
+- `--cwd <path>` runs `init`, `add`, `diff`, `update`, or `doctor` against another project directory.
+- `--dry-run` previews `init`, `add`, or `update` writes.
+- `--force` replaces locally modified generated files after you review `banhaten diff`.
+- `--json` prints machine-readable output for commands that show it above.
+
 Global flags:
 
-- `--cwd <path>` runs against another project directory.
-- `--dry-run` previews writes.
-- `--force` rewrites generated files even when already current.
-- `--json` prints machine-readable output where supported.
+- `--help` or `-h` prints help.
 - `--silent` or `-s` suppresses normal command output.
 - `--yes` or `-y` is accepted for non-interactive scripts.
 - `--version` or `-v` prints the CLI version.
 
 ## Generated File Ownership
 
-Banhaten is a source registry. Installed component files are generated from the registry and are replaceable by `banhaten add` or `banhaten update` when registry content differs.
+Banhaten is a source registry. The install receipt records the exact generated hash for every managed file. Unmodified files update automatically; locally modified component files and token blocks are never replaced unless you pass `--force`.
 
 Use `banhaten diff` before updating if you edit generated component files locally:
 
 ```bash
 npx banhaten diff
-npx banhaten update button
+npx banhaten update button --force # only after reviewing intentional replacement
 ```
 
 Keep product-specific composition outside generated files when possible. Use local wrapper components for app behavior and keep Banhaten files focused on tokens, layout, accessibility primitives, and direction behavior.
@@ -73,6 +95,13 @@ Keep product-specific composition outside generated files when possible. Use loc
 
 Every component must style through Banhaten CSS variables, component aliases, or documented exception-ledger values. Raw colors, pixel values, opacity utilities, z-index utilities, durations, and shadow literals are blocked by the component token check.
 
+Structured token values and aliases are authored in the owned fragments under
+`tokens/source/`; `tokens/banhaten.tokens.json` is their compiled publication
+artifact. Tailwind mappings, keyframes, global and accessibility rules, and
+typography utilities are authored in `tokens/banhaten.utilities.css`.
+`registry/styles/globals.css` is generated from the compiled token catalog and
+the utility source; neither generated file should be edited directly.
+
 Token modes:
 
 - Color mode: light and dark.
@@ -80,6 +109,11 @@ Token modes:
 - Radius mode: `default`, `rounded`, `sharp`.
 - Direction: inherited LTR or RTL, with component-level `dir` support where needed.
 
+The default appearance is the `blue` brand theme composed with the achromatic
+`gray` neutral scale. This keeps page, card, border, and muted surfaces neutral
+while links, focus states, and primary actions remain blue. The `gray` theme is
+still a separate monochrome brand option; it changes the brand roles as well.
+
 Example:
 
 ```tsx
@@ -95,23 +129,41 @@ Typography utilities are generated as `.bh-text-*` classes and map directly to t
 
 ## Registry Formats
 
-Banhaten maintains two registry artifacts:
+Banhaten maintains component-owned registry sources and two compiled
+publication artifacts:
 
-- `registry/index.json` is the Banhaten source of truth used by the Banhaten CLI. It includes rich metadata for RTL behavior, parts, examples, files, and dependencies.
+- `registry/catalog/components/<id>.json` owns each component contract, while
+  `registry/catalog/base.json` and `manifest.json` own the shared contract and
+  publication order.
+- `registry/index.json` is the compiled Banhaten artifact used by the CLI. It
+  includes an exhaustive, module-aware `supportedExports` runtime contract plus
+  non-exhaustive `parts` anatomy, RTL behavior, examples, files, and
+  dependencies.
 - `registry.json` is a generated shadcn-compatible export for tools that expect the public shadcn registry schema.
 
-Regenerate the shadcn-compatible export after registry changes:
+Compile both registry publication artifacts after authored catalog changes:
 
 ```bash
 npm run registry:export
 ```
 
+`supportedExports` is checked against the installed TypeScript modules during
+`npm run registry:check`; a renamed, moved, added, or removed runtime export
+fails the release gate. Run `npm run registry:exports` only after reviewing an
+intentional public runtime API change. Type-only exports are outside this
+manifest. `parts` remains an ordered composition aid and does not claim API
+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.
 
 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).
+
+The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, contrast exception, and deliberate non-copying decision.
+
 Useful commands:
 
 ```bash

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Until Banhaten reaches 1.0, security fixes are applied to the latest published minor release. Consumers should keep the CLI and copied registry components current.
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately through GitHub’s security-advisory workflow for this repository. Do not open a public issue containing exploit details, credentials, or consumer data.
+
+Include the affected Banhaten version, component or CLI command, reproduction steps, impact, and any known mitigation. Maintainers will acknowledge a complete report, assess severity, and coordinate a fix and disclosure.
+
+## Scope
+
+The CLI, registry source, generated CSS, dependency declarations, documentation application, and release artifacts are in scope. Vulnerabilities in an upstream dependency should also be reported to that upstream project when appropriate.

package/banhaten.config.example.json

@@ -1,7 +1,5 @@
 {
   "$schema": ".banhaten/schema/config.schema.json",
-  "style": "default",
-  "tsx": true,
   "tailwind": {
     "css": "app/globals.css"
   },

package/docs/design-system/README.md

@@ -3,8 +3,17 @@
 Use these docs with the live playground.
 
 - [Registry and CLI](./registry-and-cli.md): registry formats, generated-file ownership, CLI commands, and schema behavior.
+- [Installation](./installation.md): Vite, Next.js/framework-neutral setup, fonts, direction, and safe updates.
 - [Token Governance](./token-governance.md): token-only component rules, exception ledger, and public override surface.
 - [Appearance Presets](./appearance-presets.md): theme and radius mode guidance.
+- [Direction and Localization](./direction-and-localization.md): inherited LTR/RTL and product localization responsibilities.
+- [Form Recipes](./form-recipes.md): accessible Field composition, validation, selection, dates, and RTL.
+- [Density and Elevation](./density-and-elevation.md): supported size contracts and semantic shadow layers.
+- [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.
+- [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.
 - [Icon System](./icons.md): icon guidance and explorer notes.
 

package/docs/design-system/adoption-quality-remediation.md

@@ -0,0 +1,87 @@
+# Adoption Quality Remediation
+
+This checklist turns the Field Index audit into an implementation program. The
+work is ordered so application recipes depend on stable component contracts,
+and enforcement depends on documented recipes.
+
+## 1. Shared control density
+
+- [x] Add the semantic densities `compact` (32px), `default` (36px), and
+  `comfortable` (40px) to Input, Select, Date Picker, Button, Button Group,
+  Segmented Control, and Toolbar controls.
+- [x] Keep existing component-specific `size` props as compatibility aliases.
+- [x] Add a cross-component conformance example and automated height checks.
+- [x] Document the semantic density matrix and precedence rules.
+
+Acceptance: controls using the same `density` render at the same physical
+height, regardless of their legacy size names.
+
+## 2. Truthful machine-readable defaults
+
+- [x] Add explicit capability defaults to the registry schema.
+- [x] Stop inferring defaults from the first capability value.
+- [x] Record explicit defaults for the control family.
+- [x] Validate that every recorded default belongs to its capability list.
+
+Acceptance: generated API documentation agrees with runtime defaults.
+
+## 3. Input icon and shortcut contracts
+
+- [x] Replace ambiguous icon booleans with explicit `showAtSign` and `showInfo`
+  props while retaining deprecated aliases.
+- [x] Add a reusable keyboard-shortcut composition to Kbd.
+- [x] Make Input and Toolbar Search use the shared shortcut composition.
+- [x] Document search fields and date fields without implicit icons.
+
+Acceptance: a generic leading-icon request can no longer accidentally produce
+an at-sign in new code, and shortcuts use consistent keycaps.
+
+## 4. Segmented selection and application recipes
+
+- [x] Add a content-width Segmented Control with an optional non-interactive
+  label segment.
+- [x] Add a canonical Collection Filter Bar recipe.
+- [x] Add a canonical Results Toolbar recipe with cards-per-row selection.
+- [x] Cover responsive, LTR, and RTL compositions.
+
+Acceptance: the controls visible in the Field Index screenshot can be composed
+without raw heights, padding, radii, or bespoke segmented buttons.
+
+## 5. Agent and consumer adoption contract
+
+- [x] Install `.banhaten/USAGE.md` during `banhaten init`.
+- [x] Add machine-readable recommendation and avoidance guidance to relevant
+  registry entries.
+- [x] Add a read-only `banhaten doctor` command for version, drift, raw control
+  geometry, ambiguous icon props, and native-control diagnostics.
+- [x] Test text and JSON doctor output.
+
+Acceptance: an agent receives actionable rules before composing a page, and a
+consumer can detect the most common forms of design-system drift.
+
+## 6. Documentation reliability
+
+- [x] Replace fixed multi-column component grids with container-safe layouts.
+- [x] Make documentation section anchors compatible with the hash router.
+- [x] Stabilize calendar tests by controlling the displayed month.
+- [x] Add navigation and overflow regression tests.
+
+Acceptance: documentation examples do not overlap and section links preserve
+the active component page.
+
+## 7. Visual and governance gates
+
+- [x] Add visual baselines for the control family and the two golden recipes.
+- [x] Add critical control-text contrast checks rather than relying only on the
+  frozen global contrast debt.
+- [x] Generate a recurring-gap promotion report from background scenarios.
+- [x] Document the promotion rule for gaps that recur in three or more
+  backgrounds.
+
+Acceptance: component-family drift fails CI, critical controls have explicit
+contrast protection, and recurring application gaps become owned system work.
+
+## Validation
+
+- [x] Registry, token, documentation, CLI, component, and browser checks pass.
+- [x] The repository remains free of generated-artifact drift.

package/docs/design-system/agent-usage.md

@@ -0,0 +1,13 @@
+# Agent usage
+
+`banhaten init` installs `.banhaten/USAGE.md` into every consumer project. Include that file in coding-agent context so generated and redesigned screens use registry defaults and recipes instead of reconstructing the visual language from memory.
+
+The workflow is intentionally inspectable:
+
+1. `banhaten search <need>` discovers the intended primitive.
+2. `banhaten docs <component>` returns explicit defaults, fit guidance, avoid rules, and recipes.
+3. `banhaten view <component>` exposes the installed source contract.
+4. `banhaten doctor` reports installed-version drift, local managed-file drift, deprecated ambiguous props, raw geometry overrides, native date/select controls, and missing guidance.
+5. `banhaten diff` previews registry updates without writing.
+
+For collection screens, start with the filter-bar and results-toolbar recipes in [Form Recipes](./form-recipes.md). For mixed control rows, follow [Density and Elevation](./density-and-elevation.md).

package/docs/design-system/appearance-presets.md

@@ -131,7 +131,12 @@ The design system should use semantic tokens instead of importing naming pattern
 
 Components consume semantic tokens and component-scoped aliases. They must not hard-code preset-specific values or Figma fallback literals in component source.
 
-If a Figma reference exposes a literal color, size, radius, shadow, or opacity, promote it into the generated token contract or a component-level `--bh-*` alias in `registry/styles/globals.css`, then consume that token from the component. Component docs may record Figma references for audit and QA, but those literals are not implementation fallbacks.
+If a Figma reference exposes a literal color, size, radius, shadow, or opacity,
+promote it into the appropriate owned fragment under `tokens/source/`, then
+consume that token from the component. Reserve `tokens/banhaten.utilities.css`
+for authored global CSS that cannot be represented as token data. Component
+docs may record Figma references for audit and QA, but those literals are not
+implementation fallbacks.
 
 Good:
 

package/docs/design-system/component-docs-pattern.md

@@ -0,0 +1,81 @@
+# Component documentation pattern
+
+Every component page in the playground renders through one shell so the docs
+read the same way from component to component. A page is not "documented" until
+it follows this shape.
+
+## The shape
+
+```
+Header
+Anchor nav
+1. Base           the component with no options applied
+2. Anatomy        live-measured specs, mapped back to tokens
+3. Alternatives   every supported variation, one card each
+4. Installation / Usage / Composition / API / RTL / Live Variants
+```
+
+Sections 4 and below are generated from `registry/index.json` by
+`RegistryComponentDocs`. Sections 1 to 3 are authored per component.
+
+## Writing a page
+
+```tsx
+import { ComponentDocPage, type DocAlternative } from "./shared/component-doc-page"
+
+export function BadgePage({ tokens }: { tokens: Record<string, string> }) {
+  return (
+    <ComponentDocPage
+      componentId="badge"
+      title="Badge"
+      description="…"
+      tokens={tokens}
+      base={{ children: <Badge>Badge</Badge>, code: baseCode }}
+      anatomy={{
+        options: [
+          { id: "size", label: "Size", values: [{ id: "sm", label: "sm" }, { id: "lg", label: "lg" }] },
+          { id: "type", label: "Type", values: […] },
+        ],
+        render: (selection) => <Badge size={selection.size as "sm" | "lg"}>Badge</Badge>,
+      }}
+      alternatives={badgeAlternatives}
+    />
+  )
+}
+```
+
+`playground/src/pages/BadgePage.tsx` is the reference implementation.
+
+## Anatomy
+
+The inspector in `playground/src/pages/shared/anatomy/` measures the rendered
+DOM rather than reading hand-written numbers, so a spec can never drift from the
+component that ships.
+
+- The **first** option group becomes the rows of the spec matrix. Every value in
+  it is rendered off-screen and measured, so the matrix shows all sizes at once.
+- Remaining groups become scrub toggles.
+- Hovering a spec value highlights the matching segment on the diagram; hovering
+  a row switches the diagram to that variant.
+- Each measured value is reverse-mapped to the `--bh-*` token that produced it.
+  A value with no matching token renders in the warning color with a `!` — that
+  is a real finding, not a display bug: it means the component hard-codes a
+  length instead of using the scale.
+- Rulers and offsets are logical, so the whole diagram mirrors correctly in RTL
+  while the measurements stay identical.
+
+Pass `measureSelector` when the rendered root is a wrapper rather than the
+component itself.
+
+Omit `anatomy` only for components with no inline measurable root: portal-only
+overlays and canvas-style components.
+
+## Enforcement
+
+`playground/e2e/docs-consistency.spec.ts` asserts that every component and
+pattern page renders a Base section, an Alternatives section, and an Anatomy
+inspector with at least one measured row, and logs no console errors.
+
+```bash
+npm --prefix playground run test:browser
+```

package/docs/design-system/component-token-consistency-audit.md

@@ -16,7 +16,12 @@ This audit is focused on whether component color, spacing, sizing, radius, typog
 
 Current automated coverage:
 
-- `scripts/generate-token-css.mjs` imports `componentAliasDeclarations()` and emits component aliases into `registry/styles/globals.css`.
+- The token catalog compiler merges the owned `tokens/source/` fragments into
+  `tokens/banhaten.tokens.json`; `scripts/generate-token-css.mjs` combines that
+  compiled contract with `tokens/banhaten.utilities.css` and emits
+  `registry/styles/globals.css` without reading either generated output as an
+  authored input.
+- `scripts/check-token-css-reproducibility.mjs` runs the generator in a clean temporary tree with no previous `globals.css` and verifies equivalent generated content after line-ending normalization.
 - `scripts/check-token-contract.mjs` verifies those component aliases exist in the generated CSS.
 - `scripts/check-component-token-usage.mjs` scans `registry/components` for raw component-source values.
 - `scripts/check-registry-mirrors.mjs` verifies playground mirrors stay in sync with registry files.
@@ -25,7 +30,9 @@ Current automated coverage:
 
 The component library is mostly token-consistent now. The major items from the previous audit have been completed:
 
-- Component aliases are centralized in `scripts/component-token-aliases.mjs`.
+- Component aliases have explicit owners under `tokens/source/` and compile into
+  one publication artifact; JavaScript no longer carries a second token source.
+- Tailwind mappings, keyframes, global rules, accessibility rules, and typography utilities are authored in `tokens/banhaten.utilities.css`; generated CSS is output-only.
 - Generated CSS is current.
 - Component aliases are contract-checked.
 - Registry component source passes the token-usage check.
@@ -58,7 +65,10 @@ Recommended pattern target:
 
 ### P2: Create A Formal Exception Ledger For Non-Token Literals In Alias Source
 
-Raw values inside `scripts/component-token-aliases.mjs` are no longer leaking into component source, but several are intentional external or Figma-specific values. Document them so future cleanup does not accidentally erase brand/media fidelity.
+Raw contract values in the authored token fragments are no longer leaking into
+component source. Intentional external or Figma-specific values carry a type and
+stay reviewable under their canonical owner so future cleanup does not
+accidentally erase brand/media fidelity.
 
 Document as approved exceptions or promote into a clearer token group:
 

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

@@ -24,7 +24,6 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Checkbox](./checkbox.md): Radix checkbox primitive plus checkbox-card composition with selected, disabled, hover, and RTL states.
 - [Collapsible](./collapsible.md): Radix Collapsible wrapper for disclosure sections with tokenized trigger and content slots.
 - [Command](./command.md): cmdk-backed command menu with search, groups, shortcuts, separators, and empty state.
-- [Command Bar](./command-bar.md): keyboard-friendly command palette with search, recent items, results, empty states, and RTL support.
 - [Context Menu](./context-menu.md): Radix ContextMenu-backed right-click menu with labels, separators, submenus, checks, radios, and shortcuts.
 - [Date Picker](./date-picker.md): calendar and range-picker suite with presets, open states, triggers, time rows, and RTL support.
 - [Divider](./divider.md): horizontal and vertical separator with solid or dotted rules.
@@ -36,6 +35,7 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Input](./input.md): text-entry field with labels, helper and error text, add-ons, tags, shortcuts, adornments, and RTL states.
 - [Input Group](./input-group.md): grouped input shell for protocol add-ons, inline actions, prefixes, suffixes, and compact rows.
 - [Input OTP](./input-otp.md): one-time-code field with grouped slots, paste distribution, masked values, hidden form value, and RTL keyboard behavior.
+- [Item](./item.md): composable list and action row with media, content, title, description, actions, separators, variants, sizes, and token-only styling.
 - [Kbd](./kbd.md): keyboard hint primitive for shortcuts, command rows, and form help text.
 - [Label](./label.md): Radix-backed accessible label primitive with required, optional, tone, disabled, and RTL-safe text behavior.
 - [Menu](./menu.md): Radix DropdownMenu-backed command surface with rich item slots, submenus, progress rows, labels, captions, and RTL layout.
@@ -45,13 +45,14 @@ Design-system components use semantic props and tokens. Appearance presets may c
 - [Navigation Menu](./navigation-menu.md): Radix NavigationMenu-backed top navigation with trigger, content, link, viewport, and indicator parts.
 - [Onboarding Step List Item](./onboarding-step-list-item.md): vertical progress-list row with finished, active, and inactive states plus RTL support.
 - [Page Header](./page-header.md): page hierarchy, title metadata, actions, description, and local tabs.
-- [Pagination](./pagination.md): numeric, simple, and summary pagination layouts with soft or ghost styling, captions, and RTL labels.
+- [Pagination](./pagination.md): numeric, simple, and summary pagination layouts with soft or ghost styling, captions, RTL layout, and explicit localized messages.
 - [Popover](./popover.md): contextual overlay primitive with click, focus, hover, positioning, arrows, close affordance, and RTL-safe composition.
 - [Progress](./progress.md): read-only progress meter with value fill, labels, helper text, indicator, spinner, and RTL support.
 - [Progress Slider](./progress-slider.md): Radix Slider-based progress control with start-anchored fill, semantic tones, ticks, and RTL keyboard behavior.
 - [Radio Card](./radio-card.md): rich single-choice option card with Figma content types, active/disabled states, and explicit RTL variants.
 - [Radio Group](./radio-group.md): native-input radio group with labels, descriptions, errors, controlled/uncontrolled values, and RTL-safe field rows.
 - [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.
 - [Sheet](./sheet.md): Radix Dialog-based edge panel with logical start/end placement, top/bottom placement, size variants, and RTL support.
 - [Sidebar](./sidebar.md): composable app sidebar with collapse state, grouped menu items, logical placement, and sidebar tokens.

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

@@ -49,3 +49,19 @@ Open the live component page or run `npx banhaten docs accordion` to inspect sou
 - `inheritsDirection`: true
 - `textAlignment`: Uses text-start and dir="auto" so Arabic and English copy align and punctuate naturally.
 - `spacing`: Uses gap and logical inherited direction rather than physical left/right spacing.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/accordion.tsx: Accordion, AccordionContent, AccordionItem, AccordionTrigger, accordionVariants` |
+| `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` |
+| `variants` | `default`, `bordered`, `cards`, `soft` |
+<!-- registry-contract:end -->

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

@@ -47,7 +47,7 @@ The Figma component defines these top-level variants:
 
 ## Token Contract
 
-The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
 
 - Backgrounds: `--bh-bg-raised`, `--bh-bg-success-default`
 - Borders: `--bh-border-default`, `--bh-border-subtle`
@@ -90,3 +90,17 @@ Open the live component page or run `npx banhaten docs activity-feed` to inspect
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/expanded/ActivityFeed.tsx: ActivityFeed, ActivityFeedItem` |
+| `parts` | `ActivityFeed`, `ActivityFeedItem` |
+| `registryDependencies` | `button` |
+| `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` |
+<!-- registry-contract:end -->

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

@@ -68,3 +68,20 @@ Open the live component page or run `npx banhaten docs alert-dialog` to inspect
 - `textDirection`: Title and description use dir="auto" for Arabic and English copy.
 - `spacing`: Header, body, and footer use logical layout and Banhaten spacing tokens so action order and copy mirror naturally.
 - `semantics`: Radix AlertDialog provides the modal alert role, focus trap, and safe cancellation behavior.
+
+<!-- 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/alert-dialog.tsx: AlertDialog, AlertDialogAction, AlertDialogBody, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogIcon, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, alertDialogContentVariants` |
+| `parts` | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogPortal`, `AlertDialogOverlay`, `AlertDialogHeader`, `AlertDialogIcon`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogBody`, `AlertDialogFooter`, `AlertDialogCancel`, `AlertDialogAction` |
+| `registryDependencies` | `button` |
+| `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-component-default`, `--shadow-modal` |
+<!-- registry-contract:end -->