banhaten 0.1.2 → 0.1.3

package/docs/design-system/component-token-consistency-audit.md

@@ -0,0 +1,163 @@
+# Component Token Consistency Audit
+
+Date: 2026-06-13
+
+## Scope
+
+Reviewed the distributable component surface in `registry/components`, expanded component files in `registry/components/expanded`, generated/global token CSS in `registry/styles/globals.css`, token generation and contract scripts, and the playground mirrors.
+
+This audit is focused on whether component color, spacing, sizing, radius, typography, opacity, focus, z-index, shadow, and motion values are driven by Banhaten tokens or documented component aliases.
+
+## Checks Run
+
+- `npm run tokens:check` passed.
+- `npm run registry:check` passed.
+- `npm --prefix playground run test:components` passed with 97 component tests.
+
+Current automated coverage:
+
+- `scripts/generate-token-css.mjs` imports `componentAliasDeclarations()` and emits component aliases into `registry/styles/globals.css`.
+- `scripts/check-token-contract.mjs` verifies those component aliases exist in the generated CSS.
+- `scripts/check-component-token-usage.mjs` scans `registry/components` for raw component-source values.
+- `scripts/check-registry-mirrors.mjs` verifies playground mirrors stay in sync with registry files.
+
+## Current Status
+
+The component library is mostly token-consistent now. The major items from the previous audit have been completed:
+
+- Component aliases are centralized in `scripts/component-token-aliases.mjs`.
+- Generated CSS is current.
+- Component aliases are contract-checked.
+- Registry component source passes the token-usage check.
+- Registry and playground mirrors match.
+- Core focus, z-index, duration, spacing, radius, typography, icon sizing, and common opacity patterns are now tokenized.
+
+The remaining changes are smaller consistency and governance items.
+
+## Required Changes
+
+### P1: Replace Remaining Raw `opacity-0` Utilities
+
+`--bh-opacity-0` already exists, and most components use tokenized opacity. Replace the remaining Tailwind raw zero-opacity utilities with token-backed forms:
+
+- `registry/components/date-picker.tsx`: replace `disabled:opacity-0` with `disabled:opacity-[var(--bh-opacity-0)]`.
+- `registry/components/radio-group.tsx`: replace the hidden input `opacity-0` with `opacity-[var(--bh-opacity-0)]`.
+- `registry/components/textarea.tsx`: replace `after:opacity-0` with `after:opacity-[var(--bh-opacity-0)]`.
+- Sync mirrors through `npm run registry:sync` or the existing mirror workflow.
+
+This is not a visual bug, but it is a token-discipline cleanup.
+
+### P1: Tighten The Token-Usage Check For Zero And Full Opacity
+
+`scripts/check-component-token-usage.mjs` currently flags raw Tailwind opacity only for `50`, `55`, `60`, and `70`. Extend that rule so component source also flags raw `opacity-0` and `opacity-100`, unless an explicit exception is added.
+
+Recommended pattern target:
+
+- Flag: `opacity-0`, `opacity-100`, `disabled:opacity-0`, `after:opacity-0`, grouped/state-prefixed variants.
+- Allow: `opacity-[var(--bh-opacity-0)]`, `opacity-[var(--bh-opacity-100)]`.
+
+### P2: Create A Formal Exception Ledger For Non-Token Literals In Alias Source
+
+Raw values inside `scripts/component-token-aliases.mjs` are no longer leaking into component source, but several are intentional external or Figma-specific values. Document them so future cleanup does not accidentally erase brand/media fidelity.
+
+Document as approved exceptions or promote into a clearer token group:
+
+- Social provider colors: Facebook, Google, LinkedIn, WhatsApp.
+- Radio-card illustrative/payment colors and dimensions.
+- Fractional icon/media geometry such as `28.333px`, `13.333px`, and `6.364px`.
+- Effect/shadow color stops, since the supplied token zips do not include effect tokens.
+- Expanded layout widths and breakpoints for showcase/product-sized components.
+- `--bh-activity-feed-completed-brightness: 0.99`, or replace it with a semantic completed-state color if the visual can be expressed without a brightness filter.
+
+### P2: Keep JS Numeric Offsets Paired With CSS Tokens
+
+Radix APIs require numeric `sideOffset` values, so these cannot directly consume CSS variables:
+
+- `registry/components/select.tsx` uses `SELECT_MENU_SIDE_OFFSET_PX = 4`, mirroring `--bh-select-menu-offset`.
+- `registry/components/tooltip.tsx` uses pointer and pointerless numeric offsets, mirroring tooltip spacing aliases.
+
+The comments are already present. The remaining change is to add these cases to the exception ledger or add a small assertion/test that keeps the JS numbers aligned with their matching aliases.
+
+### P3: Clarify Expanded Component Contract
+
+Expanded components are registered with `status: "expanded"` and have many layout aliases, especially Icon Explorer, Table, Timeline, Steps, Catalog Components, and File Upload. Decide whether these are production component contracts or documentation/showcase layouts.
+
+If production:
+
+- Keep the `--bh-*` layout aliases as public component tokens.
+- Add docs for which layout aliases are safe to override.
+- Add them to any token documentation tables.
+
+If documentation/showcase only:
+
+- Mark them as documentation-level layout tokens.
+- Keep them under the static token check, but document that their large fixed widths are layout constraints rather than primitive spacing tokens.
+
+## Component Matrix
+
+### Core Components
+
+Needs token cleanup:
+
+- Date Picker: raw `disabled:opacity-0`.
+- Radio Group: raw hidden-input `opacity-0`.
+- Textarea: raw focus-ring pseudo-element `after:opacity-0`.
+
+Token-clean under current checks:
+
+- Accordion
+- Alert
+- Attribute
+- Avatar
+- Badge
+- Button
+- Button Group
+- Card
+- Checkbox
+- Divider
+- Input
+- Menu
+- Modal
+- Pagination
+- Progress
+- Progress Slider
+- Radio Card
+- Select
+- Select Content
+- Slider
+- Social Button
+- Spinner
+- Tag
+- Toggle
+- Toolbar
+- Tooltip
+
+### Expanded Components
+
+No direct component-source token violations remain under the current static check. Their remaining work is contract clarity and exception documentation:
+
+- Activity Feed
+- Banner
+- Breadcrumbs
+- Catalog Components Showcase
+- Command Bar
+- Expanded Divider
+- File Upload
+- Icon Explorer
+- Onboarding Step List Item
+- Page Header
+- Slideout
+- Steps
+- Table
+- Tabs
+- Timeline
+
+Approved literal media-query breakpoints remain in CSS `@media` conditions because CSS custom properties are not reliable media-query operands. Geometry inside those media query blocks should continue using Banhaten tokens or component aliases.
+
+## Suggested Implementation Order
+
+1. Replace the three raw `opacity-0` utilities in registry components and sync mirrors.
+2. Extend `scripts/check-component-token-usage.mjs` to catch raw `opacity-0` and `opacity-100`.
+3. Add an exception ledger for alias-source literals and Radix numeric offsets.
+4. Decide and document the expanded-component token contract.
+5. Re-run `npm run tokens:check`, `npm run registry:check`, and `npm --prefix playground run test:components`.

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

