banhaten 0.1.2 → 0.2.0

package/docs/design-system/components/alert-dialog.md

@@ -0,0 +1,87 @@
+# Alert Dialog
+
+Alert Dialog is the destructive or consequential confirmation primitive. It is backed by Radix AlertDialog so focus, Escape behavior, outside interaction, and alert-dialog semantics are handled by the correct primitive.
+
+## API
+
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="danger">Delete project</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogIcon intent="danger" />
+      <AlertDialogTitle>Delete project?</AlertDialogTitle>
+    </AlertDialogHeader>
+    <AlertDialogBody>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogBody>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete project</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `AlertDialog`, `AlertDialogTrigger`, `AlertDialogPortal` | Radix AlertDialog shell |
+| `AlertDialogOverlay`, `AlertDialogContent` | modal alert surface |
+| `AlertDialogHeader`, `AlertDialogBody`, `AlertDialogFooter` | layout regions |
+| `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogIcon` | accessible warning copy |
+| `AlertDialogCancel`, `AlertDialogAction` | safe cancel and confirm actions |
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `default`, `lg` |
+| `intent` | `default`, `warning`, `danger` |
+
+## Token Contract
+
+Alert Dialog uses Banhaten raised surface, backdrop, border, radius, shadow, semantic intent, body typography, focus, and button tokens.
+
+## RTL
+
+The surface inherits direction. Title and description use `dir="auto"` and action layout uses logical flex order.
+
+## Accessibility
+
+Use Alert Dialog for destructive or irreversible choices. Focus should land on the cancel action by default when you build higher-level confirmations. `ConfirmModal` is wired on top of this alert-dialog primitive for the constrained confirmation pattern.
+
+## Install
+
+```bash
+npx banhaten add alert-dialog
+```
+
+## Examples
+
+Primary registry example: `examples/alert-dialog-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs alert-dialog` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
+- `spacing`: Header, body, and footer use logical layout and Banhaten spacing tokens so action order and copy mirror naturally.
+- `semantics`: Radix AlertDialog provides the modal alert role, focus trap, and safe cancellation behavior.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/alert-dialog.tsx: AlertDialog, AlertDialogAction, AlertDialogBody, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogIcon, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, alertDialogContentVariants` |
+| `parts` | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogPortal`, `AlertDialogOverlay`, `AlertDialogHeader`, `AlertDialogIcon`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogBody`, `AlertDialogFooter`, `AlertDialogCancel`, `AlertDialogAction` |
+| `registryDependencies` | `button` |
+| `features` | `alert-dialog semantics`, `cancel focus pattern`, `safe cancel action`, `destructive action`, `semantic intent icon` |
+| `intents` | `default`, `warning`, `danger` |
+| `sizes` | `sm`, `default`, `lg` |
+| `tokens` | `--bh-alert-dialog-border`, `--bh-alert-dialog-width`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-component-default`, `--shadow-modal` |
+<!-- registry-contract:end -->

package/docs/design-system/components/alert.md

