banhaten 0.2.0 → 0.4.0

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

@@ -0,0 +1,73 @@
+# Activity Heatmap
+
+`ActivityHeatmap` visualizes activity as seven-day week columns with five intensity levels. It is domain-neutral: contribution totals, period controls, headings, and product-specific copy belong to the surrounding composition.
+
+## API
+
+```tsx
+import {
+  ActivityHeatmap,
+  type ActivityHeatmapItem,
+} from "@/components/ui/expanded/ActivityHeatmap"
+
+const items: ActivityHeatmapItem[] = activity.map((level, index) => ({
+  id: String(index),
+  label: `Day ${index + 1}, activity level ${level} of 4`,
+  level,
+}))
+
+<ActivityHeatmap
+  ariaLabel="Weekly activity over the last 39 weeks"
+  items={items}
+/>
+```
+
+Items are supplied in column-major order: the first seven values make the first week, the next seven make the second week, and so on. `level` accepts `0`, `1`, `2`, `3`, or `4`.
+
+## Token Contract
+
+The component introduces no new design tokens and contains no raw visual values. Its complete visual contract is composed from existing Banhaten tokens:
+
+- Cell size: `--bh-space-3xl-16`
+- Gap: `--bh-space-xs-4`
+- Radius: `--bh-radius-sm-4`
+- Empty level: `--bh-bg-neutral-medium`
+- Activity levels: `--bh-bg-accent-purple-subtle`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-purple-default`, `--bh-content-accent-purple-strong`
+
+## RTL Rules
+
+Set `dir="rtl"` or inherit an RTL direction boundary to place the first supplied week at the logical start edge. Item order is never mutated in JavaScript.
+
+## Accessibility
+
+The heatmap exposes one image-style accessible summary through `ariaLabel`, avoiding hundreds of repetitive focus stops. Give each item a concise `label` to provide a native pointer tooltip. If users must inspect or act on individual days, pair the heatmap with an accessible table or list rather than turning every cell into a button.
+
+## Install
+
+```bash
+npx banhaten add activity-heatmap
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/activity-heatmap-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs activity-heatmap` to inspect source files, installation, and examples.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/expanded/ActivityHeatmap.tsx: ActivityHeatmap` |
+| `parts` | `ActivityHeatmap` |
+| `registryDependencies` | None |
+| `props.ariaLabel` | `string; default "Activity heatmap"; Accessible summary for the full visualized period.` |
+| `props.dir` | `ltr \| rtl; default "inherited"; Places the first activity column at the logical start edge.` |
+| `props.items` | `readonly ActivityHeatmapItem[]; default "[]"; Column-major cells grouped into seven-day weeks, each with a level from zero through four.` |
+| `states` | `level-0`, `level-1`, `level-2`, `level-3`, `level-4` |
+| `tokens` | `--bh-bg-accent-purple-default`, `--bh-bg-accent-purple-soft`, `--bh-bg-accent-purple-subtle`, `--bh-bg-neutral-medium`, `--bh-content-accent-purple-strong`, `--bh-content-default`, `--bh-font-family`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-xs-4`, `--shadow-component-focus-ring` |
+<!-- registry-contract:end -->

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

@@ -83,5 +83,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `alert-dialog semantics`, `cancel focus pattern`, `safe cancel action`, `destructive action`, `semantic intent icon` |
 | `intents` | `default`, `warning`, `danger` |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-alert-dialog-border`, `--bh-alert-dialog-width`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-component-default`, `--shadow-modal` |
+| `tokens` | `--bh-alert-dialog-border`, `--bh-alert-dialog-width`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-2xl`, `--shadow-modal` |
 <!-- registry-contract:end -->

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

@@ -47,7 +47,7 @@ The implementation covers the Alert matrix from Figma:
 - 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 icons and close controls are `20px`; the close glyph is `16px`.
+- 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.
@@ -105,7 +105,7 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | --- | --- |
 | `supportedExports` | `components/alert.tsx: Alert, alertVariants, arabicAlertMessages` |
 | `parts` | `Alert` |
-| `registryDependencies` | None |
-| `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-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-opacity-80`, `--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`, `--shadow-button-focus` |
+| `registryDependencies` | `button` |
+| `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/attribute.md

@@ -99,5 +99,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `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-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-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` |
 <!-- registry-contract:end -->

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

@@ -23,7 +23,7 @@ Avatar represents people, accounts, teams, and system actors. It supports images
 
 ## 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.
+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
 
@@ -66,5 +66,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `forms` | `circular`, `rounded` |
 | `sizes` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` |
 | `statusColors` | `offline`, `busy`, `blocked`, `available`, `away` |
