banhaten 0.1.2 → 0.2.0

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

@@ -0,0 +1,99 @@
+# Banner
+
+`Banner` presents short product announcements, notices, or lightweight calls to action.
+
+Figma reference: `Design system 3.0 Copy / Banner`, node `237:39513`.
+
+## Variants
+
+The implementation covers the Banner matrix from Figma:
+
+| Prop | Values |
+| --- | --- |
+| `type` | `slim`, `single-action-inline`, `single-action`, `input` |
+| `size` | `floating`, `full-width` |
+| `content` | `title`, `title-description` |
+| `color` | `brand`, `grey`, `brand-light` |
+| `dir` | `ltr`, `rtl` |
+
+## API
+
+```tsx
+<Banner
+  type="single-action"
+  size="floating"
+  content="title"
+  color="brand"
+  dir="ltr"
+/>
+```
+
+| Prop | Default |
+| --- | --- |
+| `title` | localized demo title |
+| `description` | localized demo description |
+| `linkLabel` | `Link button` |
+| `actionLabel` | `Button` |
+| `inputPlaceholder` | `Placeholder` |
+| `showIcon` | `true` |
+| `showInlineAction` | `true` |
+| `onAction` | none |
+| `onClose` | none |
+
+## Pixel Rules
+
+- Root padding is `12px 16px`.
+- Slim title rows are `48px`; slim title-description rows are `52px`.
+- Single-action, inline-action, and input rows are `60px`.
+- Floating rows use `10px` radius; full-width rows have square edges.
+- Leading icon is `20px`; close icon is `16px`.
+- Action controls and text inputs are `36px` tall with `8px` radius.
+- LTR body text uses `15px / 24px`. RTL title-only body text uses `12px / 16px`.
+- Title-description content uses a semibold title, a `17px / 28px` separator dot, and regular description text.
+
+## 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-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-muted`, `--bh-bg-always-white`
+- Content: `--bh-content-default`, `--bh-content-inverse`, `--bh-content-link`, `--bh-content-muted`, `--bh-content-subtle`
+- Borders: `--bh-border-subtle`, `--bh-border-input`
+- Shape: `--bh-control-default`, `--bh-radius-lg-8`, `--bh-radius-xl-10`
+- Space: `--bh-space-xs-4`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-xl-12`, `--bh-space-3xl-16`
+
+## Accessibility
+
+- The banner root exposes an `aria-label`.
+- Link, action, and close affordances are real buttons.
+- The input variant uses a real text input with an `aria-label`.
+- RTL is controlled through `dir="rtl"` so icon, text, action, input, and close placement mirror logically.
+
+## Install
+
+```bash
+npx banhaten add banner
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/banner-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs banner` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- 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/expanded/Banner.tsx: Banner` |
+| `parts` | `Banner` |
+| `registryDependencies` | `button`, `input` |
+| `tokens` | `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-muted`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-inverse`, `--bh-content-link`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-210`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-font-weight`, `--bh-text-body-lg-medium-line-height`, `--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`, `--shadow-component-default` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,188 @@
+# Breadcrumbs
+
+Breadcrumbs show a user's location in a hierarchy and provide a quick path back to parent pages. Use `Breadcrumbs` for page-level navigation, not for step progress, tabs, or filters.
+
+Figma reference: `Breadcrumbs`, node `238:7987`.
+
+## Variants
+
+The Figma component defines these variants:
+
+| Type | Style | Separator type | Direction |
+| --- | --- | --- | --- |
+| `Default` | `Default` | `Slash` | LTR and RTL |
+| `Default` | `Default` | `Chevron` | LTR and RTL |
+| `Default` | `Raised` | `Slash` | LTR and RTL |
+| `Default` | `Raised` | `Chevron` | LTR and RTL |
+| `Only Icon` | `Default` | `Slash` | LTR and RTL |
+| `Only Icon` | `Default` | `Chevron` | LTR and RTL |
+| `Only Icon` | `Raised` | `Slash` | LTR and RTL |
+| `Only Icon` | `Raised` | `Chevron` | LTR and RTL |
+
+The Figma source supports up to six visible breadcrumb items. Code should model this as an `items` collection instead of positional booleans such as `showBreadcrumb01`.
+
+## API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type BreadcrumbSeparator = "slash" | "chevron";
+type BreadcrumbStyle = "default" | "raised";
+
+type BreadcrumbItem = {
+  label: string;
+  href?: string;
+  icon?: React.ReactNode;
+  current?: boolean;
+};
+
+type BreadcrumbsProps = {
+  items: BreadcrumbItem[];
+  separator?: BreadcrumbSeparator;
+  style?: BreadcrumbStyle;
+  iconOnly?: boolean;
+  dir?: "ltr" | "rtl" | "auto";
+  maxItems?: number;
+  "aria-label"?: string;
+};
+```
+
+`items` should be ordered from root to current page in logical reading order. RTL rendering should mirror the visual order through layout direction, not by reversing the source data.
+
+## Layout
+
+- The root is a horizontal flex row with centered alignment.
+- The default style has no container background and uses a compact inline gap.
+- The raised style adds a surface fill, a 1px border, 12px padding, and an 8px radius in the Figma source.
+- Text items use `Body/body-md (base)/medium` with a 15px size and 24px line height.
+- Item icons are 20px square.
+- Slash and chevron separators are 16px square and should be decorative.
+- LTR chevrons point right; RTL chevrons point left.
+- The icon-only type keeps the same item and separator rhythm but hides visible labels.
+- Do not allow wrapping inside individual breadcrumb labels unless the component has a deliberate collapsed or overflow mode.
+
+## Tokens
+
+Breadcrumbs should consume existing semantic tokens:
+
+```ts
+export const breadcrumbsTokens = {
+  itemColor: "content.subtle",
+  currentItemColor: "content.default",
+  iconColor: "content.subtle",
+  separatorColor: "content.subtle",
+  raisedBackground: "background.card",
+  raisedBorder: "border.subtle",
+  raisedRadius: "shape.control",
+  inlineGap: "space.xs-4",
+  raisedGap: "space.md-8",
+  raisedPadding: "space.xl-12",
+};
+```
+
+Do not hard-code Figma fallback values in component code. The current Figma fallbacks include `content/subtle` as `#4e596e`, `bg/raised` as white, `border/subtle` as `rgba(55, 83, 122, 0.13)`, and `radius/lg-8` as 8px. Implementations should resolve those through semantic tokens.
+
+If the design system later adds a dedicated `background.raised` token, the raised style can map to it. Until then, use the closest raised surface token such as `background.card`.
+
+## Accessibility
+
+- Render the component as navigation, usually `<nav aria-label="Breadcrumb">`.
+- Use an ordered list so the hierarchy is exposed to assistive technology.
+- Render linked ancestors as anchors.
+- Mark the current page with `aria-current="page"` and do not require it to be a link.
+- Hide separators from assistive technology with `aria-hidden="true"`.
+- Icon-only breadcrumbs must provide an accessible label for every item, even when visible text is hidden.
+- Preserve logical item order for screen readers in RTL contexts.
+- Provide keyboard focus treatment through the link or action primitive, not on decorative separators.
+
+## Usage
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Products", href: "/products" },
+    { label: "Analytics", current: true },
+  ]}
+/>
+
+<Breadcrumbs
+  separator="chevron"
+  style="raised"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Reports", href: "/reports" },
+    { label: "Monthly", current: true },
+  ]}
+/>
+
+<Breadcrumbs
+  iconOnly
+  aria-label="Breadcrumb"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Settings", href: "/settings", icon: <SettingsIcon /> },
+    { label: "Profile", current: true, icon: <UserIcon /> },
+  ]}
+/>
+
+<Breadcrumbs
+  dir="rtl"
+  separator="chevron"
+  items={[
+    { label: "Home", href: "/", icon: <HomeIcon /> },
+    { label: "Account", href: "/account" },
+    { label: "Security", current: true },
+  ]}
+/>
+```
+
+## Preset Impact
+
+- `default`: inline breadcrumbs remain quiet, and raised breadcrumbs use a modest surface radius with subtle border separation.
+- `rounded`: raised breadcrumbs can use the softer control radius and slightly more relaxed spacing.
+- `sharp`: raised breadcrumbs should use square or near-square corners and tighter horizontal rhythm.
+
+## Implementation Notes
+
+- Use the design system's icon primitive for home and chevron icons. The Figma source uses Remix Icon `home-5-line`, `arrow-right-s-line`, and `arrow-left-s-line`.
+- Generate separators between items instead of requiring callers to include separator items.
+- Keep overflow behavior explicit. If the trail is too long, collapse middle items behind an overflow control instead of silently hiding the current page.
+- Prefer `dir` or logical CSS properties for RTL behavior rather than maintaining separate RTL item arrays.
+- The raised style is a navigation surface, not a card. Keep elevation at `elevation.none` unless a consuming product places it inside an overlay.
+
+## Install
+
+```bash
+npx banhaten add breadcrumbs
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/breadcrumbs-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs breadcrumbs` 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/expanded/breadcrumbs.css`, `components/expanded/Breadcrumbs.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- 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/expanded/Breadcrumbs.tsx: BreadcrumbFolderIcon, BreadcrumbHomeIcon, Breadcrumbs` |
+| `parts` | `Breadcrumbs` |
+| `registryDependencies` | None |
+| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-stroke-190`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height` |
+<!-- registry-contract:end -->

