banhaten 0.1.2 → 0.2.0

package/CHANGELOG.md

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

package/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Banhaten
+
+## Local checks
+
+Use Node 18.18 or newer, install the root and playground dependencies, then run:
+
+```bash
+npm run check
+```
+
+The full check validates schemas, CLI behavior, token generation, token-only component styling, registry mirrors, isolated installs, documentation coverage, browser tests, and the production bundle.
+
+## Component rules
+
+- Build component styling from canonical `--bh-*` and `--shadow-*` tokens. Add
+  new values to the appropriate owned fragment under `tokens/source/` before
+  using them in component source.
+- Keep product copy, sample dates, and product actions in examples rather than production defaults.
+- Preserve inherited direction and use logical CSS properties. Test both LTR and RTL keyboard behavior.
+- Use native semantics or proven accessible primitives, and document the public API, examples, tokens, RTL behavior, and accessibility contract.
+- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab.
+
+## Generated artifacts
+
+Edit the owned fragments under `tokens/source/` for structured tokens and
+aliases, and edit `registry/catalog/components/<id>.json` for component registry
+metadata. `tokens/banhaten.tokens.json` and `registry/index.json` are compiled
+publication artifacts. Edit `tokens/banhaten.utilities.css` for authored
+Tailwind mappings, keyframes, global rules, accessibility rules, and typography
+utilities. The generated `registry/styles/globals.css` is rebuilt from the
+compiled token catalog and that authored CSS source.
+
+After token or registry metadata changes, run:
+
+```bash
+npm run tokens:build
+npm run components:tokens:metadata -- --write
+npm run registry:export
+npm run docs:normalize
+```
+
+Do not hand-edit `tokens/banhaten.tokens.json`, `registry/index.json`,
+`registry/styles/globals.css`, `registry.json`, or generated registry contract
+tables.

package/README.md

@@ -1,373 +1,190 @@
-# Banhaten design system
+# Banhaten Design System
 
-Banhaten design system is an Arabic and English-first React design system. It installs source components into a project, shadcn-style:
+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.
 
-```text
+## Quick Start
+
+Run the CLI from the root of a React app:
+
+```bash
 npx banhaten init
