banhaten 0.1.3 → 0.3.0

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

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

package/docs/design-system/installation.md

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

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

@@ -0,0 +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)

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

@@ -1,19 +1,37 @@
 # Registry And CLI
 
-Banhaten publishes two registry shapes.
+Banhaten maintains one authored registry catalog and publishes two compiled
+registry shapes.
 
 | Artifact | Purpose |
 | --- | --- |
-| `registry/index.json` | Banhaten source of truth for the Banhaten CLI. Includes rich metadata for files, examples, dependencies, parts, RTL behavior, and design-system capabilities. |
+| `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`. |
 
-Run `npm run registry:export` after editing `registry/index.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. `banhaten add` and `banhaten update` compare installed files to registry files and replace stale generated files by default. Use `banhaten diff` before updating when a project has local edits inside generated components.
+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 managed Banhaten token block while preserving CSS outside the block.
+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
 
@@ -21,14 +39,19 @@ The token stylesheet is generated-owned too. `init`, `add`, and `update` refresh
 npx banhaten init
 npx banhaten add button input select
 npx banhaten diff
-npx banhaten update button
+npx banhaten update button --force
 npx banhaten list --json
 npx banhaten search input
 npx banhaten docs button
 npx banhaten view button
+npx banhaten doctor
 ```
 
-The CLI detects `packageManager` and common lockfiles before printing dependency install hints.
+`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
 

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

@@ -0,0 +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.

package/docs/design-system/roadmap.md

@@ -0,0 +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.

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

@@ -0,0 +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.

package/docs/design-system/tabs.md

@@ -29,7 +29,7 @@ The implementation follows the Figma component at `Design system 3.0 Copy / Tabs
 
 ## 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-neutral-subtle`, `--bh-bg-default`
 - Borders: `--bh-border-default`

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

@@ -3,7 +3,8 @@
 Banhaten components must be built from Banhaten tokens. Component source may use:
 
 - Generated `--bh-*` semantic tokens.
-- Component aliases emitted by `scripts/component-token-aliases.mjs`.
+- System, typography, effect, and component variables compiled from their owned
+  fragments under `tokens/source/` into the published `cssVariables` contract.
 - shadcn alias bridge variables such as `--background`, `--foreground`, and `--ring` only when they point back to Banhaten tokens.
 - Documented exception-ledger values when the value is external, brand-owned, or required by a third-party primitive API.
 
@@ -18,6 +19,27 @@ Do not add raw component styling literals directly to `registry/components`:
 
 `npm run tokens:check` enforces the generated CSS contract and component token usage.
 
