banhaten 0.3.0 → 0.5.0

package/docs/design-system/launch-comparison-shadcn.md

@@ -1,98 +1,98 @@
-# Launch Comparison: Banhaten and shadcn/ui
-
-Benchmark references reviewed against the official shadcn/ui CLI, registry, theming, and RTL documentation on 2026-07-10; Banhaten implementation status refreshed on 2026-08-20. shadcn/ui is the distribution and documentation benchmark—not Banhaten’s visual source.
-
-## Outcome
-
-Banhaten is a launch candidate with a distinct product contract: Arabic and English-first typography, inherited RTL by default, seven brand themes, three radius modes, stable primitives separated from larger Patterns, and a hard rule that distributable components consume canonical Banhaten tokens.
-
-The former color-contrast exception is closed. The reviewed semantic-role corrections preserve the Banhaten palette while selecting valid foreground/background roles across themes and states. The Color Contrast page now evaluates 910 theme/mode scenarios and reports **910 passes and 0 failures**, with every pair, score, threshold, state, and swatch retained as inspectable evidence.
-
-## Benchmark Summary
-
-| Area | shadcn/ui benchmark | Banhaten launch answer | Status |
-| --- | --- | --- | --- |
-| Distribution | Source registry and CLI installation | Canonical Banhaten registry plus generated shadcn-compatible `registry.json` | Verified |
-| Component ownership | Copied source is consumer-owned | Receipt-backed generated ownership; local drift blocks updates unless explicitly forced | Stronger safety |
-| Registry dependencies | Dependency closure and typed registry items | Dependency graph, schema validation, mirror checks, and isolated compilation of all 68 items | Verified |
-| CLI | `init`, `add`, `view`, `docs`, migrations, presets | `init`, `add`, real `diff`, safe `update`, `list`, `search`, full `docs`, and `view` | Launch scope verified |
-| Framework setup | Multiple framework templates | Vite auto-configuration and framework-neutral/Next-style source installation | Verified |
-| Package managers | npm, pnpm, Yarn, Bun | Detection and install hints tested for all four | Verified |
-| Theming | CSS variables, dark mode, presets | Live semantic aliases, light/dark, seven brand themes, three radius modes | Verified |
-| Token contract | Optional CSS-variable path | CSS variables are mandatory; raw component colors, sizes, opacity, duration, z-index, shadow, and generic internal aliases fail CI | Banhaten-specific |
-| RTL | First-class RTL and install-time transformations | Authored logical layout, inherited direction hook/provider, Arabic font, explicit message catalogs, and RTL keyboard tests | Banhaten-specific |
-| Documentation | Live preview/code, component examples, API and CLI docs | Live registry previews, exact example source, extracted TypeScript props, token contract, accessibility contract, RTL, files, navigation/token search, and copy actions | Verified |
-| Components vs blocks | Components and larger blocks | Stable Components and broader Patterns; experiments and visual QA isolated under Lab | Verified |
-| Accessibility | Primitive semantics and per-component guidance | Native/Radix semantics, focus handling, dialog traps, tabs contract, reduced motion, forced colors, 910/910 contrast, strict route Axe, and Chromium/Firefox/WebKit tests | Verified |
-| Release governance | Changelog and frequent CLI/schema evolution | Changelog, security, contributing, support matrix, stability tiers, deprecation, release gate, and roadmap | Verified |
-
-## Full Finding Register
-
-### Components and behavior
-
-- Removed sample titles, images, actions, close controls, dates, time rows, and no-op callbacks from production defaults. Examples now own demonstration content.
-- Added Item and controlled/uncontrolled Toggle Group APIs, including single/multiple selection and RTL-aware keyboard movement.
-- Repaired Command Bar search/clear/submit behavior, Table disabled/action behavior, File Upload progress semantics, Spinner reduced-motion behavior, and Date Picker presets/month-year interaction.
-- Standardized direction resolution for Alert, Pagination, Input OTP, Carousel, and Toast through explicit props, `DirectionProvider`, nearest `[dir]`, then document direction.
-- Corrected Arabic Pagination copy and kept product strings explicit rather than silently localizing demo text.
-- Added focused behavior tests; the component suite currently runs 205 tests.
-
-### Colors and tokens
-
-- Repaired semantic foreground/background role selection across component states while preserving the canonical palette; all 910 generated contrast combinations now pass.
-- Split system, typography, effects, component variables, dark effects, and
-  scoped aliases into owned `tokens/source/` fragments that compile to
-  `tokens/banhaten.tokens.json`.
-- Generated live `var(...)` alias graphs rather than flattened semantic values and verified custom-property closure.
-- Added named categorical chart semantics, spinner/skeleton/motion tokens, exact icon stroke tokens, Item tokens, default border/transition wiring, reduced motion, and forced-color focus rules.
-- Generated exact component token metadata from source. All 68 registry components have non-empty, current token contracts.
-- Deduplicated theme CSS against the default cascade and kept generated CSS at 156,729 bytes after the accessibility and component-token additions.
-- Documented the no-global-density decision and the semantic elevation hierarchy.
-
-### Usage and composition
-
-- Added installation, direction/localization, form recipes, density/elevation, support, roadmap, and release-policy guides.
-- Separated stable Components from broader Patterns and isolated Component Matrix, Theme Test, Theme Lab, and screenshot review under Lab/Visual QA.
-- Added explicit TypeScript prop source, token contract, accessibility contract, composition notes, RTL behavior, and registry file links to shared component documentation.
-- Added searchable/copyable token pages with computed values and `var(--token)` usage syntax.
-
-### Installation and registry
-
-- Added Inter and IBM Plex Sans Arabic weights 400–700 automatically and composed them through font-family tokens.
-- Removed dead `style` and `tsx` config fields; config now contains only settings the CLI honors.
-- Added real unified diff output and SHA-256 ownership receipts for base files, components, and the generated token block.
-- Prevented `add` and `update` from overwriting local edits without `--force`; transactions roll back on failure.
-- Kept CSS outside the marked Banhaten token block intact and protected edits inside the generated block.
-- Tested Vite, non-Vite/Next-style projects, dependency conflicts, JSONC aliases, unsupported Vite config rollback, npm, pnpm, Yarn, and Bun.
-- Generated a current shadcn-compatible registry and compiled every registry component in isolation.
-- Removed design-source ZIP archives from the published package while keeping the canonical JSON contract and required registry assets.
-
-### Documentation and presentation
-
-- Removed launch-blocking `noindex`, added description/social metadata, dynamic page titles, skip link, release status/version, and responsive searchable navigation.
-- Reframed the overview around quick start, token rules, safe updates, and the now-enforced contrast contract.
-- Added focus trap, Escape, initial focus, and focus return to Customize and Component Matrix dialogs.
-- Completed Preview/Code tab IDs, `aria-controls`, `aria-labelledby`, roving focus, and keyboard navigation.
-- Renamed ambiguous “Copy Page” to “Copy page link” and added clipboard fallback.
-- Changed the CLI `docs` command from a path hint to the complete packaged component documentation plus metadata.
-
-### Verification and release
-
-- Browser checks cover Chromium, Firefox, and WebKit; visual baselines stay on Chromium for deterministic snapshots.
-- Automated checks cover LTR/RTL behavior, portals, focus return, docs navigation, mobile navigation, token copy/search, live theme overrides, the 910/910 contrast totals, reduced motion, forced colors, and strict route-wide Axe findings without a color-rule exception.
-- Bundle budgets, schema validation, token generation, token-only styling, registry mirrors, documentation coverage, CLI integration, isolated installs, package audit, and tarball contents are release gates.
-
-## Deliberate Differences, Not Missing Copies
-
-Banhaten does not copy shadcn’s preset marketplace, `create` templates, registry namespaces, programmatic registry API, or migration catalog for launch. Those are distribution-platform capabilities, not component-quality requirements. They belong on the roadmap only when Banhaten has a concrete consumer need and maintenance owner.
-
-Banhaten also does not support opting out of CSS variables: the canonical token graph is the mechanism that keeps themes, Arabic typography, accessibility modes, and every component aligned. That constraint is intentional and is the core of Banhaten’s visual independence.
-
-## Reference Benchmark
-
-- [shadcn/ui CLI](https://ui.shadcn.com/docs/cli)
-- [shadcn/ui registry schema](https://ui.shadcn.com/docs/registry/registry-json)
-- [shadcn/ui registry API](https://ui.shadcn.com/docs/registry/api-reference)
-- [shadcn/ui theming](https://ui.shadcn.com/docs/theming)
-- [shadcn/ui RTL](https://ui.shadcn.com/docs/rtl)
-- [shadcn/ui changelog](https://ui.shadcn.com/docs/changelog)
+# Launch Comparison: Banhaten and shadcn/ui
+
+Benchmark references reviewed against the official shadcn/ui CLI, registry, theming, and RTL documentation on 2026-07-10; Banhaten implementation status refreshed on 2026-08-20. shadcn/ui is the distribution and documentation benchmark—not Banhaten’s visual source.
+
+## Outcome
+
+Banhaten is a launch candidate with a distinct product contract: Arabic and English-first typography, inherited RTL by default, seven brand themes, three radius modes, stable primitives separated from larger Patterns, and a hard rule that distributable components consume canonical Banhaten tokens.
+
+The former color-contrast exception is closed. The reviewed semantic-role corrections preserve the Banhaten palette while selecting valid foreground/background roles across themes and states. The Color Contrast page now evaluates 910 theme/mode scenarios and reports **910 passes and 0 failures**, with every pair, score, threshold, state, and swatch retained as inspectable evidence.
+
+## Benchmark Summary
+
+| Area | shadcn/ui benchmark | Banhaten launch answer | Status |
+| --- | --- | --- | --- |
+| Distribution | Source registry and CLI installation | Canonical Banhaten registry plus generated shadcn-compatible `registry.json` | Verified |
+| Component ownership | Copied source is consumer-owned | Receipt-backed generated ownership; local drift blocks updates unless explicitly forced | Stronger safety |
+| Registry dependencies | Dependency closure and typed registry items | Dependency graph, schema validation, mirror checks, and isolated compilation of all 68 items | Verified |
+| CLI | `init`, `add`, `view`, `docs`, migrations, presets | `init`, `add`, real `diff`, safe `update`, `list`, `search`, full `docs`, and `view` | Launch scope verified |
+| Framework setup | Multiple framework templates | Vite auto-configuration and framework-neutral/Next-style source installation | Verified |
+| Package managers | npm, pnpm, Yarn, Bun | Detection and install hints tested for all four | Verified |
+| Theming | CSS variables, dark mode, presets | Live semantic aliases, light/dark, seven brand themes, three radius modes | Verified |
+| Token contract | Optional CSS-variable path | CSS variables are mandatory; raw component colors, sizes, opacity, duration, z-index, shadow, and generic internal aliases fail CI | Banhaten-specific |
+| RTL | First-class RTL and install-time transformations | Authored logical layout, inherited direction hook/provider, Arabic font, explicit message catalogs, and RTL keyboard tests | Banhaten-specific |
+| Documentation | Live preview/code, component examples, API and CLI docs | Live registry previews, exact example source, extracted TypeScript props, token contract, accessibility contract, RTL, files, navigation/token search, and copy actions | Verified |
+| Components vs blocks | Components and larger blocks | Stable Components and broader Patterns; experiments and visual QA isolated under Lab | Verified |
+| Accessibility | Primitive semantics and per-component guidance | Native/Radix semantics, focus handling, dialog traps, tabs contract, reduced motion, forced colors, 910/910 contrast, strict route Axe, and Chromium/Firefox/WebKit tests | Verified |
+| Release governance | Changelog and frequent CLI/schema evolution | Changelog, security, contributing, support matrix, stability tiers, deprecation, release gate, and roadmap | Verified |
+
+## Full Finding Register
+
+### Components and behavior
+
+- Removed sample titles, images, actions, close controls, dates, time rows, and no-op callbacks from production defaults. Examples now own demonstration content.
+- Added Item and controlled/uncontrolled Toggle Group APIs, including single/multiple selection and RTL-aware keyboard movement.
+- Repaired Command Bar search/clear/submit behavior, Table disabled/action behavior, File Upload progress semantics, Spinner reduced-motion behavior, and Date Picker presets/month-year interaction.
+- Standardized direction resolution for Alert, Pagination, Input OTP, Carousel, and Toast through explicit props, `DirectionProvider`, nearest `[dir]`, then document direction.
+- Corrected Arabic Pagination copy and kept product strings explicit rather than silently localizing demo text.
+- Added focused behavior tests; the component suite currently runs 205 tests.
+
+### Colors and tokens
+
+- Repaired semantic foreground/background role selection across component states while preserving the canonical palette; all 910 generated contrast combinations now pass.
+- Split system, typography, effects, component variables, dark effects, and
+  scoped aliases into owned `tokens/source/` fragments that compile to
+  `tokens/banhaten.tokens.json`.
+- Generated live `var(...)` alias graphs rather than flattened semantic values and verified custom-property closure.
+- Added named categorical chart semantics, spinner/skeleton/motion tokens, exact icon stroke tokens, Item tokens, default border/transition wiring, reduced motion, and forced-color focus rules.
+- Generated exact component token metadata from source. All 68 registry components have non-empty, current token contracts.
+- Deduplicated theme CSS against the default cascade and kept generated CSS at 156,729 bytes after the accessibility and component-token additions.
+- Documented the no-global-density decision and the semantic elevation hierarchy.
+
+### Usage and composition
+
+- Added installation, direction/localization, form recipes, density/elevation, support, roadmap, and release-policy guides.
+- Separated stable Components from broader Patterns and isolated Component Matrix, Theme Test, Theme Lab, and screenshot review under Lab/Visual QA.
+- Added explicit TypeScript prop source, token contract, accessibility contract, composition notes, RTL behavior, and registry file links to shared component documentation.
+- Added searchable/copyable token pages with computed values and `var(--token)` usage syntax.
+
+### Installation and registry
+
+- Added Inter and IBM Plex Sans Arabic weights 400–700 automatically and composed them through font-family tokens.
+- Removed dead `style` and `tsx` config fields; config now contains only settings the CLI honors.
+- Added real unified diff output and SHA-256 ownership receipts for base files, components, and the generated token block.
+- Prevented `add` and `update` from overwriting local edits without `--force`; transactions roll back on failure.
+- Kept CSS outside the marked Banhaten token block intact and protected edits inside the generated block.
+- Tested Vite, non-Vite/Next-style projects, dependency conflicts, JSONC aliases, unsupported Vite config rollback, npm, pnpm, Yarn, and Bun.
+- Generated a current shadcn-compatible registry and compiled every registry component in isolation.
+- Removed design-source ZIP archives from the published package while keeping the canonical JSON contract and required registry assets.
+
+### Documentation and presentation
+
+- Removed launch-blocking `noindex`, added description/social metadata, dynamic page titles, skip link, release status/version, and responsive searchable navigation.
+- Reframed the overview around quick start, token rules, safe updates, and the now-enforced contrast contract.
+- Added focus trap, Escape, initial focus, and focus return to Customize and Component Matrix dialogs.
+- Completed Preview/Code tab IDs, `aria-controls`, `aria-labelledby`, roving focus, and keyboard navigation.
+- Renamed ambiguous “Copy Page” to “Copy page link” and added clipboard fallback.
+- Changed the CLI `docs` command from a path hint to the complete packaged component documentation plus metadata.
+
+### Verification and release
+
+- Browser checks cover Chromium, Firefox, and WebKit; visual baselines stay on Chromium for deterministic snapshots.
+- Automated checks cover LTR/RTL behavior, portals, focus return, docs navigation, mobile navigation, token copy/search, live theme overrides, the 910/910 contrast totals, reduced motion, forced colors, and strict route-wide Axe findings without a color-rule exception.
+- Bundle budgets, schema validation, token generation, token-only styling, registry mirrors, documentation coverage, CLI integration, isolated installs, package audit, and tarball contents are release gates.
+
+## Deliberate Differences, Not Missing Copies
+
+Banhaten does not copy shadcn’s preset marketplace, `create` templates, registry namespaces, programmatic registry API, or migration catalog for launch. Those are distribution-platform capabilities, not component-quality requirements. They belong on the roadmap only when Banhaten has a concrete consumer need and maintenance owner.
+
+Banhaten also does not support opting out of CSS variables: the canonical token graph is the mechanism that keeps themes, Arabic typography, accessibility modes, and every component aligned. That constraint is intentional and is the core of Banhaten’s visual independence.
+
+## Reference Benchmark
+
+- [shadcn/ui CLI](https://ui.shadcn.com/docs/cli)
+- [shadcn/ui registry schema](https://ui.shadcn.com/docs/registry/registry-json)
+- [shadcn/ui registry API](https://ui.shadcn.com/docs/registry/api-reference)
+- [shadcn/ui theming](https://ui.shadcn.com/docs/theming)
+- [shadcn/ui RTL](https://ui.shadcn.com/docs/rtl)
+- [shadcn/ui changelog](https://ui.shadcn.com/docs/changelog)

package/docs/design-system/registry-and-cli.md

@@ -1,64 +1,64 @@
-# Registry And CLI
-
-Banhaten maintains one authored registry catalog and publishes two compiled
-registry shapes.
-
-| Artifact | Purpose |
-| --- | --- |
-| `registry/catalog/` | Authored base and component-owned contracts plus the intentional publication order. |
-| `registry/index.json` | Compiled artifact consumed by the Banhaten CLI. Includes exhaustive module-aware runtime exports, non-exhaustive composition parts, files, examples, dependencies, RTL behavior, and design-system capabilities. |
-| `registry.json` | Generated shadcn-compatible export for tools that expect `https://ui.shadcn.com/schema/registry.json`. |
-
-Edit `registry/catalog/components/<id>.json` for a component or
-`registry/catalog/base.json` for shared installation metadata, then run
-`npm run registry:export` to compile `registry/index.json` and `registry.json`.
-
-`npm run package:check` verifies the actual npm tarball rather than the
-worktree: it extracts the archive, derives every required registry source and
-example from the packed index, checks byte-for-byte closure, then runs the
-packed CLI and installs the full component catalog into a clean project.
-
-Each component groups its exhaustive runtime value API under
-`supportedExports`, keyed by the exact registry source module that owns the
-installed import path. The release gate resolves those modules with TypeScript
-and rejects missing, stale, moved, type-only, or newly unlisted runtime values.
-Run `npm run registry:exports` only after reviewing an intentional runtime API
-change. The separate `parts` list is ordered component anatomy for examples and
-composition; it is deliberately non-exhaustive and every part must resolve to a
-supported runtime export.
-
-## Generated Files
-
-Installed files are generated source with receipt-backed ownership hashes. `banhaten add` and `banhaten update` replace a stale file automatically only when its current hash still matches the version Banhaten installed. A locally modified file stops the transaction and remains untouched unless the caller reviews `banhaten diff` and explicitly passes `--force`.
-
-The token stylesheet is generated-owned too. `init`, `add`, and `update` refresh the marked Banhaten token block while preserving CSS outside the block. Local edits inside the marked block receive the same drift protection; place product overrides after the block.
-
-## CLI Commands
-
-```bash
-npx banhaten init
-npx banhaten add button input select
-npx banhaten diff
-npx banhaten update button --force
-npx banhaten list --json
-npx banhaten search input
-npx banhaten docs button
-npx banhaten view button
-npx banhaten doctor
-```
-
-`doctor` is read-only. It reports installed-version drift, missing or modified
-managed files, missing agent guidance, deprecated ambiguous props, local raw
-control geometry, and native date/select controls that bypass the registry.
-
-The CLI resolves one unambiguous package-manager root before printing dependency install hints. Dependency requirements use `semver` containment rather than range overlap: already-narrow consumer ranges are preserved, broader ranges are narrowed only when the complete Banhaten range fits inside them, and partial/disjoint or non-semver declarations stop atomically. A narrowed manifest always produces an install hint; an unchanged manifest suppresses that action only when bounded installed packages and a supported npm lock agree. Other lock formats remain conservative and are reconciled by their selected package manager.
-
-## Schema Files
-
-Schema files live in `schema/`. The CLI copies them into `.banhaten/schema/` so generated `banhaten.config.json` can use a local `$schema` path instead of a fragile external domain:
-
-- `schema/config.schema.json`
-- `schema/registry.schema.json`
-- `schema/tokens.schema.json`
-
-Do not point package metadata or generated config at `banhaten.dev` unless that domain is live and serving the schema files.
+# Registry And CLI
+
+Banhaten maintains one authored registry catalog and publishes two compiled
+registry shapes.
+
+| Artifact | Purpose |
+| --- | --- |
+| `registry/catalog/` | Authored base and component-owned contracts plus the intentional publication order. |
+| `registry/index.json` | Compiled artifact consumed by the Banhaten CLI. Includes exhaustive module-aware runtime exports, non-exhaustive composition parts, files, examples, dependencies, RTL behavior, and design-system capabilities. |
+| `registry.json` | Generated shadcn-compatible export for tools that expect `https://ui.shadcn.com/schema/registry.json`. |
+
+Edit `registry/catalog/components/<id>.json` for a component or
+`registry/catalog/base.json` for shared installation metadata, then run
+`npm run registry:export` to compile `registry/index.json` and `registry.json`.
+
+`npm run package:check` verifies the actual npm tarball rather than the
+worktree: it extracts the archive, derives every required registry source and
+example from the packed index, checks byte-for-byte closure, then runs the
+packed CLI and installs the full component catalog into a clean project.
+
+Each component groups its exhaustive runtime value API under
+`supportedExports`, keyed by the exact registry source module that owns the
+installed import path. The release gate resolves those modules with TypeScript
+and rejects missing, stale, moved, type-only, or newly unlisted runtime values.
+Run `npm run registry:exports` only after reviewing an intentional runtime API
+change. The separate `parts` list is ordered component anatomy for examples and
+composition; it is deliberately non-exhaustive and every part must resolve to a
+supported runtime export.
+
+## Generated Files
+
+Installed files are generated source with receipt-backed ownership hashes. `banhaten add` and `banhaten update` replace a stale file automatically only when its current hash still matches the version Banhaten installed. A locally modified file stops the transaction and remains untouched unless the caller reviews `banhaten diff` and explicitly passes `--force`.
+
+The token stylesheet is generated-owned too. `init`, `add`, and `update` refresh the marked Banhaten token block while preserving CSS outside the block. Local edits inside the marked block receive the same drift protection; place product overrides after the block.
+
+## CLI Commands
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+npx banhaten diff
+npx banhaten update button --force
+npx banhaten list --json
+npx banhaten search input
+npx banhaten docs button
+npx banhaten view button
+npx banhaten doctor
+```
+
+`doctor` is read-only. It reports installed-version drift, missing or modified
+managed files, missing agent guidance, deprecated ambiguous props, local raw
+control geometry, and native date/select controls that bypass the registry.
+
+The CLI resolves one unambiguous package-manager root before printing dependency install hints. Dependency requirements use `semver` containment rather than range overlap: already-narrow consumer ranges are preserved, broader ranges are narrowed only when the complete Banhaten range fits inside them, and partial/disjoint or non-semver declarations stop atomically. A narrowed manifest always produces an install hint; an unchanged manifest suppresses that action only when bounded installed packages and a supported npm lock agree. Other lock formats remain conservative and are reconciled by their selected package manager.
+
+## Schema Files
+
+Schema files live in `schema/`. The CLI copies them into `.banhaten/schema/` so generated `banhaten.config.json` can use a local `$schema` path instead of a fragile external domain:
+
+- `schema/config.schema.json`
+- `schema/registry.schema.json`
+- `schema/tokens.schema.json`
+
+Do not point package metadata or generated config at `banhaten.dev` unless that domain is live and serving the schema files.

package/docs/design-system/release-policy.md

@@ -1,30 +1,30 @@
-# Release Policy
-
-## Stability tiers
-
-| Tier | Promise | Documentation location |
-| --- | --- | --- |
-| Stable component | Supported public API, token contract, accessibility behavior, and migration notes | Components |
-| Pattern | Supported composition with a broader layout and product-integration contract | Patterns |
-| Lab | Evaluation or visual-QA surface; not a supported consumer API | Lab / Visual QA lab |
-
-## Versioning
-
-Banhaten uses semantic versioning. Before 1.0, a minor release may contain a breaking API change, but every breaking change still requires a changelog entry and migration instructions. Patch releases must remain backward compatible.
-
-Deprecations remain documented for at least one minor release before removal. Deprecated exports keep working during that window and include a replacement path.
-
-## Release gate
-
-A release candidate must pass:
-
-1. Canonical schema and token generation checks.
-2. The component token checker with no raw-value or unresolved-variable violations.
-3. CLI integration tests and isolated compilation for every registry component.
-4. LTR and RTL interaction tests, accessibility checks, production build, and bundle budgets.
-5. Documentation coverage for install, usage, examples, API, tokens, direction, accessibility, and migration impact.
-6. Color Contrast report regeneration. Contrast failures are documented; color values change only through an explicit design decision.
-
-## Ownership
-
-Every release has one maintainer responsible for the registry artifact, one design reviewer for token and visual changes, and one accessibility reviewer for interaction or semantic changes. A release is not complete until the changelog and package contents are verified from a packed tarball.
+# Release Policy
+
+## Stability tiers
+
+| Tier | Promise | Documentation location |
+| --- | --- | --- |
+| Stable component | Supported public API, token contract, accessibility behavior, and migration notes | Components |
+| Pattern | Supported composition with a broader layout and product-integration contract | Patterns |
+| Lab | Evaluation or visual-QA surface; not a supported consumer API | Lab / Visual QA lab |
+
+## Versioning
+
+Banhaten uses semantic versioning. Before 1.0, a minor release may contain a breaking API change, but every breaking change still requires a changelog entry and migration instructions. Patch releases must remain backward compatible.
+
+Deprecations remain documented for at least one minor release before removal. Deprecated exports keep working during that window and include a replacement path.
+
+## Release gate
+
+A release candidate must pass:
+
+1. Canonical schema and token generation checks.
+2. The component token checker with no raw-value or unresolved-variable violations.
+3. CLI integration tests and isolated compilation for every registry component.
+4. LTR and RTL interaction tests, accessibility checks, production build, and bundle budgets.
+5. Documentation coverage for install, usage, examples, API, tokens, direction, accessibility, and migration impact.
+6. Color Contrast report regeneration. Contrast failures are documented; color values change only through an explicit design decision.
+
+## Ownership
+
+Every release has one maintainer responsible for the registry artifact, one design reviewer for token and visual changes, and one accessibility reviewer for interaction or semantic changes. A release is not complete until the changelog and package contents are verified from a packed tarball.

package/docs/design-system/roadmap.md

@@ -1,14 +1,14 @@
-# Roadmap
-
-The roadmap separates launch requirements from product-specific expansion. Items below are not stable APIs until they move into Components or Patterns with registry source, tokens, docs, and tests.
-
-| Candidate | Current direction | Gate before promotion |
-| --- | --- | --- |
-| Drawer naming/API | Evaluate whether Sheet and Slideout already cover the use cases | Distinct semantics and migration value |
-| Attachment/file item | Compose Item, File Upload, Progress, and actions first | Repeated product demand and a stable data model |
-| Hijri calendar | Keep calendar formatting in the product layer for launch | Calendar-system adapter, locale rules, keyboard QA, and date-library decision |
-| Compact density mode | Use supported component sizes | Named token mode, target-size guardrails, and full matrix QA |
-| Additional Arabic fonts | IBM Plex Sans Arabic is the installed default | Licensing, loading cost, fallback metrics, and typography review |
-| Framework adapters | Source installation remains framework-neutral | Maintained SSR/CSP tests and clear ownership |
-
-Feature requests should describe the user problem, why existing primitives do not compose cleanly, accessibility requirements, direction/localization impact, and the proposed token contract.
+# Roadmap
+
+The roadmap separates launch requirements from product-specific expansion. Items below are not stable APIs until they move into Components or Patterns with registry source, tokens, docs, and tests.
+
+| Candidate | Current direction | Gate before promotion |
+| --- | --- | --- |
+| Drawer naming/API | Evaluate whether Sheet and Slideout already cover the use cases | Distinct semantics and migration value |
+| Attachment/file item | Compose Item, File Upload, Progress, and actions first | Repeated product demand and a stable data model |
+| Hijri calendar | Keep calendar formatting in the product layer for launch | Calendar-system adapter, locale rules, keyboard QA, and date-library decision |
+| Compact density mode | Use supported component sizes | Named token mode, target-size guardrails, and full matrix QA |
+| Additional Arabic fonts | IBM Plex Sans Arabic is the installed default | Licensing, loading cost, fallback metrics, and typography review |
+| Framework adapters | Source installation remains framework-neutral | Maintained SSR/CSP tests and clear ownership |
+
+Feature requests should describe the user problem, why existing primitives do not compose cleanly, accessibility requirements, direction/localization impact, and the proposed token contract.

package/docs/design-system/support-matrix.md

@@ -1,23 +1,23 @@
-# Support Matrix
-
-| Area | Launch baseline |
-| --- | --- |
-| React | 18.2.x and 19.x; packed registry sources compile against both compatibility floors in CI |
-| React DOM | 18.2.x and 19.x; kept on the same major as React |
-| Tailwind CSS | 4.x |
-| Node | Published CLI and registry: 18.18 or newer, with packed-artifact CI on 18.18.0, 20, and 22; the private playground build toolchain runs on Node 22 |
-| TypeScript | Bundler-style module resolution; copied source is TypeScript/TSX |
-| Browsers | Current stable Chrome/Edge, Firefox, and Safari; previous major versions are best-effort until they are included in automated release testing |
-| Direction | Inherited LTR and RTL; explicit component overrides where documented |
-| Fonts | Inter for Latin and IBM Plex Sans Arabic for Arabic, installed by the CLI |
-| Package managers | npm, pnpm, Yarn, and Bun install hints |
-| Tooling | Vite configured automatically when detected; framework-neutral source installation otherwise |
-
-Internet Explorer and browsers without modern CSS custom properties, logical properties, or ES2022 support are not supported. Consumer applications remain responsible for their framework’s SSR, CSP, and browser-transpilation configuration.
-
-Release verification builds and extracts the real npm tarball, derives its
-required registry file and example closure from the packed index, executes the
-packed CLI from outside the repository, and installs every registry component
-into a clean fixture. React compatibility jobs then compile that packed source
-against exact React 18.2 and React 19 floors instead of relying only on the
-playground lockfile.
+# Support Matrix
+
+| Area | Launch baseline |
+| --- | --- |
+| React | 18.2.x and 19.x; packed registry sources compile against both compatibility floors in CI |
+| React DOM | 18.2.x and 19.x; kept on the same major as React |
+| Tailwind CSS | 4.x |
+| Node | Published CLI and registry: 18.18 or newer, with packed-artifact CI on 18.18.0, 20, and 22; the private playground build toolchain runs on Node 22 |
+| TypeScript | Bundler-style module resolution; copied source is TypeScript/TSX |
+| Browsers | Current stable Chrome/Edge, Firefox, and Safari; previous major versions are best-effort until they are included in automated release testing |
+| Direction | Inherited LTR and RTL; explicit component overrides where documented |
+| Fonts | Inter for Latin and IBM Plex Sans Arabic for Arabic, installed by the CLI |
+| Package managers | npm, pnpm, Yarn, and Bun install hints |
+| Tooling | Vite configured automatically when detected; framework-neutral source installation otherwise |
+
+Internet Explorer and browsers without modern CSS custom properties, logical properties, or ES2022 support are not supported. Consumer applications remain responsible for their framework’s SSR, CSP, and browser-transpilation configuration.
+
+Release verification builds and extracts the real npm tarball, derives its
+required registry file and example closure from the packed index, executes the
+packed CLI from outside the repository, and installs every registry component
+into a clean fixture. React compatibility jobs then compile that packed source
+against exact React 18.2 and React 19 floors instead of relying only on the
+playground lockfile.

package/docs/design-system/tabs.md

@@ -1,53 +1,54 @@
-# Tabs
-
-Tabs switch between peer views while keeping the user in the same context.
-
-The implementation follows the Figma component at `Design system 3.0 Copy / Tabs` (`225:9832`). It supports every variant in the matrix: `underline`, `segment`, and `rounded`; `md`, `sm`, and `xs`; full-width and hug-content layouts; LTR and RTL.
-
-## API
-
-```tsx
-<Tabs
-  variant="underline"
-  size="md"
-  fullWidth={false}
-  dir="ltr"
-  items={["Tab item", "Tab item", "Tab item", "Tab item", "Tab item"]}
-/>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `variant` | `underline`, `segment`, `rounded` | `underline` |
-| `size` | `md`, `sm`, `xs` | `md` |
-| `fullWidth` | `boolean` | `false` |
-| `dir` | `ltr`, `rtl` | `ltr` |
-| `items` | `string[]` | five `Tab item` labels |
-| `activeIndex` | `number` | uncontrolled |
-| `defaultActiveIndex` | `number` | `0` |
-| `onActiveIndexChange` | `(index: number) => void` | none |
-
-## 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 its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
-
-- Backgrounds: `--bh-bg-neutral-subtle`, `--bh-bg-default`
-- Borders: `--bh-border-default`
-- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`
-- Shape: `--bh-radius-md-6`, `--bh-radius-lg-8`, `--bh-radius-full`
-
-## Pixel Rules
-
-- Text is Inter `15px / 24px`.
-- Active labels use weight `500`; inactive labels use weight `400`.
-- Segment and rounded containers use `2px` padding and `2px` item gaps.
-- Underline containers use a `1px` default bottom border and `16px` item gaps.
-- Active underline tabs use a `2px` `#245ded` bottom border.
-- Segment selected tabs use a pill radius; rounded selected tabs use `6px`.
-- Selected segment and rounded tabs use white fill plus `0 1px 1px rgba(15, 17, 20, 0.06)`.
-- `md` segment and rounded tabs are `40px` tall inside a `44px` container.
-- `sm` segment and rounded tabs are `36px` tall inside a `40px` container.
-- `xs` segment and rounded tabs are `32px` tall inside a `36px` container.
-- `md` underline rows are `56px`; `sm` and `xs` underline rows are `48px`.
-- Full-width tabs stretch equally inside their parent width.
-- RTL uses `dir="rtl"` on the tablist so the active first item appears on the right edge.
+# Tabs
+
+Tabs switch between peer views while keeping the user in the same context.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Tabs` (`225:9832`). It supports every variant in the matrix: `underline`, `segment`, and `rounded`; `md`, `sm`, and `xs`; full-width and hug-content layouts; LTR and RTL.
+
+## API
+
+```tsx
+<Tabs
+  variant="underline"
+  size="md"
+  fullWidth={false}
+  dir="ltr"
+  items={["Tab item", "Tab item", "Tab item", "Tab item", "Tab item"]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `underline`, `segment`, `rounded` | `underline` |
+| `size` | `md`, `sm`, `xs` | `md` |
+| `fullWidth` | `boolean` | `false` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `string[]` | five `Tab item` labels |
+| `activeIndex` | `number` | uncontrolled |
+| `defaultActiveIndex` | `number` | `0` |
+| `onActiveIndexChange` | `(index: number) => void` | none |
+
+## 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 its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
+
+- Backgrounds: `--bh-bg-neutral-subtle`, `--bh-bg-default`
+- Borders: `--bh-border-default`
+- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`
+- Shape: `--bh-radius-md-6`, `--bh-radius-lg-8`, `--bh-radius-full`
+
+## Pixel Rules
+
+- Text is Inter `15px / 24px`.
+- Active labels use weight `500`; inactive labels use weight `400`.
+- Segment and rounded containers use `2px` padding and `2px` item gaps.
+- Underline containers use a `1px` default bottom border and `16px` item gaps.
+- Active underline tabs use a `2px` `#245ded` bottom border.
+- Segment selected tabs use a pill radius; rounded selected tabs use `6px`.
+- Selected segment and rounded tabs use white fill plus `0 1px 1px rgba(15, 17, 20, 0.06)`.
+- `md` segment and rounded tabs are `40px` tall inside a `44px` container.
+- `sm` segment and rounded tabs are `36px` tall inside a `40px` container.
+- `xs` segment and rounded tabs are `32px` tall inside a `36px` container.
+- `md` underline rows are `56px`; `sm` and `xs` underline rows are `48px`.
+- Full-width tabs stretch equally while every label fits. Intrinsic label width is the minimum; narrower rows scroll horizontally instead of shrinking triggers beneath their copy.
+- Hug-content tabs keep their intrinsic widths and use the same local horizontal overflow behavior under pressure.
+- RTL uses `dir="rtl"` on the tablist so the active first item appears on the right edge.