banhaten 0.5.0 → 0.6.0

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

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

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

@@ -1,56 +1,56 @@
-# 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. The `md` and `lg` icon fallbacks use 18px glyphs in 20px slots; other avatar sizes keep their existing scale. 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.
-
+# 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. The `md` and `lg` icon fallbacks use 18px glyphs in 20px slots; other avatar sizes keep their existing scale. 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
 

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

@@ -1,57 +1,57 @@
-# 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.
-
+# 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
 
@@ -67,6 +67,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `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-bold`, `--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-bold`, `--bh-bg-accent-rose-subtle`, `--bh-bg-accent-sky-base`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-bold`, `--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-on-neutral`, `--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` |
+| `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-bold`, `--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-bold`, `--bh-bg-accent-rose-subtle`, `--bh-bg-accent-sky-base`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-bold`, `--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-border-width-default`, `--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-on-neutral`, `--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 -->

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

@@ -1,89 +1,89 @@
-# 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.
-- The leading glyph is `18px` in a `20px` slot; the close glyph remains `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.
-
+# 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.
+- The leading glyph is `18px` in a `20px` slot; the close glyph remains `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