# Banhaten design system

Banhaten design system is an Arabic and English-first React design system. It installs source components into a project, shadcn-style:

```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
```

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, users, flags, 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:

```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
```

Run the local component playground:

```bash
npm --prefix playground install
npm run playground:dev
```

In a published package:

```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
```

After `init` or `add`, run your package manager install command when the CLI reports new dependencies:

```bash
npm install
```

## Getting Started

Use the CLI from the root of a React app:

```bash
npx banhaten init
npx banhaten add button input select
npm install
```

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.

## Tailwind And Aliases

Banhaten targets Tailwind CSS v4. `banhaten init` makes sure your configured CSS file includes Tailwind, then appends the Banhaten token block:

```css
@import "tailwindcss";
```

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"
  }
}
```

For non-Vite bundlers, make sure your TypeScript and bundler config resolve `@/*` to your source folder.

## Typography Utilities

The token CSS ships `.bh-text-*` classes for every Banhaten typography token:

```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

Banhaten themes are controlled by attributes on the document element:

```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` |
| `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:

```bash
npx banhaten diff
npx banhaten diff button
```

Refresh all detected installed components, or target a specific component:

```bash
npx banhaten update
npx banhaten update button
```

`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:

```tsx
<html lang="ar" dir="rtl">
```

or:

```tsx
<html lang="en" dir="ltr">
```

Components should avoid physical left/right styling unless there is a deliberate visual reason.