@@ -0,0 +1,111 @@
+# Alert
+
+`Alert` presents contextual feedback with compact and expandable layouts.
+
+Figma reference: `Design system 3.0 Copy / Alert`, node `158:4645`.
+
+## Variants
+
+The implementation covers the Alert matrix from Figma:
+
+| Prop | Values |
+| --- | --- |
+| `status` | `danger`, `success`, `warning`, `info`, `neutral` |
+| `isExpandable` | `false`, `true` |
+| `dir` | `ltr`, `rtl` |
+
+## API
+
+```tsx
+<Alert status="danger" title="Unable to save" />
+<Alert
+  actions={[{ label: "عرض التفاصيل", onClick: openDetails }]}
+  status="success"
+  isExpandable
+  dir="rtl"
+  title="تم الحفظ"
+/>
+```
+
+| Prop | Default |
+| --- | --- |
+| `status` | `neutral` |
+| `isExpandable` | `false`; requires at least one visible action |
+| `dir` | inherited |
+| `title` | none |
+| `description` | none |
+| `messages` | English close-button message; accepts partial localized overrides |
+| `closeLabel` | overrides `messages.close` |
+| `actions` | none |
+| `showActions` | auto when actions exist |
+| `showCloseButton` | auto when `onClose` exists |
+| `onClose` | none |
+
+## Pixel Rules
+
+- Compact alerts are `470px` wide and `56px` tall with `16px` padding.
+- Expandable alerts are `500px` wide, content-sized, and use `20px 16px` padding.
+- `isExpandable` falls back to the compact layout when no action is visible.
+- Compact rows use `8px` radius; expandable rows use `10px` radius.
+- Status icons and close controls are `20px`; the close glyph is `16px`.
+- Compact content uses `8px` between icon and title.
+- Expanded titles align to the block-start edge of the status icon.
+- Expandable content uses `12px` between icon, copy, close, and action rows.
+- The description-to-actions gap remains exactly `12px` as copy wraps.
+- Expanded action rows retain `20px` of block-end padding.
+- Expanded height grows with title and description content; direction does not select a height.
+- Titles use `15px / 24px` medium text.
+- Descriptions use `14px / 20px` regular text at `80%` opacity.
+
+## Token Contract
+
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
+
+- Backgrounds: `--bh-bg-danger-subtle`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-bg-info-subtle`, `--bh-bg-neutral-subtle`
+- Borders: `--bh-border-danger-subtle`, `--bh-border-success-subtle`, `--bh-border-warning-subtle`, `--bh-border-info-subtle`, `--bh-border-subtle`, `--bh-border-default`
+- Content: `--bh-content-danger-strong`, `--bh-content-success-strong`, `--bh-content-warning-strong`, `--bh-content-brand-strong`, `--bh-content-default`
+- Shape: `--bh-radius-lg-8`, `--bh-radius-xl-10`, `--bh-radius-full`
+- Space: `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-space-4xl-20`
+
+## Accessibility
+
+- The close affordance is a real button.
+- Action links are rendered as real buttons to support product actions.
+- Warning and danger use `role="alert"`; other statuses use `role="status"` unless overridden.
+- `dir` inherits by default and controls visual and reading direction only.
+- The close button keeps its English default under RTL. Pass `closeLabel` or `messages` for localized accessibility copy.
+- Product copy and action behavior are always explicit; the component does not ship demo text or no-op controls.
+
+## Install
+
+```bash
+npx banhaten add alert
+```
+
+## Examples
+
+Primary registry example: `examples/alert-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs alert` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `messages`: Direction does not select the close-button language. Pass closeLabel or messages explicitly.
+- `textAlignment`: Uses dir="auto" on title and description while the root dir prop mirrors icon, action, and close placement.
+- `spacing`: Uses flexbox, gap, and logical direction so compact and expandable RTL layouts match the Figma matrix.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/alert.tsx: Alert, alertVariants, arabicAlertMessages` |
+| `parts` | `Alert` |
+| `registryDependencies` | None |
+| `tokens` | `--bh-alert-compact-height`, `--bh-alert-compact-padding`, `--bh-alert-compact-radius`, `--bh-alert-compact-width`, `--bh-alert-expanded-padding-x`, `--bh-alert-expanded-padding-y`, `--bh-alert-expanded-radius`, `--bh-alert-expanded-width`, `--bh-alert-icon-size`, `--bh-bg-danger-subtle`, `--bh-bg-info-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-border-danger-subtle`, `--bh-border-default`, `--bh-border-info-subtle`, `--bh-border-subtle`, `--bh-border-success-subtle`, `--bh-border-warning-subtle`, `--bh-border-width-default`, `--bh-content-brand-default`, `--bh-content-brand-strong`, `--bh-content-danger-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-success-strong`, `--bh-content-warning-default`, `--bh-content-warning-strong`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-icon-stroke-225`, `--bh-opacity-80`, `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-underline-font-size`, `--bh-text-body-md-underline-font-weight`, `--bh-text-body-md-underline-letter-spacing`, `--bh-text-body-md-underline-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-button-focus` |
+| `variants` | `danger`, `success`, `warning`, `info`, `neutral` |
+<!-- registry-contract:end -->

package/docs/design-system/components/aspect-ratio.md

@@ -0,0 +1,59 @@
+# Aspect Ratio
+
+Aspect Ratio wraps Radix AspectRatio for fixed-format media, screenshots, and preview surfaces.
+
+## API
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/preview.png" alt="Preview" />
+</AspectRatio>
+```
+
+| Prop | Values |
+| --- | --- |
+| `ratio` | any positive number |
+
+## Token Contract
+
+Aspect Ratio uses Banhaten neutral background and radius tokens by default.
+
+## RTL
+
+Aspect Ratio is direction-neutral.
+
+## Accessibility
+
+Provide accessible names for media rendered inside the ratio box.
+
+## Install
+
+```bash
+npx banhaten add aspect-ratio
+```
+
+## Examples
+
+Primary registry example: `examples/aspect-ratio-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs aspect-ratio` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `geometry`: Aspect Ratio controls media geometry and does not alter text direction.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/aspect-ratio.tsx: AspectRatio` |
+| `parts` | `AspectRatio` |
+| `registryDependencies` | None |
+| `features` | `fixed media ratios`, `preview surfaces`, `responsive sizing` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-radius-xl-10` |
+<!-- registry-contract:end -->