-| `tokens` | `--bh-avatar-action-icon-size`, `--bh-avatar-action-icon-size-2xl`, `--bh-avatar-action-icon-size-3xl`, `--bh-avatar-action-icon-size-4xl`, `--bh-avatar-action-icon-size-large`, `--bh-avatar-action-icon-size-medium`, `--bh-avatar-action-icon-size-small`, `--bh-avatar-action-icon-size-tiny`, `--bh-avatar-action-icon-size-xlarge`, `--bh-avatar-action-icon-size-xsmall`, `--bh-avatar-action-size`, `--bh-avatar-action-size-2xl`, `--bh-avatar-action-size-3xl`, `--bh-avatar-action-size-4xl`, `--bh-avatar-action-size-large`, `--bh-avatar-action-size-medium`, `--bh-avatar-action-size-small`, `--bh-avatar-action-size-tiny`, `--bh-avatar-action-size-xlarge`, `--bh-avatar-action-size-xsmall`, `--bh-avatar-fallback-font-size-2xl`, `--bh-avatar-fallback-font-size-2xs`, `--bh-avatar-fallback-font-size-3xl`, `--bh-avatar-fallback-font-size-4xl`, `--bh-avatar-fallback-font-size-lg`, `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-sm`, `--bh-avatar-fallback-font-size-xl`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-fallback-size`, `--bh-avatar-icon-size`, `--bh-avatar-icon-size-2xl`, `--bh-avatar-icon-size-2xs`, `--bh-avatar-icon-size-3xl`, `--bh-avatar-icon-size-4xl`, `--bh-avatar-icon-size-lg`, `--bh-avatar-icon-size-md`, `--bh-avatar-icon-size-sm`, `--bh-avatar-icon-size-xl`, `--bh-avatar-icon-size-xs`, `--bh-avatar-radius`, `--bh-avatar-size`, `--bh-avatar-size-2xl`, `--bh-avatar-size-2xs`, `--bh-avatar-size-3xl`, `--bh-avatar-size-4xl`, `--bh-avatar-size-lg`, `--bh-avatar-size-md`, `--bh-avatar-size-sm`, `--bh-avatar-size-xl`, `--bh-avatar-size-xs`, `--bh-avatar-status-ring`, `--bh-avatar-status-ring-default`, `--bh-avatar-status-ring-thin`, `--bh-avatar-status-size`, `--bh-avatar-status-size-large`, `--bh-avatar-status-size-medium`, `--bh-avatar-status-size-small`, `--bh-avatar-status-size-tiny`, `--bh-avatar-status-size-xlarge`, `--bh-avatar-status-size-xsmall`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-subtle`, `--bh-bg-success-default`, `--bh-border-width-default`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-weight-semibold`, `--bh-icon-stroke-210`, `--bh-icon-stroke-240`, `--bh-icon-stroke-260`, `--bh-icon-stroke-280`, `--bh-interactive-brand-default`, `--bh-interactive-danger-default`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-sm-medium-font-size`, `--shadow-avatar-badge` |
+| `tokens` | `--bh-avatar-action-icon-size`, `--bh-avatar-action-icon-size-2xl`, `--bh-avatar-action-icon-size-3xl`, `--bh-avatar-action-icon-size-4xl`, `--bh-avatar-action-icon-size-large`, `--bh-avatar-action-icon-size-medium`, `--bh-avatar-action-icon-size-small`, `--bh-avatar-action-icon-size-tiny`, `--bh-avatar-action-icon-size-xlarge`, `--bh-avatar-action-icon-size-xsmall`, `--bh-avatar-action-size`, `--bh-avatar-action-size-2xl`, `--bh-avatar-action-size-3xl`, `--bh-avatar-action-size-4xl`, `--bh-avatar-action-size-large`, `--bh-avatar-action-size-medium`, `--bh-avatar-action-size-small`, `--bh-avatar-action-size-tiny`, `--bh-avatar-action-size-xlarge`, `--bh-avatar-action-size-xsmall`, `--bh-avatar-fallback-font-size-2xl`, `--bh-avatar-fallback-font-size-2xs`, `--bh-avatar-fallback-font-size-3xl`, `--bh-avatar-fallback-font-size-4xl`, `--bh-avatar-fallback-font-size-lg`, `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-sm`, `--bh-avatar-fallback-font-size-xl`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-fallback-size`, `--bh-avatar-icon-size`, `--bh-avatar-icon-size-2xl`, `--bh-avatar-icon-size-2xs`, `--bh-avatar-icon-size-3xl`, `--bh-avatar-icon-size-4xl`, `--bh-avatar-icon-size-lg`, `--bh-avatar-icon-size-md`, `--bh-avatar-icon-size-sm`, `--bh-avatar-icon-size-xl`, `--bh-avatar-icon-size-xs`, `--bh-avatar-icon-slot-size`, `--bh-avatar-radius`, `--bh-avatar-size`, `--bh-avatar-size-2xl`, `--bh-avatar-size-2xs`, `--bh-avatar-size-3xl`, `--bh-avatar-size-4xl`, `--bh-avatar-size-lg`, `--bh-avatar-size-md`, `--bh-avatar-size-sm`, `--bh-avatar-size-xl`, `--bh-avatar-size-xs`, `--bh-avatar-status-ring`, `--bh-avatar-status-ring-default`, `--bh-avatar-status-ring-thin`, `--bh-avatar-status-size`, `--bh-avatar-status-size-large`, `--bh-avatar-status-size-medium`, `--bh-avatar-status-size-small`, `--bh-avatar-status-size-tiny`, `--bh-avatar-status-size-xlarge`, `--bh-avatar-status-size-xsmall`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-subtle`, `--bh-bg-success-default`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-on-brand`, `--bh-font-weight-semibold`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-210`, `--bh-icon-stroke-240`, `--bh-icon-stroke-260`, `--bh-icon-stroke-280`, `--bh-interactive-brand-default`, `--bh-interactive-danger-default`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-sm-medium-font-size`, `--shadow-avatar-badge` |
 <!-- registry-contract:end -->

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

@@ -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-default`, `--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-default`, `--bh-bg-accent-rose-subtle`, `--bh-bg-accent-sky-base`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-default`, `--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-subtle`, `--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-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

@@ -46,7 +46,7 @@ The implementation covers the Banner matrix from Figma:
 - 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`.
+- 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.
@@ -95,5 +95,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/Banner.tsx: Banner` |
 | `parts` | `Banner` |
 | `registryDependencies` | `button`, `input` |