package/docs/design-system/components/button-group.md

@@ -0,0 +1,117 @@
+# Button Group
+
+Button Group is a connected set of related button actions. It supports text buttons and icon-only buttons, three sizes, inherited LTR/RTL direction, logical dividers, and tokenized interaction states.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Button Group Item 1.2` (`390:12399`).
+
+## API
+
+Use `ButtonGroup` as the connected container and `ButtonGroupItem` for each action.
+
+```tsx
+<ButtonGroup aria-label="View options" size="md">
+  <ButtonGroupItem>
+    <PlusIcon data-icon="inline-start" />
+    Button
+    <PlusIcon data-icon="inline-end" />
+  </ButtonGroupItem>
+  <ButtonGroupItem aria-pressed>
+    <PlusIcon data-icon="inline-start" />
+    Active
+    <PlusIcon data-icon="inline-end" />
+  </ButtonGroupItem>
+</ButtonGroup>
+```
+
+Use `ToggleGroup` when the connected controls own a single or multiple pressed-value model. It includes controlled and uncontrolled state plus Home, End, and direction-aware arrow-key focus movement.
+
+```tsx
+<ToggleGroup aria-label="Text alignment" defaultValue="start">
+  <ToggleGroupItem value="start">Start</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+  <ToggleGroupItem value="end">End</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `sm`, `xs` |
+| `mode` | `default`, `iconOnly` |
+| `ButtonGroupItem aria-pressed` | `true`, `false` |
+| `ButtonGroupItem disabled` | `boolean` |
+| `ToggleGroup type` | `single`, `multiple` |
+| `ToggleGroup value`, `defaultValue` | `string`, `string[]` |
+| `ToggleGroupItem value` | `string` |
+
+Interaction styling is applied through native CSS pseudo states: `:hover`, `:active`, `:focus-visible`, `:disabled`, and `aria-pressed="true"`.
+
+## States
+
+| State | Background | Content |
+| --- | --- | --- |
+| Default | `--bh-button-group-item-bg` | `--bh-button-group-content-default` |
+| Hover | `--bh-button-group-item-hover-bg` | `--bh-button-group-content-default` |
+| Pressed | `--bh-button-group-item-pressed-bg` | `--bh-button-group-content-default` |
+| Active | `--bh-button-group-item-active-bg` | `--bh-button-group-content-active` |
+| Disabled | `--bh-button-group-item-disabled-bg` | `--bh-button-group-content-disabled` |
+
+## Dimensions
+
+| Size | Height | LTR text item | RTL text item | Icon-only item |
+| --- | ---: | ---: | ---: | ---: |
+| `md` | 40px | 128px | 124px | 40px |
+| `sm` | 36px | 120px | 116px | 36px |
+| `xs` | 32px | 112px | 108px | 32px |
+
+Text buttons use the design-system button typography tokens. Icon-only buttons require an accessible label.
+
+## Install
+
+```bash
+npx banhaten add button-group
+```
+
+## Examples
+
+Primary registry example: `examples/button-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs button-group` 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/button-group.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `itemSizing`: LTR and RTL default items keep their fixed Figma matrix widths. Icon-only groups keep the same square dimensions.
+- `spacing`: Uses logical dividers and inherited flex direction so item order, icon order, padding, and separators follow LTR or RTL.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
+<!-- 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/button-group.tsx: ButtonGroup, ButtonGroupItem, ButtonGroupLabel, ToggleGroup, ToggleGroupItem, buttonGroupItemVariants, buttonGroupLabelVariants, buttonGroupVariants` |
+| `parts` | `ButtonGroup`, `ButtonGroupItem`, `ButtonGroupLabel`, `ToggleGroup`, `ToggleGroupItem` |
+| `registryDependencies` | None |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "comfortable"; Preferred cross-component sizing contract. Maps to legacy xs, sm, or md group sizes.` |
+| `props.itemWidth` | `"fixed" \| "content"; default "fixed"; Uses the reviewed fixed matrix widths or lets each text item hug its content.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `modes` | `default`, `iconOnly` |
+| `selectionTypes` | `single`, `multiple` |
+| `sizes` | `md`, `sm`, `xs` |
+| `tokens` | `--bh-border-width-default`, `--bh-button-group-bg`, `--bh-button-group-border`, `--bh-button-group-content`, `--bh-button-group-content-active`, `--bh-button-group-content-disabled`, `--bh-button-group-divider`, `--bh-button-group-icon-size`, `--bh-button-group-item-active-bg`, `--bh-button-group-item-bg`, `--bh-button-group-item-disabled-bg`, `--bh-button-group-item-hover-bg`, `--bh-button-group-item-pressed-bg`, `--bh-button-group-label-padding-x`, `--bh-button-group-md-gap`, `--bh-button-group-md-height`, `--bh-button-group-md-icon-padding-x`, `--bh-button-group-md-item-rtl-width`, `--bh-button-group-md-item-width`, `--bh-button-group-md-padding-x`, `--bh-button-group-radius`, `--bh-button-group-sm-gap`, `--bh-button-group-sm-height`, `--bh-button-group-sm-icon-padding-x`, `--bh-button-group-sm-item-rtl-width`, `--bh-button-group-sm-item-width`, `--bh-button-group-sm-padding-x`, `--bh-button-group-xs-gap`, `--bh-button-group-xs-height`, `--bh-button-group-xs-icon-padding-x`, `--bh-button-group-xs-item-rtl-width`, `--bh-button-group-xs-item-width`, `--bh-button-group-xs-padding-x`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--bh-z-raised`, `--shadow-button-group`, `--shadow-button-group-focus`, `--shadow-component-default` |
+| `widths` | `fixed`, `content` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,95 @@
+# Button
+
+Button is the primary action primitive for forms, workflows, navigation actions, and destructive confirmations. It supports semantic variants, text and icon sizes, loading composition, link composition through `asChild`, and RTL-safe icon behavior.
+
+## API
+
+```tsx
+<Button variant="default" size="default">
+  Save changes
+</Button>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white` | `default` |
+| `size` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `default` |
+| `asChild` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `aria-busy` | `boolean` | none |
+
+## Examples
+
+```tsx
+<Button>
+  <PlusIcon data-icon="inline-start" />
+  New item
+</Button>
+
+<Button variant="outline">
+  Continue
+  <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
+</Button>
+
+<Button disabled aria-busy="true">
+  <Spinner data-icon="inline-start" />
+  Loading
+</Button>
+```
+
+```tsx
+<div dir="rtl">
+  <Button>إرسال</Button>
+  <Button variant="outline">
+    متابعة
+    <ArrowRightIcon data-icon="inline-end" data-rtl-flip="true" />
+  </Button>
+</div>
+```
+
+## Token Contract
+
+Button consumes semantic interaction, content, border, radius, typography, spacing, opacity, and shadow tokens. Component source should not hard-code Figma color, spacing, radius, or shadow literals.
+
+- Typography: `--bh-text-button-font-size`, `--bh-text-button-line-height`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`
+- Shape: `--bh-control-default`
+- Heights and padding: `--bh-button-*-height`, `--bh-button-*-padding-x`, `--bh-button-*-padding-y`
+- Icon rhythm: `--bh-button-icon-size`, `--bh-button-icon-offset`, `--bh-button-label-padding-x`
+- Effects: `--shadow-button-raised`, `--shadow-button-secondary`, `--shadow-button-soft`, `--shadow-button-focus`, `--shadow-button-danger-focus`
+
+## RTL Rules
+
+- Button inherits `dir` from the nearest parent.
+- Text labels render with `dir="auto"` so Arabic and English labels resolve naturally.
+- Use `data-icon="inline-start"` and `data-icon="inline-end"` for optical icon offsets.
+- Use `data-rtl-flip="true"` only for directional icons that should mirror, such as arrows and chevrons.
+
+## Accessibility
+
+- Use native `type`, `disabled`, and `aria-busy` attributes for behavior.
+- Icon-only buttons must have an accessible name through `aria-label`.
+- Use `asChild` for anchors or router links instead of nesting interactive elements.
+
+## Install
+
+```bash
+npx banhaten add button
+```
+
+<!-- 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/button.tsx: Button, buttonVariants` |
+| `parts` | `Button` |
+| `registryDependencies` | `spinner` |
+| `props.density` | `"compact" \| "default" \| "comfortable"; default "comfortable"; Preferred cross-component sizing contract. Maps to legacy xs, sm, or default sizes while preserving icon-only sizing.` |
+| `densities` | `compact`, `default`, `comfortable` |
+| `sizes` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` |
+| `tokens` | `--bh-bg-always-white`, `--bh-bg-success-bold`, `--bh-bg-success-default`, `--bh-bg-success-strong`, `--bh-bg-warning-bold`, `--bh-bg-warning-default`, `--bh-bg-warning-strong`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-label-padding-x`, `--bh-button-lg-height`, `--bh-button-lg-padding-x`, `--bh-button-lg-padding-y`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-secondary-border`, `--bh-button-secondary-focus-border`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xl-height`, `--bh-button-xl-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-brand`, `--bh-content-on-color`, `--bh-content-on-light`, `--bh-control-default`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-danger-default`, `--bh-interactive-danger-disabled`, `--bh-interactive-danger-hover`, `--bh-interactive-danger-pressed`, `--bh-interactive-danger-soft-default`, `--bh-interactive-danger-soft-disabled`, `--bh-interactive-danger-soft-hover`, `--bh-interactive-danger-soft-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-interactive-secondary-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-opacity-30`, `--bh-space-none`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-secondary`, `--shadow-button-secondary-focus`, `--shadow-button-soft` |
+| `variants` | `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,95 @@
+# Card
+
+Card is a token-built surface primitive for product summaries, media tiles, and action panels. It supports vertical and horizontal layouts, leading and trailing image treatments, full-image cards, desktop/mobile spacing, footer actions, and RTL-safe text.
+
+## Install
+
+```bash
+npx banhaten add card
+```
+
+## Anatomy
+
+- `Card`: root surface with title, subtitle, description, media, and optional footer composition.
+- `CardMedia`: image/media slot with leading, trailing, or full-image treatment.
+- `CardFooter`: supporting metadata or action area.
+- `CardActions`: Button-composed primary and secondary actions.
+
+## Example
+
+```tsx
+import { Card } from "@/components/ui/card"
+
+export function Example() {
+  return (
+    <Card
+      title="Project activity"
+      subtitle="Updated 2 minutes ago"
+      description="A compact summary of the latest workspace changes."
+      orientation="horizontal"
+      type="leading-image"
+    />
+  )
+}
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `orientation` | `vertical`, `horizontal` |
+| `type` | `leading-image`, `trailing-image`, `full-image` |
+| `breakpoint` | `desktop`, `mobile` |
+| `dir` | inherited, `ltr`, `rtl` |
+
+## RTL
+
+Card uses logical spacing, inherited direction, and `dir="auto"` copy wrappers so title, subtitle, description, footer actions, and menu affordances mirror naturally.
+
+## API
+
+Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `cardVariants`.
+
+| Contract | Values |
+| --- | --- |
+| `types` | `leading-image`, `trailing-image`, `full-image` |
+| `orientations` | `vertical`, `horizontal` |
+
+## Examples
+
+Primary registry example: `examples/card-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs card` 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/card.tsx`, `assets/images/art-01.jpg`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical direction, text-start behavior, and dir="auto" copy so title, subtitle, description, footer actions, and menu affordance mirror naturally.
+- `actions`: The default footer composes the existing Button primitive and keeps action order logical in LTR and RTL.
+
+## 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/card.tsx: Card, CardActions, CardFooter, CardMedia, cardVariants` |
+| `parts` | `Card`, `CardMedia`, `CardFooter`, `CardActions` |
+| `registryDependencies` | `button` |
+| `breakpoints` | `desktop`, `mobile` |
+| `orientations` | `vertical`, `horizontal` |
+| `tokens` | `--bh-bg-accent-green-subtle`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-card-actions-max-width`, `--bh-card-bg`, `--bh-card-border`, `--bh-card-content-padding`, `--bh-card-desktop-content-padding`, `--bh-card-desktop-full-height`, `--bh-card-desktop-horizontal-padding`, `--bh-card-desktop-media-height`, `--bh-card-full-height`, `--bh-card-horizontal-media-width`, `--bh-card-horizontal-min-height`, `--bh-card-horizontal-padding`, `--bh-card-horizontal-width`, `--bh-card-media-height`, `--bh-card-media-overlay`, `--bh-card-mobile-content-padding`, `--bh-card-mobile-full-height`, `--bh-card-mobile-horizontal-padding`, `--bh-card-mobile-media-height`, `--bh-card-more-icon-size`, `--bh-card-more-size`, `--bh-card-radius`, `--bh-card-vertical-width`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-interactive-ghost-hover`, `--bh-radius-3xl-16`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-lg-regular-font-size`, `--bh-text-body-lg-regular-font-weight`, `--bh-text-body-lg-regular-letter-spacing`, `--bh-text-body-lg-regular-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-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--shadow-button-focus` |
+| `types` | `leading-image`, `trailing-image`, `full-image` |
+<!-- registry-contract:end -->

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

@@ -0,0 +1,61 @@
+# Carousel
+
+Carousel is an Embla-backed carousel with content, item, previous, and next controls.
+
+## API
+
+```tsx
+<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
+  <CarouselContent>
+    <CarouselItem>Slide</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Token Contract
+
+Carousel controls use Banhaten Button tokens, spacing, radius, and directional icon behavior.
+
+## RTL
+
+Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
+
+## Accessibility
+
+Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
+
+## Install
+
+```bash
+npx banhaten add carousel
+```
+
+## Examples
+
+Primary registry example: `examples/carousel-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs carousel` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `directionalIconFlip`: Previous and next arrow icons flip in RTL.
+- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
+
+<!-- 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/carousel.tsx: Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, arabicCarouselMessages` |
+| `parts` | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
+| `registryDependencies` | `button` |
+| `features` | `Embla API`, `previous and next controls`, `plugin support` |
+| `orientations` | `horizontal`, `vertical` |
+| `tokens` | `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-7xl-40`, `--bh-space-8xl-48` |
+<!-- registry-contract:end -->