@@ -0,0 +1,74 @@
+# Components
+
+Design-system components use semantic props and tokens. Appearance presets may change their visual treatment, but they should not change component APIs.
+
+## Component Catalog
+
+- [Accordion](./accordion.md): Radix-backed disclosure primitive with variants, size scale, animation, and RTL-safe text alignment.
+- [Activity Feed](./activity-feed.md): vertical activity timeline with avatars, status dots, captions or slot content, actions, and RTL support.
+- [Alert](./alert.md): compact and expandable contextual feedback with semantic status colors, action links, close control, and RTL support.
+- [Alert Dialog](./alert-dialog.md): Radix AlertDialog-backed confirmation surface for destructive or consequential actions with semantic intent styling.
+- [Aspect Ratio](./aspect-ratio.md): Radix AspectRatio wrapper for fixed-format media, previews, and product surfaces.
+- [Attribute](./attribute.md): semantic key-value description lists with alignment variants, density, bordered rows, rich value slots, and RTL support.
+- [Autocomplete](./autocomplete.md): searchable combobox field composed from Input, Select menu rows, and Tag chips for single or multiple selection.
+- [Avatar](./avatar.md): user avatar primitive with image, fallback, status, action overlays, groups, and RTL-safe overlap.
+- [Badge](./badge.md): compact status and metadata primitive with semantic colors, icons, dots, flags, counts, and RTL support.
+- [Banner](./banner.md): announcement and notice strip with slim, action, inline-action, input, color, size, content, and RTL variants.
+- [Button](./button.md): semantic action primitive with variants, text and icon sizes, loading composition, link composition, and Arabic/RTL-safe icon behavior.
+- [Button Group](./button-group.md): connected action groups with text and icon-only modes, md/sm/xs sizes, RTL widths, dividers, native interaction styling, and active/disabled states.
+- [Breadcrumbs](./breadcrumbs.md): hierarchical page navigation with slash or chevron separators, raised or inline styles, and RTL support.
+- [Card](./card.md): token-built content surface with image placements, footer actions, desktop/mobile spacing, and RTL-safe copy.
+- [Carousel](./carousel.md): Embla-backed carousel with content, item, previous, and next controls.
+- [Catalog Components](./catalog-components.md): expanded catalog showcase bundle for breadcrumbs, dividers, tags, file upload states, and table previews.
+- [Chart](./chart.md): Recharts wrapper with Banhaten chart tokens, responsive container, tooltip content, and legend content.
+- [Checkbox](./checkbox.md): Radix checkbox primitive plus checkbox-card composition with selected, disabled, hover, and RTL states.
+- [Collapsible](./collapsible.md): Radix Collapsible wrapper for disclosure sections with tokenized trigger and content slots.
+- [Command](./command.md): cmdk-backed command menu with search, groups, shortcuts, separators, and empty state.
+- [Command Bar](./command-bar.md): keyboard-friendly command palette with search, recent items, results, empty states, and RTL support.
+- [Context Menu](./context-menu.md): Radix ContextMenu-backed right-click menu with labels, separators, submenus, checks, radios, and shortcuts.
+- [Date Picker](./date-picker.md): calendar and range-picker suite with presets, open states, triggers, time rows, and RTL support.
+- [Divider](./divider.md): horizontal and vertical separator with solid or dotted rules.
+- [Empty State](./empty-state.md): no-results and first-run state with a neutral icon halo, title, supporting copy, actions, and RTL support.
+- [File Upload](./file-upload.md): drag-and-drop upload target with queued file rows, status feedback, and LTR/RTL size variants.
+- [Field](./field.md): accessible form-row composition for labels, controls, descriptions, errors, grouped fields, and validation state.
+- [Hover Card](./hover-card.md): Radix HoverCard-backed preview surface for rich hover and focus context.
+- [Icons](./icons.md): expanded icon explorer for pack review, semantic mapping, shortlist comparison, and Iconify inspection.
+- [Input](./input.md): text-entry field with labels, helper and error text, add-ons, tags, shortcuts, adornments, and RTL states.
+- [Input Group](./input-group.md): grouped input shell for protocol add-ons, inline actions, prefixes, suffixes, and compact rows.
+- [Input OTP](./input-otp.md): one-time-code field with grouped slots, paste distribution, masked values, hidden form value, and RTL keyboard behavior.
+- [Kbd](./kbd.md): keyboard hint primitive for shortcuts, command rows, and form help text.
+- [Label](./label.md): Radix-backed accessible label primitive with required, optional, tone, disabled, and RTL-safe text behavior.
+- [Menu](./menu.md): Radix DropdownMenu-backed command surface with rich item slots, submenus, progress rows, labels, captions, and RTL layout.
+- [Menubar](./menubar.md): Radix Menubar-backed application menu with keyboard navigation and menu item slots.
+- [Modal](./modal.md): Radix Dialog-backed modal surface with size variants, header/body/footer slots, ConfirmModal guardrails, Button actions, Checkbox opt-out, and RTL support.
+- [Native Select](./native-select.md): tokenized native select field for platform forms, mobile fallback, and lightweight option sets.
+- [Navigation Menu](./navigation-menu.md): Radix NavigationMenu-backed top navigation with trigger, content, link, viewport, and indicator parts.
+- [Onboarding Step List Item](./onboarding-step-list-item.md): vertical progress-list row with finished, active, and inactive states plus RTL support.
+- [Page Header](./page-header.md): page hierarchy, title metadata, actions, description, and local tabs.
+- [Pagination](./pagination.md): numeric, simple, and summary pagination layouts with soft or ghost styling, captions, and RTL labels.
+- [Popover](./popover.md): contextual overlay primitive with click, focus, hover, positioning, arrows, close affordance, and RTL-safe composition.
+- [Progress](./progress.md): read-only progress meter with value fill, labels, helper text, indicator, spinner, and RTL support.
+- [Progress Slider](./progress-slider.md): Radix Slider-based progress control with start-anchored fill, semantic tones, ticks, and RTL keyboard behavior.
+- [Radio Card](./radio-card.md): rich single-choice option card with Figma content types, active/disabled states, and explicit RTL variants.
+- [Radio Group](./radio-group.md): native-input radio group with labels, descriptions, errors, controlled/uncontrolled values, and RTL-safe field rows.
+- [Select](./select.md): Radix Select-backed field and menu item system with item media, selection styles, validation states, and RTL layout.
+- [Resizable](./resizable.md): react-resizable-panels-backed split pane primitive with tokenized resize handle.
+- [Sheet](./sheet.md): Radix Dialog-based edge panel with logical start/end placement, top/bottom placement, size variants, and RTL support.
+- [Sidebar](./sidebar.md): composable app sidebar with collapse state, grouped menu items, logical placement, and sidebar tokens.
+- [Slideout](./slideout.md): desktop and mobile side panel with header/footer actions, scrollable slots, example content, and RTL support.
+- [Scroll Area](./scroll-area.md): Radix ScrollArea wrapper with tokenized viewport, scrollbar, thumb, and corner styling.
+- [Slider](./slider.md): accessible value and range control with single, range, multi-thumb, vertical, ticked, pill, tone, size, disabled, and RTL variants.
+- [Skeleton](./skeleton.md): token-built loading placeholders for text, avatars, actions, forms, cards, lists, tables, shimmer motion, and RTL surfaces.
+- [Social Button](./social-button.md): sign-in action primitive for supported providers with solid, outline, icon-only, focus, and RTL states.
+- [Spinner](./spinner.md): compact steady and dynamic loading spinners with inherited color and tokenized sizing.
+- [Steps](./steps.md): horizontal and vertical progress indicators with icon or number markers, item-level slots/actions, and RTL support.
+- [Table](./table.md): composable table and data-table workflow with selectable rows, sortable headers, search, filters, pagination, row states, RTL support, and reusable cell item variants.
+- [Tabs](./tabs.md): Radix Tabs-backed local navigation with underline, segmented, and rounded treatments across LTR and RTL.
+- [Textarea](./textarea.md): multiline field with labels, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
+- [Timeline](./timeline.md): vertical and horizontal progress/event sequences with default or icon markers, states, dates, captions, and RTL support.
+- [Toast](./toast.md): Sonner-style feedback primitive with semantic intents, action support, Banhaten token styling, and logical RTL placement.
+- [Tag](./tag.md): compact metadata, filter, and removable-selection chip with type, state, size, close-button, and RTL variants.
+- [Toggle](./toggle.md): switch-style boolean control with sm/md sizes, optional handle icons, labeled leading/trailing rows, supporting text, and RTL support.
+- [Toolbar](./toolbar.md): filter and action toolbar with search, select triggers, icon buttons, chips, summaries, desktop/mobile styles, and RTL support.
+- [Tooltip](./tooltip.md): Radix Tooltip-backed help surface with dark/default variants, pointer positions, shortcut/close slots, and RTL support.
+- [Typography](./typography.md): documentation for existing `.bh-text-*` token utility classes.

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