-| `tokens` | `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-muted`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-inverse`, `--bh-content-link`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-210`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-font-weight`, `--bh-text-body-lg-medium-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--shadow-component-default` |
+| `modes` | `slim`, `single-action-inline`, `single-action`, `input` |
+| `sizes` | `floating`, `full-width` |
+| `states` | `title`, `title-description` |
+| `tokens` | `--bh-bg-brand-bold`, `--bh-bg-brand-soft`, `--bh-bg-muted`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-link`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-210`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-radius-xl-10`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-font-weight`, `--bh-text-body-lg-medium-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--shadow-xl` |
+| `variants` | `brand`, `grey`, `brand-light` |
 <!-- registry-contract:end -->

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

@@ -55,7 +55,7 @@ type BreadcrumbsProps = {
 - 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.
+- Item glyphs are 18px square inside 20px slots.
 - 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.
@@ -184,5 +184,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/Breadcrumbs.tsx: BreadcrumbFolderIcon, BreadcrumbHomeIcon, Breadcrumbs` |
 | `parts` | `Breadcrumbs` |
 | `registryDependencies` | None |
-| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-stroke-190`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height` |
+| `modes` | `text`, `icon-only`, `slash`, `chevron` |
+| `states` | `link`, `current`, `overflow` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-190`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height` |
+| `variants` | `default`, `raised` |
 <!-- registry-contract:end -->

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

@@ -65,7 +65,7 @@ Interaction styling is applied through native CSS pseudo states: `:hover`, `:act
 | `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.
+Text buttons use the design-system button typography tokens. Default glyphs are 18px inside preserved 20px slots. Icon-only buttons require an accessible label.
 
 ## Install
 
@@ -109,9 +109,10 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `props.density` | `"compact" \| "default" \| "comfortable"; default "comfortable"; Preferred cross-component sizing contract. Maps to legacy xs, sm, or md group sizes.` |
 | `props.itemWidth` | `"fixed" \| "content"; default "fixed"; Uses the reviewed fixed matrix widths or lets each text item hug its content.` |
 | `densities` | `compact`, `default`, `comfortable` |
+| `features` | `contained horizontal scrolling for narrow containers`, `connected dividers remain intact while scrolling` |
 | `modes` | `default`, `iconOnly` |
 | `selectionTypes` | `single`, `multiple` |
 | `sizes` | `md`, `sm`, `xs` |
-| `tokens` | `--bh-border-width-default`, `--bh-button-group-bg`, `--bh-button-group-border`, `--bh-button-group-content`, `--bh-button-group-content-active`, `--bh-button-group-content-disabled`, `--bh-button-group-divider`, `--bh-button-group-icon-size`, `--bh-button-group-item-active-bg`, `--bh-button-group-item-bg`, `--bh-button-group-item-disabled-bg`, `--bh-button-group-item-hover-bg`, `--bh-button-group-item-pressed-bg`, `--bh-button-group-label-padding-x`, `--bh-button-group-md-gap`, `--bh-button-group-md-height`, `--bh-button-group-md-icon-padding-x`, `--bh-button-group-md-item-rtl-width`, `--bh-button-group-md-item-width`, `--bh-button-group-md-padding-x`, `--bh-button-group-radius`, `--bh-button-group-sm-gap`, `--bh-button-group-sm-height`, `--bh-button-group-sm-icon-padding-x`, `--bh-button-group-sm-item-rtl-width`, `--bh-button-group-sm-item-width`, `--bh-button-group-sm-padding-x`, `--bh-button-group-xs-gap`, `--bh-button-group-xs-height`, `--bh-button-group-xs-icon-padding-x`, `--bh-button-group-xs-item-rtl-width`, `--bh-button-group-xs-item-width`, `--bh-button-group-xs-padding-x`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--bh-z-raised`, `--shadow-button-group`, `--shadow-button-group-focus`, `--shadow-component-default` |
+| `tokens` | `--bh-border-width-default`, `--bh-button-group-bg`, `--bh-button-group-border`, `--bh-button-group-content`, `--bh-button-group-content-active`, `--bh-button-group-content-disabled`, `--bh-button-group-divider`, `--bh-button-group-icon-size`, `--bh-button-group-icon-slot-size`, `--bh-button-group-item-active-bg`, `--bh-button-group-item-bg`, `--bh-button-group-item-disabled-bg`, `--bh-button-group-item-hover-bg`, `--bh-button-group-item-pressed-bg`, `--bh-button-group-label-padding-x`, `--bh-button-group-md-gap`, `--bh-button-group-md-height`, `--bh-button-group-md-icon-padding-x`, `--bh-button-group-md-item-rtl-width`, `--bh-button-group-md-item-width`, `--bh-button-group-md-padding-x`, `--bh-button-group-radius`, `--bh-button-group-sm-gap`, `--bh-button-group-sm-height`, `--bh-button-group-sm-icon-padding-x`, `--bh-button-group-sm-item-rtl-width`, `--bh-button-group-sm-item-width`, `--bh-button-group-sm-padding-x`, `--bh-button-group-xs-gap`, `--bh-button-group-xs-height`, `--bh-button-group-xs-icon-padding-x`, `--bh-button-group-xs-item-rtl-width`, `--bh-button-group-xs-item-width`, `--bh-button-group-xs-padding-x`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--bh-z-raised`, `--shadow-button-group`, `--shadow-button-group-focus`, `--shadow-component-default` |
 | `widths` | `fixed`, `content` |
 <!-- registry-contract:end -->

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