-npx banhaten add button
-npx banhaten add button-group
-npx banhaten add menu
-npx banhaten add modal
-npx banhaten add checkbox
-npx banhaten add radio-card
-npx banhaten add divider
-npx banhaten add pagination
-npx banhaten add toolbar
-npx banhaten add social-button
-npx banhaten add input
-npx banhaten add select
-npx banhaten add autocomplete
-npx banhaten add date-picker
-npx banhaten add slider
-npx banhaten add skeleton
-npx banhaten add progress
-npx banhaten add progress-slider
-npx banhaten add textarea
-npx banhaten add toggle
-npx banhaten add attribute
-npx banhaten add card
-npx banhaten add accordion
-npx banhaten add avatar
-npx banhaten add badge
-npx banhaten add tag
-npx banhaten add tooltip
+npx banhaten add button input select
 ```
 
-The current scaffold includes:
-
-- A publishable `banhaten` CLI.
-- Design-token CSS with light, dark, LTR, and RTL foundations.
-- A complete Figma-matched `button` registry item using React, Radix Slot, CVA variants, reusable shadow tokens, icon placement attributes, and RTL directional-icon flipping.
-- A Figma-matched `button-group` registry item with connected md/sm/xs rows, default and icon-only modes, dividers, reusable group shadow, RTL widths, native hover/focus/pressed styling, and active/disabled states.
-- A Radix DropdownMenu-backed, Figma-matched `menu` registry item with the raised menu surface, default, multiline, call-to-action, progress, button, label, caption, and divider item compositions, plus badges, switches, avatars, actions, meta text, and RTL-safe slots.
-- A Radix Dialog-backed, Figma-matched `modal` registry item with Small, Default, and Large sizes, tokenized raised surface, header/body/footer slots, ConfirmModal guardrails, Button actions, Checkbox opt-out, and RTL layout.
-- A Figma-matched `checkbox` registry item with Radix checkbox behavior, a 20px root, 16px visual control, selected and disabled states, checkbox cards, component shadow, and RTL layout.
-- A Figma-matched `radio-card` registry item with icon, payment, avatar, company, support-label, and label-only layouts across LTR/RTL with native hover styling plus active and disabled states.
-- A Figma-matched `divider` registry item with horizontal and vertical directions, solid and dotted types, 1px stroke, 2px dash rhythm, and Color mode divider tokens.
-- A Figma-matched `pagination` registry item with numeric, simple, and summary layouts, soft and ghost styles, exact 32px controls, captions, and RTL labels.
-- A Figma-matched `toolbar` registry item with search, select triggers, filter actions, chips, selected-count badges, desktop/mobile wrapping, and RTL-safe composition.
-- A Figma-matched `social-button` registry item for Apple, Facebook, Google, LinkedIn, Twitter (new), and WhatsApp sign-in buttons with solid, outlined, icon-only, native focus-visible, and RTL states.
-- A token-built `attribute` registry item for semantic key-value rows, detail cards, alignment variants, copyable values, loading rows, and RTL layouts.
-- A token-built `card` registry item with vertical, horizontal, full-image, mobile, footer action, and RTL surface use cases.
-- An `avatar` registry item with image, fallback, badge, group, group count, size scale, and RTL-safe overlap.
-- An `accordion` registry item with Radix disclosure behavior, variants, sizes, animation, and RTL-safe text alignment.
-- A Figma-matched `badge` registry item with light, outline, and solid styles, semantic accent colors, dot, flag, icon, numeric, and RTL-safe composition.
-- A Figma-matched `tag` registry item with simple, dot, flag, avatar, and icon types, default/active/disabled states, native hover/focus-visible styling, xs/md/lg sizes, optional close button, and RTL-safe composition.
-- A Radix Switch-backed `toggle` registry item with sm/md geometry, active/disabled states, optional handle icons, labeled fields, supporting text, and RTL-safe label placement.
-- A Figma-matched `textarea` registry item with label, helper text, error, default and tags modes, placeholder, filled, disabled, and RTL states.
-- A Radix Select-backed, Figma-matched `select` registry item with default and soft triggers, error/filled/disabled states, menu surface, checkbox and check selection, and item media for text, icons, users, companies, payment methods, and status dots.
-- A composed `autocomplete` registry item with Input field anatomy, Select menu rows, Tag selections, filtering, keyboard navigation, controlled state, and RTL layout.
-- A Figma-matched `date-picker` registry item with Calendar, Range Calendar, Date Picker, Date Range Picker, presets, time rows, open states, month/year view, and RTL.
-- A Radix Slider-backed `slider` registry item with single, range, multi-thumb, text/tooltip indicators, ticks, vertical layout, pill treatment, tones, and RTL behavior.
-- A token-built `skeleton` registry item with primitive, text, avatar, button, input, card, list, table, form, shimmer, reduced-motion, and RTL loading compositions.
-- A read-only `progress` registry item with value meters, label placements, helper text, indicators, spinner, and RTL fill direction.
-- A Radix-based `progress-slider` registry item with semantic tones, ticks, focus treatment, and RTL-aware keyboard behavior.
-- A `spinner` registry item with steady `Spinner`, variable-arc `DynamicSpinner`, inherited text color, and CSS variable sizing.
-- A Radix Tooltip-backed `tooltip` registry item with dark/default variants, small/large sizes, pointer positions, shortcut and close slots, and RTL-safe layout.
-- Token CSS generated from the local token exports in `tokens`, with the Banhaten alias layer kept in the same generated stylesheet.
-- Inter as the single font family, loaded through `@fontsource/inter` weights 400, 500, 600, and 700.
-- Figma-sourced typography tokens for all 43 local text styles across Display, Heading, and Body.
-
-## Local Usage
-
-From this repository:
-
-```text
-node src/cli/index.js init --cwd ./playground
-node src/cli/index.js add button --cwd ./playground
-node src/cli/index.js add button-group --cwd ./playground
-node src/cli/index.js add menu --cwd ./playground
-node src/cli/index.js add modal --cwd ./playground
-node src/cli/index.js add checkbox --cwd ./playground
-node src/cli/index.js add radio-card --cwd ./playground
-node src/cli/index.js add divider --cwd ./playground
-node src/cli/index.js add pagination --cwd ./playground
-node src/cli/index.js add toolbar --cwd ./playground
-node src/cli/index.js add social-button --cwd ./playground
-node src/cli/index.js add input --cwd ./playground
-node src/cli/index.js add select --cwd ./playground
-node src/cli/index.js add autocomplete --cwd ./playground
-node src/cli/index.js add date-picker --cwd ./playground
-node src/cli/index.js add slider --cwd ./playground
-node src/cli/index.js add skeleton --cwd ./playground
-node src/cli/index.js add spinner --cwd ./playground
-node src/cli/index.js add progress --cwd ./playground
-node src/cli/index.js add progress-slider --cwd ./playground
-node src/cli/index.js add textarea --cwd ./playground
-node src/cli/index.js add toggle --cwd ./playground
-node src/cli/index.js add attribute --cwd ./playground
-node src/cli/index.js add card --cwd ./playground
-node src/cli/index.js add accordion --cwd ./playground
-node src/cli/index.js add avatar --cwd ./playground
-node src/cli/index.js add badge --cwd ./playground
-node src/cli/index.js add tag --cwd ./playground
-node src/cli/index.js add tooltip --cwd ./playground
+When dependencies are added, the CLI prints the install command for your package manager.
+
+```bash
+npm install
+pnpm install
+yarn install
+bun install
 ```
 
