banhaten 0.1.3 → 0.3.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

@@ -68,3 +68,20 @@ Open the live component page or run `npx banhaten docs alert-dialog` to inspect
 - `textDirection`: Title and description use dir="auto" for Arabic and English copy.
 - `spacing`: Header, body, and footer use logical layout and Banhaten spacing tokens so action order and copy mirror naturally.
 - `semantics`: Radix AlertDialog provides the modal alert role, focus trap, and safe cancellation behavior.
+
+<!-- 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/alert-dialog.tsx: AlertDialog, AlertDialogAction, AlertDialogBody, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogIcon, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, alertDialogContentVariants` |
+| `parts` | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogPortal`, `AlertDialogOverlay`, `AlertDialogHeader`, `AlertDialogIcon`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogBody`, `AlertDialogFooter`, `AlertDialogCancel`, `AlertDialogAction` |
+| `registryDependencies` | `button` |
+| `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-lg`, `--shadow-modal` |
+<!-- registry-contract:end -->

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

@@ -17,36 +17,49 @@ The implementation covers the Alert matrix from Figma:
 ## API
 
 ```tsx
-<Alert status="danger" />
-<Alert status="success" isExpandable dir="rtl" />
+<Alert status="danger" title="Unable to save" />
+<Alert
+  actions={[{ label: "عرض التفاصيل", onClick: openDetails }]}
+  status="success"
+  isExpandable
+  dir="rtl"
+  title="تم الحفظ"
+/>
 ```
 
 | Prop | Default |
 | --- | --- |
-| `status` | `danger` |
-| `isExpandable` | `false` |
-| `dir` | `ltr` |
-| `title` | localized demo title |
-| `description` | localized demo description |
-| `actions` | localized link actions |
-| `showActions` | `true` |
-| `showCloseButton` | `true` |
+| `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 with `20px 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 icons and close controls are `20px`; the close glyph is `16px`.
 - 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 `registry/styles/globals.css` as a `--bh-*` token or alias first.
+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`
@@ -58,7 +71,10 @@ The component consumes Banhaten semantic tokens and component aliases. Do not ha
 
 - The close affordance is a real button.
 - Action links are rendered as real buttons to support product actions.
-- `dir` controls visual and reading direction for English and Arabic states.
+- 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
 
@@ -74,6 +90,22 @@ Open the live component page or run `npx banhaten docs alert` to inspect source
 
 ## RTL Rules
 
-- `inheritsDirection`: false
+- `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
+
+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/alert.tsx: Alert, alertVariants, arabicAlertMessages` |
+| `parts` | `Alert` |
+| `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-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/aspect-ratio.md

@@ -42,3 +42,18 @@ Open the live component page or run `npx banhaten docs aspect-ratio` to inspect
 
 - `inheritsDirection`: false
 - `geometry`: Aspect Ratio controls media geometry and does not alter text direction.
+
+<!-- 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/aspect-ratio.tsx: AspectRatio` |
+| `parts` | `AspectRatio` |
+| `registryDependencies` | None |
+| `features` | `fixed media ratios`, `preview surfaces`, `responsive sizing` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-radius-xl-10` |
+<!-- registry-contract:end -->

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

@@ -85,3 +85,19 @@ Covered source files: `components/attribute.tsx`.
 ## 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
+
+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/attribute.tsx: AttributeCard, AttributeHeader, AttributeItem, AttributeLabel, AttributeList, AttributeValue, attributeCardVariants, attributeHeaderVariants, attributeItemVariants, attributeLabelVariants, attributeListVariants, attributeValueVariants` |
+| `parts` | `AttributeCard`, `AttributeHeader`, `AttributeList`, `AttributeItem`, `AttributeLabel`, `AttributeValue` |
+| `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` |
+<!-- registry-contract:end -->

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

