banhaten 0.3.0 → 0.5.0

package/README.md

@@ -1,190 +1,192 @@
-# Banhaten Design System
-
-Banhaten is an Arabic and English-first React design system with source-installed components, generated design tokens, and first-class RTL behavior. It uses a shadcn-style distribution model without copying shadcn visuals: components are built around Banhaten tokens, Banhaten component aliases, and Banhaten Figma-derived interaction patterns.
-
-## Quick Start
-
-Run the CLI from the root of a React app:
-
-```bash
-npx banhaten init
-npx banhaten add button input select
-```
-
-When dependencies are added, the CLI prints the install command for your package manager.
-
-```bash
-npm install
-pnpm install
-yarn install
-bun install
-```
-
-## What Init Adds
-
-`banhaten init` writes:
-
-- `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.
-
-`banhaten add` and `banhaten update` also refresh the generated token stylesheet, so installed projects receive token changes as the registry evolves.
-
-## CLI
-
-```bash
-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:
-
-- `--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. 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 --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.
-
-## Tokens
-
-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.
-- Brand theme: `blue`, `gray`, `brown`, `orange`, `green`, `purple`, `teal`.
-- 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
-<html className="dark" data-theme="brown" data-radius="rounded" dir="rtl" lang="ar">
-```
-
-Typography utilities are generated as `.bh-text-*` classes and map directly to token variables.
-
-```tsx
-<h1 className="bh-text-heading-xl-bold">...</h1>
-<p className="bh-text-body-md-regular">...</p>
-```
-
-## Registry Formats
-
-Banhaten maintains component-owned registry sources and two compiled
-publication artifacts:
-
-- `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.
-
-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, the closed 910/910 contrast contract, and deliberate non-copying decisions.
-
-Useful commands:
-
-```bash
-npm run docs:check
-npm run docs:normalize
-npm run playground:dev
-```
-
-## Components
-
-The registry includes core primitives such as Button, Input, Select, Field, Modal, Sheet, Sidebar, Menu, Tabs, Toast, Table, and Chart. It also includes Banhaten-specific and product-oriented components such as Attribute, Radio Card, Progress Slider, Social Button, Tag, Toolbar, Timeline, Banner, File Upload, Page Header, Command Bar, Slideout, Activity Feed, and Steps.
-
-Expanded components are larger app compositions. They are installed through the same CLI but documented as a separate tier because their layout contracts are broader than primitive controls.
-
-## Development
-
-```bash
-npm run check
-npm run tokens:check
-npm run registry:check
-npm run playground:test
-```
-
-The full check verifies CLI behavior, generated token CSS, token contract, raw token violations, registry mirrors, shadcn-compatible registry export, markdown docs, and playground coverage.
+# Banhaten Design System
+
+Banhaten is an Arabic and English-first React design system with source-installed components, generated design tokens, and first-class RTL behavior. It uses a shadcn-style distribution model without copying shadcn visuals: components are built around Banhaten tokens, Banhaten component aliases, and Banhaten Figma-derived interaction patterns.
+
+## Quick Start
+
+Run the CLI from the root of a React app:
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+```
+
+When dependencies are added, the CLI prints the install command for your package manager.
+
+```bash
+npm install
+pnpm install
+yarn install
+bun install
+```
+
+## What Init Adds
+
+`banhaten init` writes:
+
+- `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.
+
+`banhaten add` and `banhaten update` also refresh the generated token stylesheet, so installed projects receive token changes as the registry evolves.
+
+## CLI
+
+```bash
+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:
+
+- `--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. 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 --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.
+
+## Tokens
+
+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.
+- Brand theme: `blue`, `gray`, `brown`, `orange`, `green`, `purple`, `teal`.
+- Radius mode: `default`, `rounded`, `sharp`.
+- Direction: inherited LTR or RTL, with component-level `dir` support where needed.
+
+The default appearance is the monochrome `gray` brand theme. It keeps page,
+card, border, and muted surfaces neutral while applying gray to links, focus
+states, and primary actions as well. `blue` remains available as an alternate
+brand theme.
+
+Example:
+
+```tsx
+<html className="dark" data-theme="brown" data-radius="rounded" dir="rtl" lang="ar">
+```
+
+Typography utilities are generated as `.bh-text-*` classes and map directly to token variables.
+
+```tsx
+<h1 className="bh-text-heading-xl-bold">...</h1>
+<p className="bh-text-body-md-regular">...</p>
+```
+
+## Registry Formats
+
+Banhaten maintains component-owned registry sources and two compiled
+publication artifacts:
+
+- `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.
+
+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. The playground also includes a Templates tier with 60 searchable page, flow, and widget compositions built from current Banhaten tokens and components.
+
+Markdown docs live in `docs/design-system/components`. They are checked for install, API, examples, token contract, RTL rules, and accessibility sections.
+
+Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md). See the [template catalog contract](docs/design-system/templates.md) and the resulting [template gap audit](docs/design-system/template-gap-audit.md) for the composition layer.
+
+The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, the closed 910/910 contrast contract, and deliberate non-copying decisions.
+
+Useful commands:
+
+```bash
+npm run docs:check
+npm run docs:normalize
+npm run playground:dev
+```
+
+## Components
+
+The registry includes core primitives such as Button, Input, Select, Field, Modal, Sheet, Sidebar, Menu, Tabs, Toast, Table, and Chart. It also includes Banhaten-specific and product-oriented components such as Attribute, Radio Card, Progress Slider, Social Button, Tag, Toolbar, Timeline, Banner, File Upload, Page Header, Command Bar, Slideout, Activity Feed, and Steps.
+
+Expanded components are larger app compositions. They are installed through the same CLI but documented as a separate tier because their layout contracts are broader than primitive controls.
+
+Templates sit above those reusable components and patterns. They demonstrate realistic page, flow, and widget assemblies without claiming product behavior or generated-file ownership; candidates become installable blocks only after their APIs and state contracts stabilize.
+
+## Development
+
+```bash
+npm run check
+npm run tokens:check
+npm run registry:check
+npm run playground:test
+```
+
+The full check verifies CLI behavior, generated token CSS, token contract, raw token violations, registry mirrors, shadcn-compatible registry export, markdown docs, and playground coverage.