package/docs/design-system/components/attribute.md

@@ -0,0 +1,103 @@
+# Attribute
+
+Attribute is a semantic description-list component for key-value information. It supports card headers, inline rows, right-aligned values, stacked mobile rows, two-column summaries, row dividers, bordered row groups, compact density, and RTL direction.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Attribute Card` (`255:123238`) and uses only existing Banhaten tokens.
+
+## API
+
+Use `AttributeCard` for the surface, `AttributeHeader` for optional title and description content, `AttributeList` for the `dl`, and `AttributeItem` for each `dt`/`dd` pair.
+
+```tsx
+<AttributeCard>
+  <AttributeHeader
+    title="Company profile"
+    description="Key-value information in a scannable card."
+  />
+  <AttributeList>
+    <AttributeItem label="Name">Acme Corporation</AttributeItem>
+    <AttributeItem label="Type">Business</AttributeItem>
+    <AttributeItem label="Industry">Software</AttributeItem>
+  </AttributeList>
+</AttributeCard>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `AttributeCard padding` | `default`, `compact` |
+| `AttributeList layout` | `inline`, `end`, `stacked`, `two-column` |
+| `AttributeList density` | `compact`, `default`, `comfortable` |
+| `AttributeList dividers` | `boolean` |
+| `AttributeList bordered` | `boolean` |
+| `AttributeList labelWidth` | CSS length, default `220px` |
+| `AttributeItem fullSpan` | `boolean`, useful in `two-column` layouts |
+| `AttributeItem truncate` | `boolean` |
+
+## Composition
+
+Values are open React slots. Compose existing primitives for status badges, copy buttons, file rows, progress bars, skeleton bars, links, and custom details.
+
+```tsx
+<AttributeList layout="end" dividers>
+  <AttributeItem label="Subscription">
+    <Badge color="green" type="dot">Active</Badge>
+  </AttributeItem>
+  <AttributeItem label="API key" truncate>
+    sk_live_************1234
+    <Button aria-label="Copy API key" size="icon-xs" variant="outline">
+      <CopyIcon />
+    </Button>
+  </AttributeItem>
+</AttributeList>
+```
+
+## RTL
+
+Attribute inherits direction from any parent. The component uses logical text alignment and `dir="auto"` wrappers for string labels and values, so Arabic and English content can sit in the same card without manual left/right classes.
+
+## Install
+
+```bash
+npx banhaten add attribute
+```
+
+## Examples
+
+Primary registry example: `examples/attribute-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs attribute` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/attribute.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Uses logical text alignment and inherited direction so label and value columns mirror naturally.
+- `textDirection`: String labels and values use dir="auto" wrappers while custom slots can control their own direction.
+- `composition`: Rows accept ReactNode values, so badges, buttons, links, progress bars, skeletons, files, and custom content can be composed from existing Banhaten primitives.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/attribute.tsx: AttributeCard, AttributeHeader, AttributeItem, AttributeLabel, AttributeList, AttributeValue, attributeCardVariants, attributeHeaderVariants, attributeItemVariants, attributeLabelVariants, attributeListVariants, attributeValueVariants` |
+| `parts` | `AttributeCard`, `AttributeHeader`, `AttributeList`, `AttributeItem`, `AttributeLabel`, `AttributeValue` |
+| `registryDependencies` | None |
+| `densities` | `compact`, `default`, `comfortable` |
+| `layouts` | `inline`, `end`, `stacked`, `two-column` |
+| `tokens` | `--bh-attribute-header-icon-size`, `--bh-attribute-header-icon-size-lg`, `--bh-attribute-label-width`, `--bh-bg-default`, `--bh-bg-neutral-soft`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-medium-font-size`, `--bh-text-heading-sm-medium-font-weight`, `--bh-text-heading-sm-medium-letter-spacing`, `--bh-text-heading-sm-medium-line-height` |
+<!-- registry-contract:end -->

