banhaten 0.1.2 → 0.1.3

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

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

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

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

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

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

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

@@ -0,0 +1,85 @@
+# 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 `registry/styles/globals.css` 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.

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

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

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

@@ -0,0 +1,83 @@
+# 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>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `sm`, `xs` |
+| `mode` | `default`, `iconOnly` |
+| `ButtonGroupItem aria-pressed` | `true`, `false` |
+| `ButtonGroupItem disabled` | `boolean` |
+
+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.

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

@@ -0,0 +1,77 @@
+# 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
+```

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

@@ -0,0 +1,78 @@
+# 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
+
+Public exports: `Card`, `CardMedia`, `CardFooter`, `CardActions`.
+
+| 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.