package/SECURITY.md

@@ -1,15 +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.
+# 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,11 +1,11 @@
-{
-  "$schema": ".banhaten/schema/config.schema.json",
-  "tailwind": {
-    "css": "app/globals.css"
-  },
-  "aliases": {
-    "ui": "@/components/ui",
-    "utils": "@/lib/utils",
-    "hooks": "@/hooks"
-  }
-}
+{
+  "$schema": ".banhaten/schema/config.schema.json",
+  "tailwind": {
+    "css": "app/globals.css"
+  },
+  "aliases": {
+    "ui": "@/components/ui",
+    "utils": "@/lib/utils",
+    "hooks": "@/hooks"
+  }
+}

package/docs/design-spacing.md

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

package/docs/design-system/README.md

@@ -1,20 +1,22 @@
-# Banhaten Design System Docs
-
-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.
-
-The playground remains the primary documentation surface because it renders live registry-backed previews, source snippets, copyable code panels, API tables, file links, and RTL behavior.
+# Banhaten Design System Docs
+
+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.
+- [Templates](./templates.md): 60 page, flow, and widget compositions built from Banhaten tokens and components.
+- [Template Gap Audit](./template-gap-audit.md): composition friction and prioritized candidates revealed by the template catalog.
+- [Launch Comparison](./launch-comparison-shadcn.md): the complete shadcn/ui benchmark, remediation register, and deliberate differences.
+- [Component Docs Pattern](./component-docs-pattern.md): the Base / Anatomy / Alternatives shape every playground component page follows.
+- [Components](./components/README.md): component markdown catalog.
+- [Icon System](./icons.md): icon guidance and explorer notes.
+
+The playground remains the primary documentation surface because it renders live registry-backed previews, source snippets, copyable code panels, API tables, file links, and RTL behavior.