@@ -54,7 +54,7 @@ Button consumes semantic interaction, content, border, radius, typography, spaci
 - 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`
+- Icon rhythm: `--bh-button-icon-size` is an 18px glyph inside `--bh-button-icon-slot-size` at 20px; `--bh-button-icon-offset` and `--bh-button-label-padding-x` preserve optical alignment.
 - Effects: `--shadow-button-raised`, `--shadow-button-secondary`, `--shadow-button-soft`, `--shadow-button-focus`, `--shadow-button-danger-focus`
 
 ## RTL Rules
@@ -90,6 +90,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `props.density` | `"compact" \| "default" \| "comfortable"; default "comfortable"; Preferred cross-component sizing contract. Maps to legacy xs, sm, or default sizes while preserving icon-only sizing.` |
 | `densities` | `compact`, `default`, `comfortable` |
 | `sizes` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` |
-| `tokens` | `--bh-bg-always-white`, `--bh-bg-success-bold`, `--bh-bg-success-default`, `--bh-bg-success-strong`, `--bh-bg-warning-bold`, `--bh-bg-warning-default`, `--bh-bg-warning-strong`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-label-padding-x`, `--bh-button-lg-height`, `--bh-button-lg-padding-x`, `--bh-button-lg-padding-y`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-secondary-border`, `--bh-button-secondary-focus-border`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xl-height`, `--bh-button-xl-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-brand`, `--bh-content-on-color`, `--bh-content-on-light`, `--bh-control-default`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-danger-default`, `--bh-interactive-danger-disabled`, `--bh-interactive-danger-hover`, `--bh-interactive-danger-pressed`, `--bh-interactive-danger-soft-default`, `--bh-interactive-danger-soft-disabled`, `--bh-interactive-danger-soft-hover`, `--bh-interactive-danger-soft-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-interactive-secondary-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-opacity-30`, `--bh-space-none`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-secondary`, `--shadow-button-secondary-focus`, `--shadow-button-soft` |
+| `tokens` | `--bh-bg-always-white`, `--bh-border-brand-strong`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-width-default`, `--bh-button-gap`, `--bh-button-gap-xs`, `--bh-button-icon-offset`, `--bh-button-icon-size`, `--bh-button-icon-slot-size`, `--bh-button-label-padding-x`, `--bh-button-lg-height`, `--bh-button-lg-padding-x`, `--bh-button-lg-padding-y`, `--bh-button-md-height`, `--bh-button-md-padding-x`, `--bh-button-secondary-border`, `--bh-button-secondary-focus-border`, `--bh-button-sm-height`, `--bh-button-sm-padding-x`, `--bh-button-sm-padding-y`, `--bh-button-xl-height`, `--bh-button-xl-padding-y`, `--bh-button-xs-height`, `--bh-button-xs-padding-x`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-brand`, `--bh-content-on-color`, `--bh-content-on-light`, `--bh-content-on-success`, `--bh-content-on-warning`, `--bh-control-default`, `--bh-interactive-brand-default`, `--bh-interactive-brand-disabled`, `--bh-interactive-brand-hover`, `--bh-interactive-brand-pressed`, `--bh-interactive-danger-default`, `--bh-interactive-danger-disabled`, `--bh-interactive-danger-hover`, `--bh-interactive-danger-pressed`, `--bh-interactive-danger-soft-default`, `--bh-interactive-danger-soft-disabled`, `--bh-interactive-danger-soft-hover`, `--bh-interactive-danger-soft-pressed`, `--bh-interactive-ghost-default`, `--bh-interactive-ghost-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-ghost-pressed`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-disabled`, `--bh-interactive-outlined-hover`, `--bh-interactive-outlined-pressed`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-interactive-secondary-pressed`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-interactive-soft-hover`, `--bh-interactive-soft-pressed`, `--bh-interactive-success-default`, `--bh-interactive-success-hover`, `--bh-interactive-success-pressed`, `--bh-interactive-warning-default`, `--bh-interactive-warning-hover`, `--bh-interactive-warning-pressed`, `--bh-opacity-30`, `--bh-space-none`, `--bh-text-button-font-size`, `--bh-text-button-font-weight`, `--bh-text-button-letter-spacing`, `--bh-text-button-line-height`, `--shadow-button-danger-focus`, `--shadow-button-focus`, `--shadow-button-raised`, `--shadow-button-secondary`, `--shadow-button-secondary-focus`, `--shadow-button-soft` |
 | `variants` | `default`, `secondary`, `soft`, `outline`, `ghost`, `ghost-primary`, `danger`, `soft-danger`, `white` |
 <!-- registry-contract:end -->

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

@@ -2,6 +2,14 @@
 
 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.
 
+Use `CardSurface` when a product-specific composition needs the owned Banhaten card surface while supplying its own internal layout.
+
+```tsx
+<CardSurface>
+  <h3>Custom metric content</h3>
+</CardSurface>
+```
+
 ## Install
 
 ```bash
@@ -48,7 +56,7 @@ Card uses logical spacing, inherited direction, and `dir="auto"` copy wrappers s
 
 ## API
 
-Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `cardVariants`.
+Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `CardSurface`, `cardVariants`.
 
 | Contract | Values |
 | --- | --- |
@@ -85,8 +93,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/card.tsx: Card, CardActions, CardFooter, CardMedia, cardVariants` |
-| `parts` | `Card`, `CardMedia`, `CardFooter`, `CardActions` |
+| `supportedExports` | `components/card.tsx: Card, CardActions, CardFooter, CardMedia, CardSurface, cardVariants` |
+| `parts` | `Card`, `CardSurface`, `CardMedia`, `CardFooter`, `CardActions` |
 | `registryDependencies` | `button` |
 | `breakpoints` | `desktop`, `mobile` |
 | `orientations` | `vertical`, `horizontal` |

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

