banhaten 0.5.0 → 0.6.0

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

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

package/docs/design-system/components/app-header.md

@@ -0,0 +1,97 @@
+# App Header
+
+App Header is the workspace bar above page content in a sidebar shell. It holds the reader's location at the start and workspace tools such as search, notifications, help, or language at the end.
+
+Use Page Header inside the page for the page title, description, and page actions. Use Toolbar for controls that act on a selection or a document.
+
+## API
+
+Put Breadcrumbs or a short location label in `AppHeaderStart`, and search and actions in `AppHeaderEnd`. Give the nested Input and every icon-only action an accessible name.
+
+```tsx
+<AppHeader>
+  <AppHeaderStart>
+    <Breadcrumbs
+      aria-label="Breadcrumb"
+      items={[{ label: "Recruiting", href: "#overview" }, { label: "Overview" }]}
+      size="sm"
+    />
+  </AppHeaderStart>
+  <AppHeaderEnd>
+    <AppHeaderSearch onSubmit={search}>
+      <Input
+        aria-label="Search workspace"
+        hasHelperText={false}
+        hasLabel={false}
+        placeholder="Search workspace"
+        type="search"
+      />
+    </AppHeaderSearch>
+    <AppHeaderAction aria-label="Notifications" icon={<BellIcon />} />
+    <AppHeaderAction aria-label="EN, switch language to Arabic" size="sm">
+      EN
+    </AppHeaderAction>
+  </AppHeaderEnd>
+</AppHeader>
+```
+
+The bar is 72px tall with 24px inline padding, a 24px gap between items, and a subtle bottom border inside that height. `AppHeaderStart` fills the free space, so the end group stays on the content edge. When space runs short, the start keeps at least 160px and the search narrows first. The bar does not wrap, so on phone widths hide the search or render a compact mobile bar.
+
+`AppHeaderAction` is flush: at rest it takes only the space of its icon or label, so it lines up with the design. Padding and a matching negative margin give it a 40px pointer target and hover surface without moving it.
+
+- Icon-only: pass `icon` and `aria-label`. The icon is 24px.
+- `size="md"`, the default: a text action in body-md medium.
+- `size="sm"`: a quieter text action in body-sm medium subtle content. It reserves 32px and aligns its label to the end edge, so a language code can change without moving the controls before it.
+- `asChild`: renders the action styles on a link.
+
+`AppHeaderSearch` is a form with the search landmark role. It sets the nested Input to the 320px search width.
+
+Breadcrumbs inside App Header show their current item in the same subtle color as the rest of the trail. Use `size="sm"` so the trail matches the 14/20 location text.
+
+## Install
+
+```bash
+npx banhaten add app-header
+```
+
+Add Breadcrumbs and Input separately when the header uses them.
+
+## Examples
+
+Primary registry example: `examples/app-header-demo.tsx`.
+
+## Token Contract
+
+App Header owns `--bh-app-header-*` tokens for its height, inline padding, gaps, start minimum width, background, border, location color, search width, icon size, and action content, hover, radius, and pointer-target inset. It sets `--bh-breadcrumbs-current-content` to the location color and `--bh-input-width` to fill the search landmark. Do not replace these values with local literals.
+
+Covered source file: `components/app-header.tsx`.
+
+## RTL Rules
+
+- The header inherits document direction.
+- Start and End regions, inline padding, and the reserved end-aligned width of small text actions use logical layout and mirror without alternate markup.
+- Breadcrumb separators and labels follow the Breadcrumbs RTL contract.
+
+## Accessibility
+
+The root is a `header` element. `AppHeaderSearch` is a search landmark and needs a labeled Input. Icon-only actions require `aria-label`. When a text action has an `aria-label`, start it with the visible label, such as “EN, switch language to Arabic”. Actions keep a 40px pointer target and a visible focus ring.
+
+<!-- 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/app-header.tsx: AppHeader, AppHeaderAction, AppHeaderEnd, AppHeaderSearch, AppHeaderStart` |
+| `parts` | `AppHeader`, `AppHeaderStart`, `AppHeaderEnd`, `AppHeaderSearch`, `AppHeaderAction` |
+| `registryDependencies` | None |
+| `props.AppHeaderAction.icon` | `ReactNode; default null; Icon content. Without children the action is icon-only and needs aria-label; the icon occupies 24px and the pointer target is 40px.` |
+| `props.AppHeaderAction.size` | `"sm" \| "md"; default "md"; md uses body-md medium default content. sm uses body-sm medium subtle content and reserves 32px at the end edge, so a short label such as a language code can change without moving earlier controls.` |
+| `props.AppHeaderAction.asChild` | `boolean; default false; Renders the action styles on the child element, such as a link.` |
+| `props.AppHeaderSearch.role` | `string; default "search"; Search landmark role on the wrapping form. Nest an Input with an accessible name; the header sets its width to the 320px search token.` |
+| `features` | `72px bar with 24px inline padding, a 24px item gap, and a subtle bottom border`, `flexible start region for Breadcrumbs or a location label in body-sm medium subtle content`, `Breadcrumbs inside the header render their current item in the location color`, `search landmark that sizes a nested Input to 320px`, `flush icon actions with a 24px footprint and a 40px target`, `flush text actions in md and sm sizes`, `logical layout that mirrors in RTL` |
+| `sizes` | `md`, `sm` |
+| `tokens` | `--bh-app-header-action-bg-hover`, `--bh-app-header-action-content`, `--bh-app-header-action-hit-inset`, `--bh-app-header-action-radius`, `--bh-app-header-action-sm-content`, `--bh-app-header-action-sm-min-width`, `--bh-app-header-bg`, `--bh-app-header-border`, `--bh-app-header-gap`, `--bh-app-header-height`, `--bh-app-header-icon-size`, `--bh-app-header-location-content`, `--bh-app-header-padding-x`, `--bh-app-header-search-width`, `--bh-app-header-start-gap`, `--bh-app-header-start-min-width`, `--bh-border-width-default`, `--bh-breadcrumbs-current-content`, `--bh-content-default`, `--bh-content-disabled`, `--bh-input-width`, `--bh-space-xs-4`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--elevation-button-focus` |
+<!-- registry-contract:end -->

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