@@ -72,3 +72,22 @@ Open the live component page or run `npx banhaten docs autocomplete` to inspect
 - `composition`: Uses the existing Input field, Select menu and menu item rows, and Tag chips instead of introducing new visual primitives.
 - `spacing`: Uses logical positioning, logical gaps, and inherited direction so the input, menu rows, checks, helper text, and selected tags mirror naturally.
 - `textDirection`: Labels, option text, helper text, and tag labels use dir="auto" through the composed primitives.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+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/autocomplete.tsx: Autocomplete, defaultFilterOptions` |
+| `parts` | `Autocomplete` |
+| `registryDependencies` | `input`, `popover`, `select`, `tag` |
+| `features` | `filtering`, `keyboard navigation`, `controlled value`, `controlled input value`, `controlled open state`, `selected tags`, `empty state` |
+| `modes` | `single`, `multiple` |
+| `sizes` | `md`, `lg` |
+| `states` | `default`, `filled`, `error`, `disabled` |
+| `tokens` | `--bh-autocomplete-menu-max-height`, `--bh-content-subtle`, `--bh-icon-stroke-225`, `--bh-input-icon-size`, `--bh-input-width`, `--bh-select-item-hover-bg`, `--bh-select-item-padding-x`, `--bh-select-menu-width`, `--bh-select-width`, `--bh-space-18xl-320`, `--bh-space-md-8`, `--bh-space-xs-4`, `--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` |
+| `variants` | `default`, `soft` |
+<!-- registry-contract:end -->

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

@@ -50,3 +50,21 @@ Open the live component page or run `npx banhaten docs avatar` to inspect source
 - `inheritsDirection`: true
 - `groupOverlap`: Uses logical -ms spacing so overlap reverses naturally in RTL.
 - `badgePlacement`: Status dots use logical end/bottom positioning; avatar actions use logical end/top positioning.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+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/avatar.tsx: Avatar, AvatarAction, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarIcon, AvatarImage, AvatarStatus, avatarActionVariants, avatarStatusVariants, avatarVariants` |
+| `parts` | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarIcon`, `AvatarBadge`, `AvatarStatus`, `AvatarAction`, `AvatarGroup`, `AvatarGroupCount` |
+| `registryDependencies` | None |
+| `actions` | `custom`, `edit`, `verified`, `remove` |
+| `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-default`, `--bh-content-on-brand`, `--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` |
+<!-- registry-contract:end -->

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

@@ -51,3 +51,22 @@ Open the live component page or run `npx banhaten docs badge` to inspect source
 - `directionalIconFlip`: Use data-rtl-flip="true" on arrows that should mirror.
 - `textDirection`: Uses dir="auto" by default for short Arabic and English labels.
 - `legacyVariants`: The previous variant prop is still accepted as a compatibility shim.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+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/badge.tsx: Badge, badgeVariants` |