@@ -0,0 +1,51 @@
+# Accordion
+
+Accordion is the disclosure primitive for grouped details, settings, FAQs, and compact content sections. It is backed by Radix Accordion and supports single or multiple expansion, size variants, visual treatments, animation, and RTL-safe copy.
+
+## API
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="billing">
+    <AccordionTrigger>Billing</AccordionTrigger>
+    <AccordionContent>Invoice and payment details.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `default`, `bordered`, `cards`, `soft` | `default` |
+| `size` | `sm`, `default`, `lg` | `default` |
+| `type` | Radix `single`, `multiple` | required |
+| `collapsible` | `boolean` | Radix default |
+
+## Token Contract
+
+Accordion uses Banhaten spacing, border, radius, content, interactive, typography, and animation tokens. Avoid raw colors or pixel values in local variants.
+
+## RTL
+
+Accordion inherits direction from its parent. Triggers and content use logical spacing and `text-start`; text labels use `dir="auto"` where the component renders string copy.
+
+## Accessibility
+
+Radix provides button semantics, `aria-expanded`, roving state, and keyboard behavior. Keep trigger content concise and do not put nested interactive controls inside `AccordionTrigger`.
+
+## Install
+
+```bash
+npx banhaten add accordion
+```
+
+## Examples
+
+Primary registry example: `examples/accordion-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs accordion` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English copy align and punctuate naturally.
+- `spacing`: Uses gap and logical inherited direction rather than physical left/right spacing.

