banhaten 0.1.1 → 0.1.3

package/README.md

@@ -1,361 +1,138 @@
-# 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.
+
+## 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 date-picker
-npx banhaten add slider
-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 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 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 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:
+When dependencies are added, the CLI prints the install command for your package manager.
 
 ```bash
-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 date-picker --cwd ./playground
-node src/cli/index.js add slider --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
+npm install
+pnpm install
+yarn install
+bun install
 ```
 
-Run the local component playground:
+## What Init Adds
 
-```bash
-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.
+- The generated Banhaten token stylesheet in your configured CSS file.
+- Tailwind v4 and Vite alias setup when those files are detected.
+- Required package dependencies.
 
-```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 date-picker
-npx banhaten add slider
-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
 
 ```bash
-npm install
+npx banhaten init [--cwd <path>] [--force] [--dry-run]
+npx banhaten add <component...> [--cwd <path>] [--force] [--dry-run]
+npx banhaten diff [component...] [--cwd <path>] [--force]
+npx banhaten update [component...] [--cwd <path>] [--force] [--dry-run]
+npx banhaten list [--json]
+npx banhaten search <query> [--json]
+npx banhaten docs <component> [--json]
+npx banhaten view <component> [--file <registry-source>] [--json]
+npx banhaten version
 ```
 
-## Getting Started
+Global flags:
+
+- `--cwd <path>` runs against another project directory.
+- `--dry-run` previews writes.
+- `--force` rewrites generated files even when already current.
+- `--json` prints machine-readable output where supported.
+- `--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
 
-Use the CLI from the root of a React app:
+Banhaten is a source registry. Installed component files are generated from the registry and are replaceable by `banhaten add` or `banhaten update` when registry content differs.
+
+Use `banhaten diff` before updating if you edit generated component files locally:
 
 ```bash
-npx banhaten init
-npx banhaten add button input select
-npm install
+npx banhaten diff
+npx banhaten update button
 ```
 
-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.
+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.
 
-## Tailwind And Aliases
+## Tokens
 
-Banhaten targets Tailwind CSS v4. `banhaten init` makes sure your configured CSS file includes Tailwind, then appends the Banhaten token block:
+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.
 
-```css
-@import "tailwindcss";
-```
+Token modes:
 
-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"
-  }
-}
-```
+- 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.
 
-For non-Vite bundlers, make sure your TypeScript and bundler config resolve `@/*` to your source folder.
+Example:
 
-## Typography Utilities
+```tsx
+<html className="dark" data-theme="brown" data-radius="rounded" dir="rtl" lang="ar">
+```
 
-The token CSS ships `.bh-text-*` classes for every Banhaten typography token:
+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>
-<button className="bh-text-button">...</button>
 ```
 
-These classes map directly to the matching font family, font size, weight, letter spacing, and line height CSS variables.
-
-## Theming
+## Registry Formats
 
-Banhaten themes are controlled by attributes on the document element:
+Banhaten maintains two registry artifacts:
 
-```tsx
-<html className="dark" data-theme="brown" data-radius="rounded" dir="rtl" lang="ar">
-```
+- `registry/index.json` is the Banhaten source of truth used by the Banhaten CLI. It includes rich metadata for RTL behavior, parts, examples, files, and dependencies.
+- `registry.json` is a generated shadcn-compatible export for tools that expect the public shadcn registry schema.
 
-- 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` |
-| `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:
+Regenerate the shadcn-compatible export after registry changes:
 
 ```bash
-npx banhaten diff
-npx banhaten diff button
+npm run registry:export
 ```
 
-Refresh all detected installed components, or target a specific component:
+## 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.
+
+Useful commands:
 
 ```bash
-npx banhaten update
-npx banhaten update button
+npm run docs:check
+npm run docs:normalize
+npm run playground:dev
 ```
 
-`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:
+## Components
 
-```tsx
-<html lang="ar" dir="rtl">
-```
+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.
 
-or:
+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.
 