+| `parts` | `Badge` |
+| `registryDependencies` | None |
+| `colors` | `neutral`, `blue`, `green`, `amber`, `danger`, `purple`, `fuchsia`, `rose`, `sky`, `golden` |
+| `options` | `splitAction` |
+| `sizes` | `sm`, `lg` |
+| `styles` | `light`, `outline`, `solid` |
+| `tokens` | `--bh-badge-focus-ring-width`, `--bh-badge-outline-border-width`, `--bh-bg-accent-amber-default`, `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-blue-bold`, `--bh-bg-accent-blue-subtle`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-golden-subtle`, `--bh-bg-accent-green-default`, `--bh-bg-accent-green-subtle`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-purple-subtle`, `--bh-bg-accent-red-default`, `--bh-bg-accent-red-subtle`, `--bh-bg-accent-rose-bold`, `--bh-bg-accent-rose-subtle`, `--bh-bg-accent-sky-base`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-bold`, `--bh-bg-neutral-subtle`, `--bh-border-accent-amber-strong`, `--bh-border-accent-amber-subtle`, `--bh-border-accent-blue-strong`, `--bh-border-accent-blue-subtle`, `--bh-border-accent-fuchsia-strong`, `--bh-border-accent-fuchsia-subtle`, `--bh-border-accent-golden-strong`, `--bh-border-accent-golden-subtle`, `--bh-border-accent-green-strong`, `--bh-border-accent-green-subtle`, `--bh-border-accent-purple-strong`, `--bh-border-accent-purple-subtle`, `--bh-border-accent-red-strong`, `--bh-border-accent-red-subtle`, `--bh-border-accent-rose-strong`, `--bh-border-accent-rose-subtle`, `--bh-border-accent-sky-strong`, `--bh-border-accent-sky-subtle`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-focus-danger`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-content-accent-amber-default`, `--bh-content-accent-amber-strong`, `--bh-content-accent-blue-default`, `--bh-content-accent-blue-strong`, `--bh-content-accent-fuchsia-default`, `--bh-content-accent-fuchsia-strong`, `--bh-content-accent-golden-default`, `--bh-content-accent-golden-strong`, `--bh-content-accent-green-default`, `--bh-content-accent-green-strong`, `--bh-content-accent-purple-default`, `--bh-content-accent-purple-strong`, `--bh-content-accent-red-default`, `--bh-content-accent-red-strong`, `--bh-content-accent-rose-default`, `--bh-content-accent-rose-strong`, `--bh-content-accent-sky-default`, `--bh-content-accent-sky-strong`, `--bh-content-default`, `--bh-content-link`, `--bh-content-muted`, `--bh-content-on-color`, `--bh-content-on-light`, `--bh-content-on-neutral`, `--bh-interactive-ghost-default`, `--bh-opacity-35`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-medium-letter-spacing`, `--bh-text-body-2xs-medium-line-height`, `--bh-text-body-2xs-semibold-font-weight`, `--bh-text-body-3xs-medium-font-size`, `--bh-text-body-3xs-medium-font-weight`, `--bh-text-body-3xs-medium-letter-spacing`, `--bh-text-body-3xs-medium-line-height`, `--bh-text-body-3xs-semibold-font-weight` |
+| `types` | `default`, `leading-icon`, `trailing-icon`, `dot`, `flag` |
+<!-- registry-contract:end -->

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

@@ -53,7 +53,7 @@ The implementation covers the Banner matrix from Figma:
 
 ## Token Contract
 
-The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
 
 - Backgrounds: `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-muted`, `--bh-bg-always-white`
 - Content: `--bh-content-default`, `--bh-content-inverse`, `--bh-content-link`, `--bh-content-muted`, `--bh-content-subtle`
@@ -83,3 +83,21 @@ Open the live component page or run `npx banhaten docs banner` to inspect source
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- 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/Banner.tsx: Banner` |
+| `parts` | `Banner` |
+| `registryDependencies` | `button`, `input` |
+| `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-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-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-md` |
+| `variants` | `brand`, `grey`, `brand-light` |
+<!-- registry-contract:end -->

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

@@ -172,3 +172,20 @@ Covered source files: `components/expanded/breadcrumbs.css`, `components/expande
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- 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/Breadcrumbs.tsx: BreadcrumbFolderIcon, BreadcrumbHomeIcon, Breadcrumbs` |
+| `parts` | `Breadcrumbs` |
+| `registryDependencies` | None |
+| `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-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` |
+| `variants` | `default`, `raised` |
+<!-- registry-contract:end -->

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

@@ -23,6 +23,16 @@ Use `ButtonGroup` as the connected container and `ButtonGroupItem` for each acti
 </ButtonGroup>
 ```
 
+Use `ToggleGroup` when the connected controls own a single or multiple pressed-value model. It includes controlled and uncontrolled state plus Home, End, and direction-aware arrow-key focus movement.
+
+```tsx
+<ToggleGroup aria-label="Text alignment" defaultValue="start">
+  <ToggleGroupItem value="start">Start</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+  <ToggleGroupItem value="end">End</ToggleGroupItem>
+</ToggleGroup>
+```
+
 ## Variants
 
 | Prop | Values |
@@ -31,6 +41,9 @@ Use `ButtonGroup` as the connected container and `ButtonGroupItem` for each acti
 | `mode` | `default`, `iconOnly` |
 | `ButtonGroupItem aria-pressed` | `true`, `false` |
 | `ButtonGroupItem disabled` | `boolean` |