package/docs/design-system/components/activity-feed.md

@@ -0,0 +1,92 @@
+# Activity Feed
+
+`ActivityFeed` renders a vertical timeline of activity items with avatars, status dots, captions or slot content, timestamps, and action buttons.
+
+Figma reference: `Design system 3.0 Copy / ActivityFeed`, component set node `587:19445`.
+
+## Variants
+
+The Figma component defines these top-level variants:
+
+| Direction | Node |
+| --- | --- |
+| LTR | `587:19381` |
+| RTL | `587:19711` |
+
+`ActivityFeedItem` also supports `caption` and `slot` item types through the `type` prop.
+
+## API
+
+```tsx
+<ActivityFeed
+  dir="ltr"
+  items={[
+    {
+      label: "Label",
+      supportText: "Support Text",
+      link: "#Link",
+      caption: "Caption text",
+      timestamp: "Mar 15. 2050",
+      type: "caption",
+    },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `ActivityFeedItemProps[]` | ten caption items |
+| `avatarSrc` | `string` | local Figma avatar asset |
+| `type` | `caption`, `slot` | `caption` |
+| `hasStatus` | `boolean` | `true` |
+| `hasActionButtons` | `boolean` | `true` |
+| `hasTwoActionButtons` | `boolean` | `true` |
+| `showLine` | `boolean` | `true` |
+| `showPaddingBottom` | `boolean` | `true` |
+
+## 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-raised`, `--bh-bg-success-default`
+- Borders: `--bh-border-default`, `--bh-border-subtle`
+- Content: `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`
+- Interactive: `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`
+- Shape: `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-control-default`
+- Space: `--bh-space-xxs-2`, `--bh-space-xs-4`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-xl-12`
+
+## Pixel Rules
+
+- Feed width is `600px`.
+- Items use a `12px` gap between the indicator rail and content.
+- Avatar is `32px` square with a full radius and subtle border.
+- The status dot renders in a `16px` box with a `6px` success fill.
+- Body text is Inter `15px / 24px`; timestamps are `14px / 20px`.
+- Captions use `12px` padding, subtle border, white raised fill, and `4px` radius.
+- Slot content is `76px` high with purple dashed border and subtle purple fill.
+- Actions use `8px` top padding, `8px` button gap, and `36px` tall buttons.
+- The repeated-item default uses a `22px` decorative bottom spacer so ten items fit the `2000px` Figma feed frame.
+- RTL mirrors the avatar rail to the right and right-aligns text content.
+
+## Accessibility
+
+- The feed uses a labelled `section`; provide `ariaLabel` when the surrounding context is not explicit.
+- Status dots and connector lines are decorative. Use item copy or parent-level announcements for meaningful state.
+- Action buttons are real `button` or `a` elements and support `ariaLabel`, `disabled`, `href`, and `onClick`.
+
+## Install
+
+```bash
+npx banhaten add activity-feed
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/activity-feed-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs activity-feed` 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/alert-dialog.md

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

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

@@ -0,0 +1,79 @@
+# 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" />
+<Alert status="success" isExpandable dir="rtl" />
+```
+
+| Prop | Default |
+| --- | --- |
+| `status` | `danger` |
+| `isExpandable` | `false` |
+| `dir` | `ltr` |
+| `title` | localized demo title |
+| `description` | localized demo description |
+| `actions` | localized link actions |
+| `showActions` | `true` |
+| `showCloseButton` | `true` |
+| `onClose` | none |
+
+## Pixel Rules
+
+- Compact alerts are `470px` wide and `56px` tall with `16px` padding.
+- Expandable alerts are `500px` wide with `20px 16px` padding.
+- 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.
+- Expandable content uses `12px` between icon, copy, close, and action rows.
+- 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 `registry/styles/globals.css` 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.
+- `dir` controls visual and reading direction for English and Arabic states.
+
+## 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`: false
+- `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.

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

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

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

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