@@ -1,48 +1,48 @@
-# 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.
-
+# Aspect Ratio
+
+Aspect Ratio wraps Radix AspectRatio for fixed-format media, screenshots, and preview surfaces.
+
+## API
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/preview.png" alt="Preview" />
+</AspectRatio>
+```
+
+| Prop | Values |
+| --- | --- |
+| `ratio` | any positive number |
+
+## Token Contract
+
+Aspect Ratio uses Banhaten neutral background and radius tokens by default.
+
+## RTL
+
+Aspect Ratio is direction-neutral.
+
+## Accessibility
+
+Provide accessible names for media rendered inside the ratio box.
+
+## Install
+
+```bash
+npx banhaten add aspect-ratio
+```
+
+## Examples
+
+Primary registry example: `examples/aspect-ratio-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs aspect-ratio` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `geometry`: Aspect Ratio controls media geometry and does not alter text direction.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,91 +1,102 @@
-# 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.
-
+# 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` (`176px` at comfortable density) |
+| `AttributeItem fullSpan` | `boolean`, useful in `two-column` layouts |
+| `AttributeItem truncate` | `boolean` |
+
+## Comfortable density
+
+`density="comfortable"` is the label/value row of a detail card inside an app shell. Rows have no block padding and sit `16px` apart, so the list follows its card's own gap. The label is body-sm (`14px / 20px`) in content/subtle, in a `176px` column (`--bh-attribute-comfortable-label-width`), and the value is body-md medium, `16px` after it. Label and value align to the top of the row.
+
+```tsx
+<AttributeList density="comfortable">
+  <AttributeItem label="Requester">Mohamed Ali</AttributeItem>
+  <AttributeItem label="Start date">1 December 2026</AttributeItem>
+</AttributeList>
+```
+
+## Composition
+
+Values are open React slots. Compose existing primitives for status badges, copy buttons, file rows, progress bars, skeleton bars, links, and custom details.
+
+```tsx
+<AttributeList layout="end" dividers>
+  <AttributeItem label="Subscription">
+    <Badge color="green" type="dot">Active</Badge>
+  </AttributeItem>
+  <AttributeItem label="API key" truncate>
+    sk_live_************1234
+    <Button aria-label="Copy API key" size="icon-xs" variant="outline">
+      <CopyIcon />
+    </Button>
+  </AttributeItem>
+</AttributeList>
+```
+
+## RTL
+
+Attribute inherits direction from any parent. The component uses logical text alignment and `dir="auto"` wrappers for string labels and values, so Arabic and English content can sit in the same card without manual left/right classes.
+
+## Install
+
+```bash
+npx banhaten add attribute
+```
+
+## Examples
+
+Primary registry example: `examples/attribute-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs attribute` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/attribute.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Uses logical text alignment and inherited direction so label and value columns mirror naturally.
+- `textDirection`: String labels and values use dir="auto" wrappers while custom slots can control their own direction.
+- `composition`: Rows accept ReactNode values, so badges, buttons, links, progress bars, skeletons, files, and custom content can be composed from existing Banhaten primitives.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -97,7 +108,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/attribute.tsx: AttributeCard, AttributeHeader, AttributeItem, AttributeLabel, AttributeList, AttributeValue, attributeCardVariants, attributeHeaderVariants, attributeItemVariants, attributeLabelVariants, attributeListVariants, attributeValueVariants` |
 | `parts` | `AttributeCard`, `AttributeHeader`, `AttributeList`, `AttributeItem`, `AttributeLabel`, `AttributeValue` |
 | `registryDependencies` | None |
+| `props.AttributeList.density` | `"compact" \| "default" \| "comfortable"; default "default"; compact and default set the row padding (8px, 16px). comfortable is the app-shell detail row: no row padding, rows 16px apart, a 14/20 label in a 176px column and 16px before the value.` |
 | `densities` | `compact`, `default`, `comfortable` |
 | `layouts` | `inline`, `end`, `stacked`, `two-column` |
-| `tokens` | `--bh-attribute-header-icon-size`, `--bh-attribute-header-icon-size-lg`, `--bh-attribute-label-width`, `--bh-bg-default`, `--bh-bg-neutral-soft`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-medium-font-size`, `--bh-text-heading-sm-medium-font-weight`, `--bh-text-heading-sm-medium-letter-spacing`, `--bh-text-heading-sm-medium-line-height` |
+| `tokens` | `--bh-attribute-comfortable-label-width`, `--bh-attribute-header-icon-size`, `--bh-attribute-header-icon-size-lg`, `--bh-attribute-label-width`, `--bh-bg-default`, `--bh-bg-neutral-soft`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--bh-text-heading-sm-medium-font-size`, `--bh-text-heading-sm-medium-font-weight`, `--bh-text-heading-sm-medium-letter-spacing`, `--bh-text-heading-sm-medium-line-height` |
 <!-- registry-contract:end -->