-Run the local component playground:
+## What Init Adds
 
-```text
-npm --prefix playground install
-npm run playground:dev
-```
+`banhaten init` writes:
 
-In a published package:
+- `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.
 
-```text
-npx banhaten init
-npx banhaten add button
-npx banhaten add button-group
-npx banhaten add menu
-npx banhaten add modal
-npx banhaten add checkbox
-npx banhaten add radio-card
-npx banhaten add divider
-npx banhaten add pagination
-npx banhaten add toolbar
-npx banhaten add social-button
-npx banhaten add input
-npx banhaten add select
-npx banhaten add autocomplete
-npx banhaten add date-picker
-npx banhaten add slider
-npx banhaten add skeleton
-npx banhaten add spinner
-npx banhaten add progress
-npx banhaten add progress-slider
-npx banhaten add textarea
-npx banhaten add toggle
-npx banhaten add attribute
-npx banhaten add card
-npx banhaten add accordion
-npx banhaten add avatar
-npx banhaten add badge
-npx banhaten add tag
-npx banhaten add tooltip
-```
+`banhaten add` and `banhaten update` also refresh the generated token stylesheet, so installed projects receive token changes as the registry evolves.
 
-After `init` or `add`, run your package manager install command when the CLI reports new dependencies:
+## CLI
 
-```text
-npm install
+```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
 ```
 
-## Getting Started
+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.
 
-Use the CLI from the root of a React app:
+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.
 
-```text
-npx banhaten init
-npx banhaten add button input select
-npm install
-```
+Command flags:
 
-The CLI writes source files into your project, updates `package.json`, injects the Banhaten token block into your configured CSS file, and keeps existing generated files current when the registry version changes.
+- `--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.
 
-## Tailwind And Aliases
+Global flags:
 
-Banhaten targets Tailwind CSS v4. `banhaten init` makes sure your configured CSS file includes Tailwind, then appends the Banhaten token block:
+- `--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.
 
-```css
-@import "tailwindcss";
-```
+## 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:
 