@@ -55,5 +55,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/CatalogComponentsShowcase.tsx: CatalogComponentsShowcase`, `components/expanded/CatalogDivider.tsx: CatalogContentDivider, CatalogDivider` |
 | `parts` | `CatalogContentDivider`, `CatalogDivider`, `CatalogComponentsShowcase` |
 | `registryDependencies` | `breadcrumbs`, `button`, `file-upload`, `table`, `tag` |
+| `modes` | `showcase`, `divider`, `content-divider` |
+| `states` | `label`, `action`, `disabled-action` |
 | `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-catalog-file-grid-max`, `--bh-catalog-file-grid-min`, `--bh-catalog-file-preview-max`, `--bh-catalog-file-preview-min`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-opacity-65`, `--bh-radius-lg-8`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-line-height`, `--shadow-component-default` |
+| `variants` | `solid-divider`, `dotted-divider` |
 <!-- registry-contract:end -->

package/docs/design-system/components/date-picker.md

@@ -16,6 +16,8 @@ npx banhaten add date-picker
 - `DateRangePicker`: trigger plus range calendar surface.
 - `DatePickerTrigger`: standalone tokenized trigger.
 
+Trigger and previous/next navigation glyphs are 18px inside 20px slots. Smaller title chevrons and calendar indicators keep their component-specific sizes.
+
 ## Example
 
 ```tsx
@@ -93,5 +95,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `densities` | `compact`, `default`, `comfortable` |
 | `modes` | `single-calendar`, `single-month-year`, `double-calendar`, `double-calendar-with-presets`, `single-range-calendar`, `date-picker`, `date-range-picker` |
 | `states` | `open`, `closed` |
-| `tokens` | `--bh-bg-brand-default`, `--bh-bg-brand-subtle`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-raised`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-button-sm-height`, `--bh-button-xs-height`, `--bh-content-brand-default`, `--bh-content-brand-strong`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-date-day-cell-height`, `--bh-date-event-dot-offset-bottom`, `--bh-date-event-dot-size`, `--bh-date-list-item-height`, `--bh-date-month-year-item-height`, `--bh-date-month-year-list-top`, `--bh-date-month-year-list-width`, `--bh-date-month-year-spacer-height`, `--bh-date-nav-button-size`, `--bh-date-nav-icon-size`, `--bh-date-picker-width`, `--bh-date-presets-width`, `--bh-date-range-month-width`, `--bh-date-range-surface-max-width`, `--bh-date-surface-border`, `--bh-date-surface-width-calendar`, `--bh-date-surface-width-picker`, `--bh-date-time-input-min-height`, `--bh-date-title-chevron-size`, `--bh-date-title-height`, `--bh-date-trigger-border`, `--bh-date-trigger-height`, `--bh-date-trigger-icon-size`, `--bh-date-trigger-shadow`, `--bh-date-trigger-width`, `--bh-icon-stroke-180`, `--bh-interactive-ghost-hover`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-soft-default`, `--bh-interactive-soft-hover`, `--bh-opacity-0`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--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-z-raised`, `--shadow-button-focus`, `--shadow-component-default`, `--shadow-date-month-year-list`, `--shadow-date-surface`, `--shadow-date-time-input`, `--shadow-input-focus-ring` |
+| `tokens` | `--bh-bg-brand-bold`, `--bh-bg-brand-subtle`, `--bh-bg-default`, `--bh-bg-default-hover`, `--bh-bg-raised`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-button-sm-height`, `--bh-button-xs-height`, `--bh-content-brand-default`, `--bh-content-brand-strong`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-date-day-cell-height`, `--bh-date-event-dot-offset-bottom`, `--bh-date-event-dot-size`, `--bh-date-list-item-height`, `--bh-date-month-year-item-height`, `--bh-date-month-year-list-top`, `--bh-date-month-year-list-width`, `--bh-date-month-year-spacer-height`, `--bh-date-nav-button-size`, `--bh-date-nav-icon-size`, `--bh-date-nav-icon-slot-size`, `--bh-date-picker-width`, `--bh-date-presets-width`, `--bh-date-range-month-width`, `--bh-date-range-surface-max-width`, `--bh-date-surface-border`, `--bh-date-surface-width-calendar`, `--bh-date-surface-width-picker`, `--bh-date-time-input-min-height`, `--bh-date-title-chevron-size`, `--bh-date-title-height`, `--bh-date-trigger-border`, `--bh-date-trigger-height`, `--bh-date-trigger-icon-size`, `--bh-date-trigger-icon-slot-size`, `--bh-date-trigger-shadow`, `--bh-date-trigger-width`, `--bh-icon-stroke-180`, `--bh-interactive-ghost-hover`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-soft-default`, `--bh-interactive-soft-hover`, `--bh-opacity-0`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--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-z-raised`, `--shadow-button-focus`, `--shadow-component-default`, `--shadow-date-month-year-list`, `--shadow-date-surface`, `--shadow-date-time-input`, `--shadow-input-focus-ring` |
 <!-- registry-contract:end -->

package/docs/design-system/components/file-upload.md

@@ -195,5 +195,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/FileUpload.tsx: FileUpload` |
 | `parts` | `FileUpload` |
 | `registryDependencies` | `button` |
-| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--shadow-component-default`, `--shadow-xs` |
+| `modes` | `single`, `multiple` |
+| `sizes` | `lg`, `sm` |
+| `states` | `default`, `hover`, `disabled`, `uploaded`, `uploading`, `uploading-progress`, `error` |
+| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--shadow-component-default`, `--shadow-sm` |
+| `variants` | `default`, `button` |
 <!-- registry-contract:end -->

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