+Structured tokens and aliases are authored in the domain and component-owned
+fragments under `tokens/source/`. `tokens/banhaten.tokens.json` is output-only
+and deterministically compiled from that manifest. Authored Tailwind mappings,
+keyframes, global and accessibility rules, and typography utilities live in
+`tokens/banhaten.utilities.css`. The distributable
+`registry/styles/globals.css` is regenerated from the compiled token catalog and
+that authored CSS source.
+
+The generator emits the complete default-theme graph once, then emits only declarations whose values differ for each alternate theme. Dark mode and alternate themes inherit unchanged scoped aliases through the cascade. This keeps the live graph auditable without duplicating identical declarations.
+
+The default appearance deliberately composes two concerns: `blue` owns brand
+roles and `gray` owns the neutral ramp. As a result, default product surfaces
+are achromatic, while links, focus states, and primary actions remain blue.
+`cssContract.defaultTheme` and `cssContract.defaultNeutralTheme` record that
+composition. `npm run tokens:build` synchronizes it into the authored default
+theme and semantic color-mode values before compiling the public artifacts.
+Alternate brand themes keep their reviewed neutral ramps unless their source is
+explicitly changed.
+
+Color values are design-owned. The generated Color Contrast page reports failing combinations and recommendations, but automation must not silently change source colors. A color change requires an explicit design review and regeneration of the contrast baseline.
+
 ## Exception Ledger
 
 The following exceptions are allowed only in token generation or documented alias source, not directly in component implementation:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "banhaten",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Banhaten design system: an Arabic and English-first React design system with shadcn-style component installation.",
   "type": "module",
   "bin": {
@@ -9,8 +9,10 @@
   "files": [
     "src",
     "registry/index.json",
+    "registry/component-contract.json",
     "registry/components",
     "registry/examples",
+    "registry/guidance",
     "registry/hooks",
     "registry/styles",
     "registry/utils",
@@ -19,42 +21,50 @@
     "registry/assets/images/art-01.jpg",
     "registry.json",
     "tokens/banhaten.tokens.json",
-    "tokens/Color mode.zip",
-    "tokens/Theme.zip",
-    "tokens/Numbers.zip",
-    "tokens/Radius.zip",
     "schema",
     "docs",
     "banhaten.config.example.json",
     "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "npm --prefix playground ci --include=dev --include=optional && npm --prefix playground run build",
     "build:railway": "npm --prefix playground ci --include=dev --include=optional && npm --prefix playground run build:railway",
     "start": "node playground/scripts/serve-static.mjs playground/dist",
-    "check": "node --check src/cli/index.js && node --check scripts/generate-shadcn-registry.mjs && node --check scripts/normalize-component-docs.mjs && npm run cli:test && npm run tokens:check && npm run registry:check && npm run docs:check && npm run playground:test && npm run playground:audit",
-    "cli:test": "node scripts/cli-integration-test.mjs",
+    "check": "node --check src/cli/index.js && node --check src/cli/command-line.js && node --check src/cli/doctor.js && node --check src/cli/config-editors.js && node --check src/cli/source-scanner.js && node --check src/cli/jsonc.js && node --check src/cli/vite-config.js && node --check src/cli/install-plan.js && node --check src/cli/install-receipt.js && node --check src/cli/package-install-state.js && node --check src/cli/package-manager.js && node --check src/cli/package-plan.js && node --check src/cli/package-version.js && node --check scripts/compile-token-catalog.mjs && node --check scripts/sync-default-theme-neutral-values.mjs && node --check scripts/token-catalog-test.mjs && node --check scripts/registry-catalog.mjs && node --check scripts/generate-registry-index.mjs && node --check scripts/generate-shadcn-registry.mjs && node --check scripts/normalize-component-docs.mjs && node --check scripts/package-artifact.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/select-react-compatibility.mjs && npm run contracts:check && npm run cli:test && npm run tokens:check && npm run components:ownership:check && npm run registry:check && npm run docs:check && npm run package:check && npm run playground:build && npm run playground:test:browser && npm run playground:audit",
+    "contracts:check": "node scripts/validate-contracts.mjs",
+    "cli:test": "node scripts/cli-argument-test.mjs && node scripts/cli-dependency-test.mjs && node scripts/cli-install-plan-test.mjs && node scripts/cli-integration-test.mjs && node scripts/cli-doctor-test.mjs",
     "playground:build": "npm --prefix playground run build",
     "playground:dev": "npm --prefix playground run dev",
     "playground:test": "npm --prefix playground run test",
+    "playground:test:browser": "npm --prefix playground run test:browser",
     "playground:audit": "npm --prefix playground audit --audit-level=high",
-    "registry:check": "node scripts/check-registry-mirrors.mjs && node scripts/generate-shadcn-registry.mjs --check",
-    "registry:export": "node scripts/generate-shadcn-registry.mjs --write",
+    "package:check": "node scripts/generate-registry-index.mjs --check && node scripts/compile-token-catalog.mjs --check && node scripts/check-package-contents.mjs",
+    "registry:build": "node scripts/generate-registry-index.mjs --write",
+    "registry:check": "node scripts/generate-registry-index.mjs --check && node scripts/check-registry-mirrors.mjs && node scripts/generate-shadcn-registry.mjs --check && node scripts/registry-runtime-exports-test.mjs && node scripts/check-isolated-registry-installs.mjs --packed",
+    "registry:export": "node scripts/generate-registry-index.mjs --write && node scripts/generate-shadcn-registry.mjs --write",
+    "registry:exports": "node scripts/check-isolated-registry-installs.mjs --write-exports",
     "registry:sync": "node scripts/check-registry-mirrors.mjs --write",
     "components:tokens:check": "node scripts/check-component-token-usage.mjs",
+    "components:ownership:check": "npm --prefix playground run test:ownership",
+    "components:tokens:metadata": "node scripts/sync-component-token-metadata.mjs",
     "docs:check": "node scripts/check-component-docs.mjs && node scripts/normalize-component-docs.mjs",
     "docs:normalize": "node scripts/normalize-component-docs.mjs --write",
     "smoke": "node src/cli/index.js list",
-    "tokens:build": "node scripts/generate-token-css.mjs --write",
-    "tokens:check": "node scripts/generate-token-css.mjs --check && node scripts/check-token-contract.mjs && npm run components:tokens:check"
+    "tokens:aliases:check": "node scripts/sync-default-theme-neutral-values.mjs",
+    "tokens:aliases:sync": "node scripts/sync-default-theme-neutral-values.mjs --write",
+    "tokens:build": "npm run tokens:aliases:sync && node scripts/compile-token-catalog.mjs --write && node scripts/generate-token-css.mjs --write",
+    "tokens:check": "npm run tokens:aliases:check && node scripts/compile-token-catalog.mjs --check && node scripts/token-catalog-test.mjs && node scripts/generate-token-css.mjs --check && node scripts/check-token-css-reproducibility.mjs && node scripts/check-token-contract.mjs && npm run components:tokens:check && npm run components:tokens:metadata"
   },
   "engines": {
     "node": ">=18.18"
   },
   "peerDependencies": {
-    "react": ">=18.2.0 || >=19.0.0",
-    "react-dom": ">=18.2.0 || >=19.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
     "tailwindcss": "^4.0.0"
   },
   "keywords": [
@@ -78,6 +88,11 @@
   "directories": {
     "doc": "docs"
   },
-  "devDependencies": {},
-  "author": "Ahmad Galal"
+  "author": "Ahmad Galal",
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "minimatch": "^10.2.5",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0"
+  }
 }