+| `ToggleGroup type` | `single`, `multiple` |
+| `ToggleGroup value`, `defaultValue` | `string`, `string[]` |
+| `ToggleGroupItem value` | `string` |
 
 Interaction styling is applied through native CSS pseudo states: `:hover`, `:active`, `:focus-visible`, `:disabled`, and `aria-pressed="true"`.
 
@@ -81,3 +94,25 @@ Covered source files: `components/button-group.tsx`.
 ## Accessibility
 
 This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
+
+<!-- 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/button-group.tsx: ButtonGroup, ButtonGroupItem, ButtonGroupLabel, ToggleGroup, ToggleGroupItem, buttonGroupItemVariants, buttonGroupLabelVariants, buttonGroupVariants` |
+| `parts` | `ButtonGroup`, `ButtonGroupItem`, `ButtonGroupLabel`, `ToggleGroup`, `ToggleGroupItem` |
+| `registryDependencies` | None |
+| `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` |
+| `widths` | `fixed`, `content` |
+<!-- registry-contract:end -->

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

@@ -75,3 +75,21 @@ Button consumes semantic interaction, content, border, radius, typography, spaci
 ```bash
 npx banhaten add button
 ```
+
+<!-- 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/button.tsx: Button, buttonVariants` |
+| `parts` | `Button` |
+| `registryDependencies` | `spinner` |
+| `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-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-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
 
-Public exports: `Card`, `CardMedia`, `CardFooter`, `CardActions`.
+Supported runtime exports: `Card`, `CardActions`, `CardFooter`, `CardMedia`, `CardSurface`, `cardVariants`.
 
 | Contract | Values |
 | --- | --- |
@@ -76,3 +84,20 @@ Covered source files: `components/card.tsx`, `assets/images/art-01.jpg`.
 ## 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
+
+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/card.tsx: Card, CardActions, CardFooter, CardMedia, CardSurface, cardVariants` |
+| `parts` | `Card`, `CardSurface`, `CardMedia`, `CardFooter`, `CardActions` |
+| `registryDependencies` | `button` |
+| `breakpoints` | `desktop`, `mobile` |
+| `orientations` | `vertical`, `horizontal` |
+| `tokens` | `--bh-bg-accent-green-subtle`, `--bh-bg-accent-sky-subtle`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-card-actions-max-width`, `--bh-card-bg`, `--bh-card-border`, `--bh-card-content-padding`, `--bh-card-desktop-content-padding`, `--bh-card-desktop-full-height`, `--bh-card-desktop-horizontal-padding`, `--bh-card-desktop-media-height`, `--bh-card-full-height`, `--bh-card-horizontal-media-width`, `--bh-card-horizontal-min-height`, `--bh-card-horizontal-padding`, `--bh-card-horizontal-width`, `--bh-card-media-height`, `--bh-card-media-overlay`, `--bh-card-mobile-content-padding`, `--bh-card-mobile-full-height`, `--bh-card-mobile-horizontal-padding`, `--bh-card-mobile-media-height`, `--bh-card-more-icon-size`, `--bh-card-more-size`, `--bh-card-radius`, `--bh-card-vertical-width`, `--bh-content-default`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-control-default`, `--bh-interactive-ghost-hover`, `--bh-radius-3xl-16`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-text-body-lg-regular-font-size`, `--bh-text-body-lg-regular-font-weight`, `--bh-text-body-lg-regular-letter-spacing`, `--bh-text-body-lg-regular-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-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--shadow-button-focus` |
+| `types` | `leading-image`, `trailing-image`, `full-image` |
+<!-- registry-contract:end -->

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

@@ -5,7 +5,7 @@ Carousel is an Embla-backed carousel with content, item, previous, and next cont
 ## API
 
 ```tsx
-<Carousel>
+<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
   <CarouselContent>
     <CarouselItem>Slide</CarouselItem>
   </CarouselContent>
@@ -20,11 +20,11 @@ Carousel controls use Banhaten Button tokens, spacing, radius, and directional i
 
 ## RTL
 
-Directional icons flip in RTL. Set Embla options through `opts` when you need a custom direction strategy.
+Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
 
 ## Accessibility
 