@@ -17,9 +17,11 @@ Input is the text-entry field primitive for forms, filters, search, numeric entr
 | `state` | `default`, `filled`, `error`, `disabled` | `default` | Selects the visual state. |
 | `label`, `message` | `ReactNode` | `null` | Their presence enables the corresponding text rows unless explicitly disabled. |
 | `hasLeadingIcon` | `boolean` | `false` | Set true to show the default at-sign icon. |
-| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the leading slot; false always removes it. |
+| `leadingIcon` | `ReactNode \| false` | `null` | A node enables the 20px leading slot; direct SVG/image glyphs normalize to 16px. `false` removes it. |
 | `hasInformationIcon` | `boolean` | `false` | Set true to show the default information icon. |
 | `trailingIcon` | `ReactNode \| false` | `null` | A node enables the trailing slot; false always removes it. |
+| `shortcutKeys` | `readonly string[]` | `["Mod", "K"]` | For `kind="shortcut"`, renders one compact, platform-aware Shortcut chip. |
+| `shortcut` | `ReactNode` | `null` | Deprecated compact-chip content escape hatch; prefer `shortcutKeys`. |
 
 ## Migration
 
@@ -27,7 +29,7 @@ Input no longer adds the default at-sign or information icon when their props ar
 
 ## Token Contract
 
-Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Add-on and button segments should use logical borders and shared field tokens.
+Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Its default size is `lg` (36px); shortcut Inputs use the Figma 8px inline padding, 20px icon slot, 16px glyph, and shared compact Shortcut. Add-on and button segments should use logical borders and shared field tokens.
 
 ## RTL
 
@@ -68,17 +70,17 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `kbd` |
 | `props.density` | `"compact" \| "default" \| "comfortable"; default "default"; Preferred cross-component sizing contract. Overrides the legacy size prop with 32px, 36px, or 40px control heights.` |
 | `props.hasLeadingIcon` | `boolean; default false; Deprecated compatibility alias for showAtSign.` |
-| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom leading icon; false always removes the leading slot.` |
+| `props.leadingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom 16px glyph inside the shared 20px leading slot; false always removes the slot.` |
 | `props.hasInformationIcon` | `boolean; default false; Deprecated compatibility alias for showInfo.` |
 | `props.trailingIcon` | `React.ReactNode \| false; default null; Supplies and enables a custom trailing icon; false always removes the information slot.` |
 | `props.showAtSign` | `boolean; default false; Explicitly shows the semantic at-sign affordance when no leadingIcon is supplied.` |
 | `props.showInfo` | `boolean; default false; Explicitly shows the semantic information affordance when no trailingIcon is supplied.` |
-| `props.shortcutKeys` | `readonly string[]; default "Mod,K"; Renders the shortcut kind with shared Kbd keycaps. Use Mod for a platform-aware primary modifier.` |
-| `props.shortcut` | `React.ReactNode; default null; Deprecated single-keycap escape hatch. Prefer shortcutKeys for a structured shortcut chord.` |
+| `props.shortcutKeys` | `readonly string[]; default "Mod,K"; Renders the shortcut kind as one compact platform-aware Shortcut chip. Use Mod for the primary modifier.` |
+| `props.shortcut` | `React.ReactNode; default null; Deprecated compact-chip content escape hatch. Prefer shortcutKeys for a structured platform-aware chord.` |
 | `densities` | `compact`, `default`, `comfortable` |
 | `kinds` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` |
 | `sizes` | `md`, `lg`, `comfortable` |
 | `states` | `default`, `filled`, `error`, `disabled` |
-| `tokens` | `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-icon-stroke-225`, `--bh-input-border`, `--bh-input-chevron-size`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-helper-gap`, `--bh-input-icon-size`, `--bh-input-info-icon-size`, `--bh-input-inline-gap`, `--bh-input-inline-tags-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-segment-gap`, `--bh-input-segment-padding-x`, `--bh-input-stepper-icon-size`, `--bh-input-stepper-width`, `--bh-input-tag-height`, `--bh-input-tag-padding-x`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-interactive-input-soft-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--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-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-z-raised`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-disabled-overlay`, `--shadow-input-focus-overlay`, `--shadow-input-focus-ring`, `--shadow-input-focus-surface`, `--shadow-input-overlay`, `--shadow-input-surface` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-icon-stroke-225`, `--bh-input-border`, `--bh-input-chevron-size`, `--bh-input-comfortable-height`, `--bh-input-comfortable-padding-x`, `--bh-input-content-gap`, `--bh-input-helper-gap`, `--bh-input-icon-size`, `--bh-input-icon-slot-size`, `--bh-input-info-icon-size`, `--bh-input-inline-gap`, `--bh-input-inline-tags-gap`, `--bh-input-label-gap`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-md-padding-x`, `--bh-input-radius`, `--bh-input-segment-gap`, `--bh-input-segment-padding-x`, `--bh-input-stepper-icon-size`, `--bh-input-stepper-width`, `--bh-input-tag-height`, `--bh-input-tag-padding-x`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-interactive-input-soft-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--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-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-z-raised`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-disabled-overlay`, `--shadow-input-focus-overlay`, `--shadow-input-focus-ring`, `--shadow-input-focus-surface`, `--shadow-input-overlay`, `--shadow-input-surface` |
 | `variants` | `default`, `soft` |
 <!-- registry-contract:end -->

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

@@ -28,6 +28,8 @@ Use `asChild` when the whole row should be a native link or button. Interactive
 | `disabled` | `boolean` |
 | `ItemMedia variant` | `icon`, `avatar`, `image` |
 
+Default `ItemMedia` glyphs are 18px while their 20px layout footprint remains stable inside the media container.
+
 ## Install
 
 ```bash