package/registry/component-contract.json

@@ -0,0 +1,40 @@
+{
+  "capabilities": {
+    "actions": "Actions",
+    "alignments": "Alignments",
+    "breakpoints": "Breakpoints",
+    "cardPositions": "Card Positions",
+    "colors": "Colors",
+    "controlPositions": "Control Positions",
+    "densities": "Densities",
+    "directions": "Directions",
+    "features": "Features",
+    "forms": "Forms",
+    "indicators": "Indicators",
+    "intents": "Intents",
+    "itemKinds": "Item Kinds",
+    "itemTypes": "Item Types",
+    "kinds": "Kinds",
+    "labelPositions": "Label Positions",
+    "layouts": "Layouts",
+    "modes": "Modes",
+    "offsets": "Offsets",
+    "options": "Options",
+    "orientations": "Orientations",
+    "platforms": "Platforms",
+    "pointerPositions": "Pointer Positions",
+    "selectionTypes": "Selection Types",
+    "shapes": "Shapes",
+    "sides": "Sides",
+    "sizes": "Sizes",
+    "states": "States",
+    "statusColors": "Status Colors",
+    "styles": "Styles",
+    "tokens": "Tokens",
+    "tones": "Tones",
+    "types": "Types",
+    "valueModes": "Value Modes",
+    "variants": "Variants",
+    "widths": "Widths"
+  }
+}

package/registry/components/alert-dialog.tsx

@@ -16,7 +16,7 @@ const alertDialogContentVariants = cva(
     "fixed left-1/2 top-1/2 z-[var(--bh-z-overlay)] flex max-h-[calc(100vh-(var(--bh-space-8xl-48)*2))] w-[var(--bh-alert-dialog-width)]",
     "max-w-[calc(100vw-(var(--bh-space-4xl-20)*2))] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden",
     "rounded-[var(--bh-radius-2xl-12)] bg-[var(--bh-bg-raised)] text-[var(--bh-content-default)] shadow-[var(--shadow-modal)] outline-none",
-    "[--bh-alert-dialog-border:var(--bh-border-subtle)] [--shadow-modal:inset_0px_0px_0px_var(--bh-border-width-default)_var(--bh-alert-dialog-border),var(--shadow-component-default)]",
+    "[--bh-alert-dialog-border:var(--bh-border-subtle)] [--shadow-modal:inset_0px_0px_0px_var(--bh-border-width-default)_var(--bh-alert-dialog-border),var(--shadow-lg)]",
   ],
   {
     variants: {
@@ -223,7 +223,7 @@ function AlertDialogIcon({
       {children ?? (
         <TriangleAlertIcon
           className="size-[var(--bh-space-3xl-16)]"
-          strokeWidth={2}
+          strokeWidth="var(--bh-icon-stroke-200)"
         />
       )}
     </span>