package/docs/design-system/components/autocomplete.md

@@ -0,0 +1,93 @@
+# Autocomplete
+
+Autocomplete is a searchable combobox field for choosing one or many known options.
+
+The implementation is intentionally composed from existing Banhaten primitives: `Input` owns the field surface, `SelectMenu` and `SelectMenuItem` own the result list, and `Tag` owns selected multi-value chips. The component adds filtering, selected-value state, keyboard navigation, ARIA combobox wiring, and controlled or uncontrolled APIs.
+
+## API
+
+```tsx
+<Autocomplete
+  label="Owner"
+  placeholder="Search people"
+  options={[
+    { value: "ahmed", label: "Ahmed Galal", addonText: "Design system" },
+    { value: "nora", label: "Nora Ali", addonText: "Product" },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `options` | `{ value, label, addonText, itemType, media, keywords, disabled }[]` | required |
+| `selectionMode` | `single`, `multiple` | `single` |
+| `value` / `defaultValue` | `string` or `string[]` | none |
+| `inputValue` / `defaultInputValue` | `string` | inferred from selected single value |
+| `open` / `defaultOpen` | `boolean` | `false` |
+| `filterOptions` | custom filtering function | label, value, and keywords filter |
+| `size` | `md`, `lg` | `lg` |
+| `variant` | `default`, `soft` | `default` |
+| `state` | `default`, `filled`, `error`, `disabled` | inferred |
+| `dir` | `ltr`, `rtl`, `auto` | inherited |
+
+## Composition Rules
+
+- Use autocomplete for known option sets that benefit from search.
+- Use `Select` when the option set is short and browsing is faster than typing.
+- Use `selectionMode="multiple"` when selected options need removable chips; chips render with `Tag`.
+- Keep async fetching, debouncing, and remote loading in product code by controlling `inputValue`, `open`, and `options`.
+- Keep option labels concise. Use `addonText` for secondary metadata.
+
+## Accessibility
+
+- The input uses `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`, `aria-controls`, and `aria-activedescendant`.
+- Results render as a `listbox` using Select menu rows.
+- Arrow keys move the active option, `Enter` selects, `Escape` closes, and `Backspace` removes the last selected tag in multiple mode when the search field is empty.
+- Labels and helper text are associated with the input, and error state maps to `aria-invalid`.
+
+## Token Contract
+
+Autocomplete consumes tokens through the primitives it composes:
+
+- Field surface, typography, icon sizing, focus ring, and disabled/error states from `Input`.
+- Menu surface, item rows, hover state, selected check, and item media slots from `Select`.
+- Removable selected chips from `Tag`.
+- Additional layout uses spacing, content, and z-index tokens only.
+
+## Install
+
+```bash
+npx banhaten add autocomplete
+```
+
+## Examples
+
+Primary registry example: `examples/autocomplete-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs autocomplete` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `composition`: Uses the existing Input field, Select menu and menu item rows, and Tag chips instead of introducing new visual primitives.
+- `spacing`: Uses logical positioning, logical gaps, and inherited direction so the input, menu rows, checks, helper text, and selected tags mirror naturally.
+- `textDirection`: Labels, option text, helper text, and tag labels use dir="auto" through the composed primitives.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/autocomplete.tsx: Autocomplete, defaultFilterOptions` |
+| `parts` | `Autocomplete` |
+| `registryDependencies` | `input`, `popover`, `select`, `tag` |
+| `features` | `filtering`, `keyboard navigation`, `controlled value`, `controlled input value`, `controlled open state`, `selected tags`, `empty state` |
+| `modes` | `single`, `multiple` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-autocomplete-menu-max-height`, `--bh-content-subtle`, `--bh-icon-stroke-225`, `--bh-input-icon-size`, `--bh-input-width`, `--bh-select-item-hover-bg`, `--bh-select-item-padding-x`, `--bh-select-menu-width`, `--bh-select-width`, `--bh-space-18xl-320`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

package/docs/design-system/components/avatar.md

@@ -0,0 +1,70 @@
+# Avatar
+
+Avatar represents people, accounts, teams, and system actors. It supports images, initials, icon fallback, circular or rounded forms, status dots, action overlays, stacked groups, group counts, size scale, and RTL-safe overlap.
+
+## API
+
+```tsx
+<Avatar name="Ahmed Galal" src="/avatars/avatar-01.jpg" status="available" />
+
+<AvatarGroup>
+  <Avatar name="Nora" />
+  <Avatar name="Omar" />
+  <AvatarGroupCount>+4</AvatarGroupCount>
+</AvatarGroup>
+```
+
+| Prop | Values |
+| --- | --- |
+| `size` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` |
+| `form` | `circular`, `rounded` |
+| `status` | `offline`, `busy`, `blocked`, `available`, `away` |
+| `action` | `custom`, `edit`, `verified`, `remove` |
+
+## Token Contract
+
+Avatar consumes Banhaten radius, sizing, border, shadow, status, background, and content tokens. Status and action markers should stay token-bound so themes and dark mode remain consistent.
+
+## RTL
+
+Avatar groups use logical negative margin so overlap reverses naturally in RTL. Status and action affordances use logical end placement.
+
+## Accessibility
+
+Use `name` or accessible image alt text for user avatars. Decorative grouped avatars can be hidden from assistive tech when the surrounding row already names the people.
+
+## Install
+
+```bash
+npx banhaten add avatar
+```
+
+## Examples
+
+Primary registry example: `examples/avatar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs avatar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `groupOverlap`: Uses logical -ms spacing so overlap reverses naturally in RTL.
+- `badgePlacement`: Status dots use logical end/bottom positioning; avatar actions use logical end/top positioning.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/avatar.tsx: Avatar, AvatarAction, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarIcon, AvatarImage, AvatarStatus, avatarActionVariants, avatarStatusVariants, avatarVariants` |
+| `parts` | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarIcon`, `AvatarBadge`, `AvatarStatus`, `AvatarAction`, `AvatarGroup`, `AvatarGroupCount` |
+| `registryDependencies` | None |
+| `actions` | `custom`, `edit`, `verified`, `remove` |
+| `forms` | `circular`, `rounded` |
+| `sizes` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` |
+| `statusColors` | `offline`, `busy`, `blocked`, `available`, `away` |
+| `tokens` | `--bh-avatar-action-icon-size`, `--bh-avatar-action-icon-size-2xl`, `--bh-avatar-action-icon-size-3xl`, `--bh-avatar-action-icon-size-4xl`, `--bh-avatar-action-icon-size-large`, `--bh-avatar-action-icon-size-medium`, `--bh-avatar-action-icon-size-small`, `--bh-avatar-action-icon-size-tiny`, `--bh-avatar-action-icon-size-xlarge`, `--bh-avatar-action-icon-size-xsmall`, `--bh-avatar-action-size`, `--bh-avatar-action-size-2xl`, `--bh-avatar-action-size-3xl`, `--bh-avatar-action-size-4xl`, `--bh-avatar-action-size-large`, `--bh-avatar-action-size-medium`, `--bh-avatar-action-size-small`, `--bh-avatar-action-size-tiny`, `--bh-avatar-action-size-xlarge`, `--bh-avatar-action-size-xsmall`, `--bh-avatar-fallback-font-size-2xl`, `--bh-avatar-fallback-font-size-2xs`, `--bh-avatar-fallback-font-size-3xl`, `--bh-avatar-fallback-font-size-4xl`, `--bh-avatar-fallback-font-size-lg`, `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-sm`, `--bh-avatar-fallback-font-size-xl`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-fallback-size`, `--bh-avatar-icon-size`, `--bh-avatar-icon-size-2xl`, `--bh-avatar-icon-size-2xs`, `--bh-avatar-icon-size-3xl`, `--bh-avatar-icon-size-4xl`, `--bh-avatar-icon-size-lg`, `--bh-avatar-icon-size-md`, `--bh-avatar-icon-size-sm`, `--bh-avatar-icon-size-xl`, `--bh-avatar-icon-size-xs`, `--bh-avatar-radius`, `--bh-avatar-size`, `--bh-avatar-size-2xl`, `--bh-avatar-size-2xs`, `--bh-avatar-size-3xl`, `--bh-avatar-size-4xl`, `--bh-avatar-size-lg`, `--bh-avatar-size-md`, `--bh-avatar-size-sm`, `--bh-avatar-size-xl`, `--bh-avatar-size-xs`, `--bh-avatar-status-ring`, `--bh-avatar-status-ring-default`, `--bh-avatar-status-ring-thin`, `--bh-avatar-status-size`, `--bh-avatar-status-size-large`, `--bh-avatar-status-size-medium`, `--bh-avatar-status-size-small`, `--bh-avatar-status-size-tiny`, `--bh-avatar-status-size-xlarge`, `--bh-avatar-status-size-xsmall`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-subtle`, `--bh-bg-success-default`, `--bh-border-width-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-weight-semibold`, `--bh-icon-stroke-210`, `--bh-icon-stroke-240`, `--bh-icon-stroke-260`, `--bh-icon-stroke-280`, `--bh-interactive-brand-default`, `--bh-interactive-danger-default`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-sm-medium-font-size`, `--shadow-avatar-badge` |
+<!-- registry-contract:end -->

package/docs/design-system/components/badge.md

@@ -0,0 +1,72 @@
+# Badge
+
+Badge is a compact status, count, classification, or metadata primitive. It supports light, outline, and solid styles; semantic color families; dot, flag, leading icon, trailing icon, numeric, and split-action compositions; and RTL-safe layout.
+
+## API
+
+```tsx
+<Badge color="green">Active</Badge>
+<Badge color="blue" type="dot">New</Badge>
+<Badge color="neutral" type="trailing-icon" splitAction>
+  Filter
+</Badge>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `style` | `light`, `outline`, `solid` | `light` |
+| `color` | `neutral`, `blue`, `green`, `amber`, `danger`, `purple`, `fuchsia`, `rose`, `sky`, `golden` | `neutral` |
+| `type` | `default`, `leading-icon`, `trailing-icon`, `dot`, `flag` | `default` |
+| `size` | `sm`, `lg` | `sm` |
+| `splitAction` | `boolean` | `false` |
+
+## Token Contract
+
+Badge uses semantic content, background, border, radius, typography, icon, opacity, and focus tokens. Provider or brand colors should be added through semantic aliases, not raw literals.
+
+## RTL
+
+Use `data-icon="inline-start"` or `data-icon="inline-end"` on icons. Directional arrows should also set `data-rtl-flip="true"`.
+
+## Accessibility
+
+Badges are usually descriptive text. Do not use color alone for critical status; include a readable label such as `Failed`, `Warning`, or `Active`.
+
+## Install
+
+```bash
+npx banhaten add badge
+```
+
+## Examples
+
+Primary registry example: `examples/badge-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs badge` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `iconPlacement`: Set type="leading-icon" or type="trailing-icon" and use data-icon="inline-start" or data-icon="inline-end". Add splitAction to give a trailing icon its own token-sized compartment.
+- `directionalIconFlip`: Use data-rtl-flip="true" on arrows that should mirror.
+- `textDirection`: Uses dir="auto" by default for short Arabic and English labels.
+- `legacyVariants`: The previous variant prop is still accepted as a compatibility shim.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/badge.tsx: Badge, badgeVariants` |
+| `parts` | `Badge` |
+| `registryDependencies` | None |
+| `colors` | `neutral`, `blue`, `green`, `amber`, `danger`, `purple`, `fuchsia`, `rose`, `sky`, `golden` |
+| `options` | `splitAction` |
+| `sizes` | `sm`, `lg` |
+| `styles` | `light`, `outline`, `solid` |
+| `tokens` | `--bh-badge-focus-ring-width`, `--bh-badge-outline-border-width`, `--bh-bg-accent-amber-default`, `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-blue-subtle`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-golden-subtle`, `--bh-bg-accent-green-default`, `--bh-bg-accent-green-subtle`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-purple-subtle`, `--bh-bg-accent-red-default`, `--bh-bg-accent-red-subtle`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-rose-subtle`, `--bh-bg-accent-sky-base`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-border-accent-amber-strong`, `--bh-border-accent-amber-subtle`, `--bh-border-accent-blue-strong`, `--bh-border-accent-blue-subtle`, `--bh-border-accent-fuchsia-strong`, `--bh-border-accent-fuchsia-subtle`, `--bh-border-accent-golden-strong`, `--bh-border-accent-golden-subtle`, `--bh-border-accent-green-strong`, `--bh-border-accent-green-subtle`, `--bh-border-accent-purple-strong`, `--bh-border-accent-purple-subtle`, `--bh-border-accent-red-strong`, `--bh-border-accent-red-subtle`, `--bh-border-accent-rose-strong`, `--bh-border-accent-rose-subtle`, `--bh-border-accent-sky-strong`, `--bh-border-accent-sky-subtle`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-focus-danger`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-content-accent-amber-default`, `--bh-content-accent-amber-strong`, `--bh-content-accent-blue-default`, `--bh-content-accent-blue-strong`, `--bh-content-accent-fuchsia-default`, `--bh-content-accent-fuchsia-strong`, `--bh-content-accent-golden-default`, `--bh-content-accent-golden-strong`, `--bh-content-accent-green-default`, `--bh-content-accent-green-strong`, `--bh-content-accent-purple-default`, `--bh-content-accent-purple-strong`, `--bh-content-accent-red-default`, `--bh-content-accent-red-strong`, `--bh-content-accent-rose-default`, `--bh-content-accent-rose-strong`, `--bh-content-accent-sky-default`, `--bh-content-accent-sky-strong`, `--bh-content-default`, `--bh-content-link`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-on-light`, `--bh-content-subtle`, `--bh-interactive-ghost-default`, `--bh-opacity-35`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-2xs-semibold-font-weight`, `--bh-text-body-3xs-medium-font-size`, `--bh-text-body-3xs-medium-font-weight`, `--bh-text-body-3xs-medium-letter-spacing`, `--bh-text-body-3xs-medium-line-height`, `--bh-text-body-3xs-semibold-font-weight` |
+| `types` | `default`, `leading-icon`, `trailing-icon`, `dot`, `flag` |
+<!-- registry-contract:end -->