@@ -67,6 +69,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `features` | `media slot`, `content slots`, `action slot`, `asChild composition`, `disabled semantics` |
 | `sizes` | `sm`, `md`, `lg` |
-| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-interactive-ghost-hover`, `--bh-item-actions-gap`, `--bh-item-content-gap`, `--bh-item-gap`, `--bh-item-group-gap`, `--bh-item-icon-size`, `--bh-item-media-radius`, `--bh-item-media-size`, `--bh-item-min-height-lg`, `--bh-item-min-height-md`, `--bh-item-min-height-sm`, `--bh-item-padding-x`, `--bh-item-padding-y`, `--bh-item-radius`, `--bh-radius-full`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-default`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-interactive-ghost-hover`, `--bh-item-actions-gap`, `--bh-item-content-gap`, `--bh-item-gap`, `--bh-item-group-gap`, `--bh-item-icon-size`, `--bh-item-icon-slot-size`, `--bh-item-media-radius`, `--bh-item-media-size`, `--bh-item-min-height-lg`, `--bh-item-min-height-md`, `--bh-item-min-height-sm`, `--bh-item-padding-x`, `--bh-item-padding-y`, `--bh-item-radius`, `--bh-radius-full`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-button-focus` |
 | `variants` | `default`, `muted`, `outline` |
 <!-- registry-contract:end -->

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

@@ -1,22 +1,25 @@
 # Kbd
 
-Kbd renders compact keyboard hints for shortcuts, command rows, and form help text.
+Kbd renders physical keyboard keys. Shortcut renders a compact combined hint for Inputs and constrained action rows, while KbdShortcut renders each physical key on its own surface.
 
 ## API
 
 ```tsx
-<Kbd>⌘</Kbd>
-<Kbd>K</Kbd>
+<Shortcut keys={["Mod", "K"]} />
+<KbdShortcut keys={["Mod", "K"]} />
+<Kbd>Esc</Kbd>
 <Kbd size="md">Shift</Kbd>
 ```
 
 | Prop | Values |
 | --- | --- |
 | `size` | `sm`, `md` |
+| `keys` | `readonly string[]`; use `Mod` for Command on Apple platforms and Control elsewhere |
+| `platform` | `auto`, `mac`, `windows`, `linux` |
 
 ## Token Contract
 
-Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button shadow tokens.
+Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button shadow tokens. Shortcut uses the Figma compact contract: 20px height/minimum width, 4px inline padding and radius, body-2xs medium typography, and no keycap shadow.
 
 ## RTL
 
@@ -51,12 +54,12 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/kbd.tsx: Kbd, KbdShortcut, kbdVariants` |
-| `parts` | `Kbd`, `KbdShortcut` |
+| `supportedExports` | `components/kbd.tsx: Kbd, KbdShortcut, Shortcut, kbdVariants, shortcutVariants` |
+| `parts` | `Kbd`, `KbdShortcut`, `Shortcut` |
 | `registryDependencies` | None |
-| `props.keys` | `readonly string[]; default null; Required by KbdShortcut. Each entry renders as its own keycap; use Mod for the platform primary modifier.` |
+| `props.keys` | `readonly string[]; default null; Used by KbdShortcut and Shortcut. Use Mod for the platform primary modifier; KbdShortcut separates keys while Shortcut combines them.` |
 | `props.platform` | `"auto" \| "mac" \| "windows" \| "linux"; default "auto"; Resolves Mod to Command on Apple platforms and Control elsewhere.` |
 | `props.disabled` | `boolean; default false; Uses disabled border, surface, content, and shadow tokens for shortcuts inside disabled controls.` |
 | `sizes` | `sm`, `md` |
-| `tokens` | `--bh-border-default`, `--bh-border-disabled`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-font-family`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-radius-md-6`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--shadow-button-soft` |
+| `tokens` | `--bh-border-default`, `--bh-border-disabled`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-font-family`, `--bh-interactive-soft-default`, `--bh-interactive-soft-disabled`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--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-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--shadow-button-soft` |
 <!-- registry-contract:end -->

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

@@ -29,7 +29,7 @@ Menu is a Radix DropdownMenu-backed action surface for contextual commands, navi
 
 ## Token Contract
 
-Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens.
+Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens. Leading glyphs are 18px inside 20px slots; trailing 16px affordances remain unchanged.
 
 ## RTL
 
@@ -71,6 +71,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `itemKinds` | `default`, `multiline`, `action`, `progress`, `button` |
 | `states` | `default`, `disabled` |