-```tsx
-<html lang="en" dir="ltr">
+## 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/banhaten.config.example.json

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

package/docs/design-system/README.md

@@ -0,0 +1,11 @@
+# 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.
+- [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.
+- [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.

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

@@ -0,0 +1,184 @@
+# Appearance Presets
+
+Appearance presets change the feel of the design system without changing component APIs.
+
+Components keep semantic variants such as `primary`, `secondary`, `subtle`, `danger`, and `ghost`. Presets decide how those meanings look through design tokens: color, radius, density, border, and elevation.
+
+## Presets
+
+- `default`: The baseline product UI. Gray application background, white cards, modest radius, conservative spacing.
+- `rounded`: A softer UI. White application background, stronger radius, relaxed spacing, gentler separation.
+- `sharp`: A precise UI. Square edges, tighter spacing, clearer borders, minimal elevation.
+
+Each preset has its own markdown file:
+
+- [Default](./appearances/default.md)
+- [Rounded](./appearances/rounded.md)
+- [Sharp](./appearances/sharp.md)
+
+Component specs:
+
+- [Icons](./icons.md)
+- [Tabs](./tabs.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+Component guidance lives in:
+
+- [Components](./components/README.md)
+- [Banner](./components/banner.md)
+- [Breadcrumbs](./components/breadcrumbs.md)
+- [Divider](./components/divider.md)
+- [File Upload](./components/file-upload.md)
+- [Tag](./components/tag.md)
+- [Timeline](./components/timeline.md)
+
+## Token Contract
+
+The design system should use semantic tokens instead of importing naming patterns from a framework. Tokens describe where they are used, not how they happen to look in one theme.
+
+### Content
+
+`content` tokens apply to text and icons.
+
+- `content.default`
+- `content.primary`
+- `content.subtle`
+- `content.muted`
+- `content.disabled`
+- `content.inverse`
+- `content.link`
+- `content.linkHover`
+- `content.onColor`
+- `content.onLight`
+- `content.onBrand`
+- `content.success`
+- `content.warning`
+- `content.danger`
+
+### Background
+
+`background` tokens apply to page, layout, component, and interactive fills.
+
+- `background.app`
+- `background.default`
+- `background.card`
+- `background.subtle`
+- `background.muted`
+- `background.disabled`
+- `background.inverse`
+- `background.overlay`
+- `background.brand`
+- `background.brandHover`
+- `background.brandPressed`
+- `background.selected`
+- `background.hover`
+- `background.pressed`
+- `background.success`
+- `background.warning`
+- `background.danger`
+
+### Border
+
+`border` tokens apply to component outlines, dividers, focus states, and validation states.
+
+- `border.default`
+- `border.subtle`
+- `border.strong`
+- `border.disabled`
+- `border.focus`
+- `border.brand`
+- `border.success`
+- `border.warning`
+- `border.danger`
+
+### Shape
+
+`shape` tokens control radius by usage, not component name.
+
+- `shape.action`
+- `shape.control`
+- `shape.card`
+- `shape.panel`
+- `shape.modal`
+- `shape.popover`
+- `shape.badge`
+- `shape.avatar`
+
+### Density
+
+`density` tokens control repeated spacing and sizing decisions.
+
+- `density.controlHeight`
+- `density.controlPaddingX`
+- `density.cardPadding`
+- `density.panelPadding`
+- `density.sectionGap`
+- `density.listRowHeight`
+- `density.tableRowHeight`
+
+### Elevation
+
+`elevation` tokens control shadows and stacking treatment.
+
+- `elevation.card`
+- `elevation.panel`
+- `elevation.popover`
+- `elevation.modal`
+- `elevation.none`
+
+## Component Rule
+
+Components consume semantic tokens and component-scoped aliases. They must not hard-code preset-specific values or Figma fallback literals in component source.
+
+If a Figma reference exposes a literal color, size, radius, shadow, or opacity, promote it into the generated token contract or a component-level `--bh-*` alias in `registry/styles/globals.css`, then consume that token from the component. Component docs may record Figma references for audit and QA, but those literals are not implementation fallbacks.
+
+Good:
+
+```tsx
+<Button variant="primary" />
+<Card />
+```
+
+Avoid:
+
+```tsx
+<Button rounded />
+<Card sharp />
+<Card className="rounded-[16px]" />
+```
+
+The preset is selected at the design-system root:
+
+```tsx
+<DesignSystemProvider appearance="default">
+  <App />
+</DesignSystemProvider>
+```
+
+or through a root attribute:
+
+```html
+<body data-appearance="default">
+```
+
+## Preset Responsibilities
+
+An appearance preset may change:
+
+- Page and layout background treatment
+- Card and panel background treatment
+- Radius for actions, controls, cards, modals, popovers, badges, and tabs
+- Component density and padding
+- Border prominence
+- Elevation and shadow strength
+- Hover, pressed, selected, and disabled treatment
+
+An appearance preset should not change:
+
+- Component behavior
+- Component variant names
+- Accessibility requirements
+- Interaction contracts
+- Information hierarchy
+- Meaning of semantic color roles