-Carousel exposes a region and button labels for previous and next controls.
+Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
 
 ## Install
 
@@ -42,3 +42,20 @@ Open the live component page or run `npx banhaten docs carousel` to inspect sour
 
 - `inheritsDirection`: true
 - `directionalIconFlip`: Previous and next arrow icons flip in RTL.
+- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
+
+<!-- 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/carousel.tsx: Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, arabicCarouselMessages` |
+| `parts` | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
+| `registryDependencies` | `button` |
+| `features` | `Embla API`, `previous and next controls`, `plugin support` |
+| `orientations` | `horizontal`, `vertical` |
+| `tokens` | `--bh-radius-full`, `--bh-space-3xl-16`, `--bh-space-7xl-40`, `--bh-space-8xl-48` |
+<!-- registry-contract:end -->

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

@@ -12,7 +12,7 @@ Catalog Components is an expanded-tier showcase bundle for catalog-style product
 | --- | --- |
 | `Breadcrumbs` | expanded breadcrumbs component |
 | `CatalogContentDivider`, `CatalogDivider` | catalog divider visuals |
-| `CatalogTag` | catalog tag previews |
+| `Tag` | core tag component, previewed in the showcase |
 | `FileUpload` | expanded upload states |
 | `Table` | expanded table preview |
 
@@ -43,3 +43,20 @@ Open the live component page or run `npx banhaten docs catalog-components` to in
 ## RTL Rules
 
 This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+<!-- 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/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/chart.md

@@ -41,3 +41,18 @@ Open the live component page or run `npx banhaten docs chart` to inspect source
 
 - `inheritsDirection`: true
 - `layout`: Chart labels and legends should use logical layout; chart geometry is controlled by Recharts.
+
+<!-- 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/chart.tsx: ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent` |
+| `parts` | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent` |
+| `registryDependencies` | None |
+| `features` | `responsive container`, `tooltip content`, `legend content`, `config colors` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-chart-categorical-aqua`, `--bh-chart-categorical-brand`, `--bh-chart-categorical-danger`, `--bh-chart-categorical-fuchsia`, `--bh-chart-categorical-information`, `--bh-chart-categorical-purple`, `--bh-chart-categorical-success`, `--bh-chart-categorical-warning`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--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-popover` |
+<!-- registry-contract:end -->

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

@@ -50,3 +50,19 @@ Open the live component page or run `npx banhaten docs checkbox` to inspect sour
 - `inheritsDirection`: true
 - `controlPlacement`: The card uses start/end control placement so the checkbox mirrors correctly in RTL.
 - `textDirection`: Labels and descriptions use dir="auto" and tokenized body-md/body-sm typography.
+
+<!-- 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/checkbox.tsx: Checkbox, CheckboxCard, checkboxCardVariants, checkboxVariants` |
+| `parts` | `Checkbox`, `CheckboxCard` |
+| `registryDependencies` | None |
+| `cardPositions` | `start`, `end` |
+| `states` | `unchecked`, `checked`, `indeterminate`, `selected`, `disabled` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-checkbox-card-border`, `--bh-checkbox-card-border-width`, `--bh-checkbox-card-border-width-active`, `--bh-checkbox-card-border-width-current`, `--bh-checkbox-card-content-gap`, `--bh-checkbox-card-gap`, `--bh-checkbox-card-label-gap`, `--bh-checkbox-card-media-icon-size`, `--bh-checkbox-card-padding`, `--bh-checkbox-card-radius`, `--bh-checkbox-card-text-gap`, `--bh-checkbox-card-width`, `--bh-checkbox-control-border`, `--bh-checkbox-control-radius`, `--bh-checkbox-control-size`, `--bh-checkbox-icon-size`, `--bh-checkbox-root-size`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-icon-stroke-300`, `--bh-interactive-checkbox-default`, `--bh-interactive-checkbox-hover`, `--bh-opacity-60`, `--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-checkbox-card`, `--shadow-checkbox-card-focus`, `--shadow-checkbox-control`, `--shadow-checkbox-focus`, `--shadow-component-default` |
+<!-- registry-contract:end -->