-| `tokens` | `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-icon-stroke-300`, `--bh-interactive-indicator-default`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-hover`, `--bh-interactive-switch-active`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-menu-action-gap`, `--bh-menu-action-height`, `--bh-menu-action-padding-x`, `--bh-menu-badge-height`, `--bh-menu-badge-padding-x`, `--bh-menu-bg`, `--bh-menu-divider-padding-y`, `--bh-menu-gap`, `--bh-menu-icon-padding`, `--bh-menu-item-action-height`, `--bh-menu-item-action-width`, `--bh-menu-item-bg`, `--bh-menu-item-button-height`, `--bh-menu-item-caption-height`, `--bh-menu-item-content-compact-padding-y`, `--bh-menu-item-content-padding`, `--bh-menu-item-default-height`, `--bh-menu-item-default-width`, `--bh-menu-item-divider-height`, `--bh-menu-item-gap`, `--bh-menu-item-hover-bg`, `--bh-menu-item-label-height`, `--bh-menu-item-multiline-height`, `--bh-menu-item-multiline-width`, `--bh-menu-item-padding-x`, `--bh-menu-item-progress-height`, `--bh-menu-item-radius`, `--bh-menu-item-slot-gap`, `--bh-menu-label-padding-x`, `--bh-menu-leading-icon-size`, `--bh-menu-padding-y`, `--bh-menu-progress-gap`, `--bh-menu-progress-height`, `--bh-menu-radius`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-menu-trailing-icon-size`, `--bh-menu-width`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--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-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-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--shadow-menu` |
+| `tokens` | `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-icon-stroke-300`, `--bh-interactive-indicator-default`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-hover`, `--bh-interactive-switch-active`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-menu-action-gap`, `--bh-menu-action-height`, `--bh-menu-action-padding-x`, `--bh-menu-badge-height`, `--bh-menu-badge-padding-x`, `--bh-menu-bg`, `--bh-menu-divider-padding-y`, `--bh-menu-gap`, `--bh-menu-icon-padding`, `--bh-menu-item-action-height`, `--bh-menu-item-action-width`, `--bh-menu-item-bg`, `--bh-menu-item-button-height`, `--bh-menu-item-caption-height`, `--bh-menu-item-content-compact-padding-y`, `--bh-menu-item-content-padding`, `--bh-menu-item-default-height`, `--bh-menu-item-default-width`, `--bh-menu-item-divider-height`, `--bh-menu-item-gap`, `--bh-menu-item-hover-bg`, `--bh-menu-item-label-height`, `--bh-menu-item-multiline-height`, `--bh-menu-item-multiline-width`, `--bh-menu-item-padding-x`, `--bh-menu-item-progress-height`, `--bh-menu-item-radius`, `--bh-menu-item-slot-gap`, `--bh-menu-label-padding-x`, `--bh-menu-leading-icon-size`, `--bh-menu-leading-icon-slot-size`, `--bh-menu-padding-y`, `--bh-menu-progress-gap`, `--bh-menu-progress-height`, `--bh-menu-radius`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-menu-trailing-icon-size`, `--bh-menu-width`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--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-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-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--shadow-menu` |
 | `widths` | `menu`, `default`, `multiline`, `action`, `auto` |
 <!-- registry-contract:end -->

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

@@ -115,5 +115,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `alert-dialog`, `button`, `checkbox`, `spinner` |
 | `intents` | `default`, `warning`, `danger` |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-modal-action-label-padding-x`, `--bh-modal-border`, `--bh-modal-width`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-button-focus`, `--shadow-component-default`, `--shadow-modal` |
+| `tokens` | `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-modal-action-label-padding-x`, `--bh-modal-border`, `--bh-modal-width`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-2xl`, `--shadow-button-focus`, `--shadow-modal` |
 <!-- registry-contract:end -->

package/docs/design-system/components/navigation-menu.md

@@ -59,5 +59,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuViewport`, `NavigationMenuIndicator` |
 | `registryDependencies` | None |
 | `features` | `top navigation`, `viewport`, `indicator`, `dropdown content` |
-| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-content-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-radius-2xl-12`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--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`, `--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-z-popover`, `--bh-z-raised`, `--shadow-popover` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-radius-2xl-12`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--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`, `--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-z-popover`, `--bh-z-raised`, `--shadow-popover` |
 <!-- registry-contract:end -->

package/docs/design-system/components/onboarding-step-list-item.md

@@ -52,7 +52,7 @@ The component consumes Banhaten semantic tokens and component aliases. Do not ha
 - Padding is `8px 12px` with a `10px` gap between the line wrap and label.
 - Text uses Inter Medium `15px / 24px` with zero letter spacing.
 - The line wrap is `24px` square.
-- Finished uses a `20px` success check-circle icon with `2px` default connector lines.
+- Finished uses an `18px` success check-circle glyph in a `20px` slot with `2px` default connector lines.
 - Active uses a `2px x 20px` brand line, a default border, white raised fill, `8px` radius, and component shadow.
 - Inactive uses a `2px x 40px` default connector line and subtle content color.
 - RTL mirrors visual order through `dir="rtl"` and right-aligns the label.
@@ -90,5 +90,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/OnboardingStepListItem.tsx: OnboardingStepListItem` |
 | `parts` | `OnboardingStepListItem` |
 | `registryDependencies` | None |
-| `tokens` | `--bh-bg-raised`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-control-default`, `--bh-font-family`, `--bh-icon-stroke-225`, `--bh-space-17xl-288`, `--bh-space-2xl-14`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--shadow-component-default` |
+| `states` | `finished`, `active`, `inactive` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-control-default`, `--bh-font-family`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-225`, `--bh-space-17xl-288`, `--bh-space-2xl-14`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--shadow-component-default` |
 <!-- registry-contract:end -->

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

@@ -93,6 +93,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | --- | --- |
 | `supportedExports` | `components/expanded/PageHeader.tsx: PageHeader` |
 | `parts` | `PageHeader` |
-| `registryDependencies` | `tabs` |
+| `registryDependencies` | `breadcrumbs`, `button`, `tabs` |
+| `modes` | `breadcrumbs`, `metadata`, `description`, `actions`, `tabs` |
+| `states` | `default`, `without-icon`, `without-actions`, `without-tabs` |
 | `tokens` | `--bh-bg-raised`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-icon-stroke-190`, `--bh-interactive-secondary-default`, `--bh-opacity-muted`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--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-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-line-height`, `--shadow-button-secondary` |
 <!-- registry-contract:end -->