-For Vite projects, the CLI also adds the `@tailwindcss/vite` plugin and configures `@/*` to resolve to your source folder.
-
-If your app does not use the default `@/components`, `@/lib/utils`, or `@/hooks` aliases, create `banhaten.config.json` before running `add`:
-
-```json
-{
-  "tailwind": {
-    "css": "src/app/globals.css"
-  },
-  "aliases": {
-    "ui": "@/components/ui",
-    "utils": "@/lib/utils",
-    "hooks": "@/hooks"
-  }
-}
+```bash
+npx banhaten diff
+npx banhaten update button --force # only after reviewing intentional replacement
 ```
 
-For non-Vite bundlers, make sure your TypeScript and bundler config resolve `@/*` to your source folder.
+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.
 
-## Typography Utilities
+## Tokens
 
-The token CSS ships `.bh-text-*` classes for every Banhaten typography token:
+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.
 
-```tsx
-<h1 className="bh-text-heading-xl-bold">...</h1>
-<p className="bh-text-body-md-regular">...</p>
-<button className="bh-text-button">...</button>
-```
+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.
 
-These classes map directly to the matching font family, font size, weight, letter spacing, and line height CSS variables.
+Token modes:
 
-## Theming
+- 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.
 
-Banhaten themes are controlled by attributes on the document element:
+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">
 ```
 
-- Color mode: add or remove the `dark` class.
-- Brand theme: set `data-theme` to `blue`, `gray`, `brown`, `orange`, `green`, `purple`, or `teal`.
-- Radius mode: set `data-radius` to `default`, `rounded`, or `sharp`.
-- Direction: set `dir` to `ltr` or `rtl`; components prefer explicit `dir` props for nested direction changes.
-
-## Component API Quick Reference
-
-| Component | Primary props |
-| --- | --- |
-| `Button` | `variant`, `size`, `asChild`, `loading`, `data-icon`, `data-rtl-flip` |
-| `ButtonGroup` | `size`, `mode`, `dir`; `ButtonGroupItem` supports `active`, `disabled`, `aria-label` |
-| `Attribute` | `layout`, `density`, `dividers`, `bordered`, `labelWidth`, rich value slots |
-| `Card` | `orientation`, `type`, `breakpoint`, `dir`, `title`, `description`, footer/media slots |
-| `Input` | `kind`, `size`, `variant`, `state`, `dir`, `label`, `message`, `hasHelperText` |
-| `Select` | `size`, `variant`, `state`, `open`, `dir`, `value`, `label`, `SelectMenuItem` |
-| `DatePicker` | `Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `view`, `type`, `dir` |
-| `Menu` | `width`; `MenuItem` supports `kind`, `disabled`, slotted icons, badges, actions, and progress |
-| `Modal` | `size`, `dir`, `title`, `description`, `showIcon`, `showCloseButton`, `showDivider`, `showFooter`, `showCheckbox`, `footer`; `ConfirmModal` adds `intent`, `confirmLabel`, `confirmLoading`, `preventOutsideDismiss` |
-| `Pagination` | `type`, `variant`, `dir`, `page`, `totalPages`, `labels` |
-| `Progress` | `value`, `min`, `max`, `size`, `labelPosition`, `helperText`, `showIndicator`, `showSpinner` |
-| `Spinner` | `Spinner`, `DynamicSpinner`, inherited text color, `--bh-spinner-size` CSS variable |
-| `Slider` | `value`, `defaultValue`, `tone`, `size`, `variant`, `orientation`, `showTicks` |
-| `ProgressSlider` | `value`, `defaultValue`, `tone`, `size`, `showTicks`, `ariaValueText` |
-| `Toggle` | `size`, `showIcon`, `disabled`; `ToggleField` supports `controlPosition`, `label`, `description` |
-| `Toolbar` | `layout`, `wrap`; slots include `ToolbarSearch`, `ToolbarSelect`, `ToolbarButton`, `ToolbarBadge` |
-| `Tooltip` | `variant`, `size`, `pointerPosition`, `showPointer`, `supportText`, shortcut/close slots |
-| `Checkbox` | Radix checkbox props, plus `CheckboxCard` for labeled card layouts |
-| `Badge` / `Tag` | `color`, `type`, `size`, `dir`; `Tag` also supports `showCloseButton` |
-
-## Updating Installed Components
-
-Check for local drift without writing files:
-
-```text
-npx banhaten diff
-npx banhaten diff button
+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>
 ```
 
-Refresh all detected installed components, or target a specific component:
+## Registry Formats
 
-```text
-npx banhaten update
-npx banhaten update button
+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
 ```
 
-`diff` is a dry-run update check and reports which files would be written, updated, or kept. `update` shares the same refresh path as `add`, so re-running `add button` still works for one-off updates. Use `--force` when you intentionally want to replace every generated file, including unchanged config files.
-
-## Component Phases
-
-Phase 1 focuses on the foundation and Button:
-
-- Button variants: `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white`.
-- Backward-compatible aliases: `destructive`, `soft-destructive`, and `link`.
-- Button sizes: `xs` 32px, `sm` 36px, `default` 40px, `lg` 48px, plus icon-only equivalents.
-- Button typography: Figma text style `Body/body-md (base)/medium` using Inter Medium, 15px font size, 24px line height, and 0px letter spacing.
-- Base typography: Figma text style `Body/body-md (base)/regular` using Inter Regular, 15px font size, 24px line height, and 0px letter spacing.
-- Button shadows: `--shadow-button-raised`, `--shadow-button-surface`, `--shadow-button-secondary`, `--shadow-button-secondary-focus`, `--shadow-button-soft`, `--shadow-button-focus`, and `--shadow-button-danger-focus`.
-- Icon placement: add `data-icon="inline-start"` or `data-icon="inline-end"` to icons.
-- RTL directional icons: add `data-rtl-flip="true"` to arrows and chevrons that should mirror.
-- Loading composition: use the generated `Spinner` inside `Button` instead of an `isLoading` prop.
-
-Current social primitives:
-
-- Button Group modes: `default` and `iconOnly`.
-- Button Group sizes: `md` 40px, `sm` 36px, and `xs` 32px.
-- Button Group default item widths: `md` 128px, `sm` 120px, and `xs` 112px in LTR; `md` 124px, `sm` 116px, and `xs` 108px in RTL. Icon-only groups stay square at `40px`, `36px`, and `32px`.
-- Button Group states: default and disabled are transparent; hover uses `--bh-interactive-ghost-hover`; pressed and active use the stronger ghost fill; active upgrades content to `--bh-content-default`.
-- Button Group typography: Figma text style `Body/body-md (base)/medium` using Inter Medium, 15px font size, 24px line height, and 0px letter spacing.
-- Button Group shadows: `--shadow-button-group`, `--shadow-button-group-focus-ring`, and `--shadow-button-group-focus`.
-- Button Group dividers: 1px logical separators using `--bh-button-group-divider`, with the outer 1px border using `--bh-button-group-border`.
-
-- Menu width: 228px for the raised surface, with 355px default-item, 402px multiline-item, and 240px call-to-action item variants matching the Figma component set.
-- Menu item types: `default`, `multiline`, `action`, `progress`, `button`, plus `MenuLabel`, `MenuCaption`, and `MenuSeparator` for non-interactive rows.
-- Menu behavior: `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuItem`, `MenuLabel`, and `MenuSeparator` are backed by Radix DropdownMenu primitives for roving focus, Escape, click-outside dismissal, and screen-reader roles.
-- Menu slots: leading and trailing icons, avatar, text, description, meta text, badge, switch, outline action, progress bar, and RTL-flipping directional icons.
-- Menu tokens: all colors, typography, radius, spacing, border, and elevation resolve through the Banhaten CSS variables, including `--shadow-menu`.
-
-- Social Button platforms: `apple`, `facebook`, `google`, `linkedin`, `twitter`, `whatsapp`.
-- Social Button variants: `solid` and `outline`.
-- Social Button sizes: `default` 36px height and `icon` 36px square.
-- Social Button typography: Figma text style `Body/body-md (base)/medium` using Inter Medium, 15px font size, 24px line height, and 0px letter spacing.
-- Social Button shadows: `--shadow-social-button`, `--shadow-social-button-focus-ring`, and `--shadow-social-button-focus`.
-- Social Button focus: Figma 4px outside blue ring at 30% opacity, combined with the social button surface shadow.
-- Social Button RTL: Arabic platform labels are included and can be passed through the `label` prop for nested RTL surfaces.
-
-- Pagination types: `numeric`, `simple`, and `summary`.
-- Pagination styles: `soft` and `ghost`.
-- Pagination dimensions: numeric rows use 560px, simple and summary rows use 458px, controls are 32px, and icons are 20px.
-- Pagination typography: Figma text style `Body/body-md (base)` using Inter 15px, 24px line height, and 0px letter spacing.
-- Pagination shadows: `--shadow-pagination-control`, `--shadow-pagination-active`, and `--shadow-pagination-focus`.
-- Pagination RTL: pass `dir="rtl"` or set the document direction to render Arabic labels and mirrored directional arrows.
-
-Phase 2 expands the registry into the rest of the system: form controls, overlays, navigation, feedback, data display, layout primitives, and typography.
-
-Current layout primitives:
-
-- Accordion variants: `default`, `bordered`, `cards`, `soft`.
-- Accordion sizes: `sm`, `default`, `lg`.
-- Accordion modes: Radix `type="single"` and `type="multiple"` are supported.
-- Divider directions: `horizontal` and `vertical`.
-- Divider types: `solid` and `dotted`.
-- Divider color: `--bh-border-subtle`, resolving from the Figma `Color mode / border/subtle` variable.
-- Divider geometry: 1px stroke via `--bh-space-xxxs-1`, 2px dash/gap via `--bh-space-xxs-2`, and 224px Figma component length via `--bh-space-15xl-224`.
-
-Current data-display primitives:
-
-- Badge styles: `light`, `outline`, `solid`.
-- Badge colors: `neutral`, `blue`, `green`, `amber`, `danger`, `purple`, `fuchsia`, `rose`, `sky`, `golden`.
-- Badge types: `default`, `leading-icon`, `trailing-icon`, `dot`, `flag`, plus `showNumber` for numeric badges.
-- Badge sizes: `sm` 24px and `lg` 28px. `xs` and `default` remain accepted as compatibility aliases.
-- Badge icons: set `type="leading-icon"` or `type="trailing-icon"` and add `data-icon="inline-start"` or `data-icon="inline-end"` to icons and spinners.
-- Badge compatibility: the previous `variant` values are still accepted and mapped onto the new Figma axes.
-- Tag types: `simple`, `dot`, `flag`, `avatar`, and `icon`, with optional `showCloseButton`.
-- Tag states: `default`, `active`, and `disabled`, with native hover and focus-visible styling resolving through Banhaten tokens.
-- Tag sizes: `xs` 24px, `md` 28px, and `lg` 36px using `Body/body-xs`, `Body/body-sm`, and `Body/body-md (base)` medium text styles.
-- Tag RTL: pass `dir="rtl"` or inherit document direction; logical padding mirrors leading media, label, and close-button placement.
-- Attribute layouts: `inline`, `end`, `stacked`, and `two-column` with compact/default/comfortable densities.
-- Card layouts: vertical, horizontal, full-image, and mobile spacing variants with Button-composed actions.
-
-Current form primitives:
-
-- Checkbox primitive: 20px interactive root, 16px centered control, 12px `check-fill` icon, 4px radius, `Shadow/component/default`, and Color mode checkbox tokens.
-- Checkbox Card: 338px Figma width, 16px padding, 16px card gap, 12px content gap, selected 2px brand border, hover raised background, disabled background/border/content tokens, and RTL-safe start/end control placement.
-- Radio Card: 338px Figma width, 16px padding, 10px card gap, 10px radius, 20px radio wrapper, 16px radio control, selected 6px dot, raised/card and control shadows, and design-system color and typography tokens.
-- Toggle sizes: `sm` and `md`, with optional handle icons and `ToggleField` leading/trailing label compositions.
-- Date Picker modes: single calendar, month/year view, double range calendar, preset list, date picker, and date range picker.
-- Slider modes: single value, range, multi-thumb, ticked, vertical, pill, text indicator, tooltip indicator, and RTL.
-- Textarea modes: `default` and `tags`.
-- Textarea states: `placeholder`, `filled`, and `disabled`; `hasError` switches the border and helper text to the danger tokens.
-- Textarea typography: labels use `Body/body-sm/medium`, body text uses `Body/body-md (base)/regular`, and helper/tag text uses `Body/body-xs`.
-- Textarea dimensions: 320px default width, 80px minimum input surface, 10px surface padding, 8px field gap, and 8px radius from the Figma component set.
-- Textarea RTL: pass `dir="rtl"` or inherit document direction so label, helper, and tag-chip ordering mirrors without physical left/right styling.
-
-## Token Source
-
-The current source of truth is the local token exports:
-
-- `tokens/Color mode.zip`
-- `tokens/Theme.zip`
-- `tokens/Numbers.zip`
-- `tokens/Radius.zip`
-
-`registry/styles/globals.css` maps those exports into Banhaten semantic CSS variables, including light/dark color mode, Blue/Gray/Brown/Orange/Green/Purple/Teal brand themes, and Default/Rounded/Sharp radius modes.
-
-Run `npm run tokens:build` after updating `tokens/banhaten.tokens.json`; it regenerates the JSON-backed token declarations while preserving local component aliases and utilities. Run `npm run tokens:check` before committing token changes. The check verifies generated CSS drift, token source files, theme/radius selectors, shadcn aliases, generated `--bh-*` variables, and retired typo tokens.
-
-## Direction
-
-Banhaten assumes UI can run in either direction:
+`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.
 
-```tsx
-<html lang="ar" dir="rtl">
+## Documentation
+
+Primary docs live in the playground and render live registry-backed previews, install commands, source snippets, API tables, registry files, RTL behavior, and copyable code panels.
+
+Markdown docs live in `docs/design-system/components`. They are checked for install, API, examples, token contract, RTL rules, and accessibility sections.
+
+Launch guides cover [installation](docs/design-system/installation.md), [direction and localization](docs/design-system/direction-and-localization.md), [form recipes](docs/design-system/form-recipes.md), [density and elevation](docs/design-system/density-and-elevation.md), the [support matrix](docs/design-system/support-matrix.md), and the [release policy](docs/design-system/release-policy.md).
+
+The durable [launch comparison with shadcn/ui](docs/design-system/launch-comparison-shadcn.md) records every audited area, remediation, verification gate, contrast exception, and deliberate non-copying decision.
+
+Useful commands:
+
+```bash
+npm run docs:check
+npm run docs:normalize
+npm run playground:dev
 ```
 
-or:
+## Components
 
-```tsx
-<html lang="en" dir="ltr">
+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
 ```
 
-Components should avoid physical left/right styling unless there is a deliberate visual reason.
+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

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

package/banhaten.config.example.json

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