banhaten 0.3.0 → 0.5.0

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

@@ -1,74 +1,74 @@
-# Alert Dialog
-
-Alert Dialog is the destructive or consequential confirmation primitive. It is backed by Radix AlertDialog so focus, Escape behavior, outside interaction, and alert-dialog semantics are handled by the correct primitive.
-
-## API
-
-```tsx
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="danger">Delete project</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogIcon intent="danger" />
-      <AlertDialogTitle>Delete project?</AlertDialogTitle>
-    </AlertDialogHeader>
-    <AlertDialogBody>
-      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
-    </AlertDialogBody>
-    <AlertDialogFooter>
-      <AlertDialogCancel>Cancel</AlertDialogCancel>
-      <AlertDialogAction>Delete project</AlertDialogAction>
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `AlertDialog`, `AlertDialogTrigger`, `AlertDialogPortal` | Radix AlertDialog shell |
-| `AlertDialogOverlay`, `AlertDialogContent` | modal alert surface |
-| `AlertDialogHeader`, `AlertDialogBody`, `AlertDialogFooter` | layout regions |
-| `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogIcon` | accessible warning copy |
-| `AlertDialogCancel`, `AlertDialogAction` | safe cancel and confirm actions |
-
-| Prop | Values |
-| --- | --- |
-| `size` | `sm`, `default`, `lg` |
-| `intent` | `default`, `warning`, `danger` |
-
-## Token Contract
-
-Alert Dialog uses Banhaten raised surface, backdrop, border, radius, shadow, semantic intent, body typography, focus, and button tokens.
-
-## RTL
-
-The surface inherits direction. Title and description use `dir="auto"` and action layout uses logical flex order.
-
-## Accessibility
-
-Use Alert Dialog for destructive or irreversible choices. Focus should land on the cancel action by default when you build higher-level confirmations. `ConfirmModal` is wired on top of this alert-dialog primitive for the constrained confirmation pattern.
-
-## Install
-
-```bash
-npx banhaten add alert-dialog
-```
-
-## Examples
-
-Primary registry example: `examples/alert-dialog-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs alert-dialog` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
-- `spacing`: Header, body, and footer use logical layout and Banhaten spacing tokens so action order and copy mirror naturally.
-- `semantics`: Radix AlertDialog provides the modal alert role, focus trap, and safe cancellation behavior.
-
+# Alert Dialog
+
+Alert Dialog is the destructive or consequential confirmation primitive. It is backed by Radix AlertDialog so focus, Escape behavior, outside interaction, and alert-dialog semantics are handled by the correct primitive.
+
+## API
+
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="danger">Delete project</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogIcon intent="danger" />
+      <AlertDialogTitle>Delete project?</AlertDialogTitle>
+    </AlertDialogHeader>
+    <AlertDialogBody>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogBody>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete project</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `AlertDialog`, `AlertDialogTrigger`, `AlertDialogPortal` | Radix AlertDialog shell |
+| `AlertDialogOverlay`, `AlertDialogContent` | modal alert surface |
+| `AlertDialogHeader`, `AlertDialogBody`, `AlertDialogFooter` | layout regions |
+| `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogIcon` | accessible warning copy |
+| `AlertDialogCancel`, `AlertDialogAction` | safe cancel and confirm actions |
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `default`, `lg` |
+| `intent` | `default`, `warning`, `danger` |
+
+## Token Contract
+
+Alert Dialog uses Banhaten raised surface, backdrop, border, radius, shadow, semantic intent, body typography, focus, and button tokens.
+
+## RTL
+
+The surface inherits direction. Title and description use `dir="auto"` and action layout uses logical flex order.
+
+## Accessibility
+
+Use Alert Dialog for destructive or irreversible choices. Focus should land on the cancel action by default when you build higher-level confirmations. `ConfirmModal` is wired on top of this alert-dialog primitive for the constrained confirmation pattern.
+
+## Install
+
+```bash
+npx banhaten add alert-dialog
+```
+
+## Examples
+
+Primary registry example: `examples/alert-dialog-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs alert-dialog` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
+- `spacing`: Header, body, and footer use logical layout and Banhaten spacing tokens so action order and copy mirror naturally.
+- `semantics`: Radix AlertDialog provides the modal alert role, focus trap, and safe cancellation behavior.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -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-lg`, `--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`, `--elevation-06`, `--elevation-modal` |
 <!-- registry-contract:end -->

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

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

@@ -0,0 +1,134 @@
+# Approval Card
+
+Approval cards pause the agent for a human decision. `ApprovalQuestions` walks through up to a few single-choice questions with a free-text "Something else" option, `ApprovalCommand` asks to run a shell command, and `ApprovalPlan` presents a short plan as a pending to-do list with an optional auto-approve countdown. All three compose `ApprovalFrame`, the shared shell: a tinted icon header, the body, and an action row. Compose it yourself for another kind of decision.
+
+Questions slide vertically inside a viewport sized to the active one, step badges and countdown seconds roll their digits, and the plan composes Task List parts: a well root, a static header with the step count, and a preview fold.
+
+## API
+
+```tsx
+import {
+  ApprovalCommand,
+  ApprovalPlan,
+  ApprovalQuestions,
+} from "@/components/ui/approval-card"
+
+<ApprovalQuestions
+  onApprove={({ answers }) => submit(answers)}
+  onReject={skip}
+  questions={questions}
+/>
+
+<ApprovalCommand command="pnpm db:migrate && pnpm build" cwd="~/acme" onApprove={run} onReject={skip} />
+
+<ApprovalPlan onApprove={({ source }) => approve(source)} onViewPlan={openPlan} plan={plan} planTitle="Session auth migration" />
+```
+
+Every card also takes `title` and `approveLabel`, each with its own default, plus native `div` props.
+
+### ApprovalQuestions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `questions` | `readonly ApprovalQuestion[]` | – | `{ id, prompt, options }` answered one at a time. |
+| `onApprove` | `(payload: { answers }) => void` | – | Fires once every question has an answer. |
+| `onReject` / `rejectLabel` | `() => void` / `string` | – / `"Skip"` | The skip action. |
+| `labels` | `Partial<ApprovalQuestionsLabels>` | English | Navigation and free-text copy. |
+
+### ApprovalCommand
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `command` / `cwd` | `string` | – | Command block content and the working directory above it. |
+| `onApprove` / `onReject` | `() => void` | – | Run and Skip actions. |
+| `rejectLabel` | `string` | `"Skip"` | Skip action copy. |
+
+### ApprovalPlan
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `plan` | `readonly ApprovalPlanStep[]` | – | Steps as `{ id, title }`, shown as pending to-do rows. Keep step details for the full plan that `onViewPlan` opens. |
+| `planTitle` / `planSummary` | `React.ReactNode` | – | Intro copy above the steps. |
+| `planPreviewCount` | `number` | `3` | Steps shown before the "more" fold. |
+| `autoApproveSeconds` | `number` | `0` | Opt-in countdown. At zero `onApprove` fires with `source: "timeout"`; choosing either action cancels it, and a new value restarts it. |
+| `onApprove` | `(payload: { source }) => void` | – | `source` is `"user"` for a click or `"timeout"` for the countdown. |
+| `onViewPlan` / `viewPlanLabel` | `() => void` / `string` | – / `"View plan"` | Secondary action that opens the full plan. |
+| `onDownload` / `onExpand` | `() => void` | – | Adds header actions. |
+| `labels` | `Partial<ApprovalPlanLabels>` | English | Countdown, fold, and header action copy. |
+
+### ApprovalFrame
+
+```tsx
+import { ApprovalFrame } from "@/components/ui/approval-card"
+
+<ApprovalFrame
+  approveLabel="Apply"
+  icon={<GitCompareIcon />}
+  onApprove={apply}
+  onSecondary={review}
+  secondaryLabel="Review"
+  title="Apply this change?"
+  tone="warning"
+>
+  <DiffSummary files={files} />
+</ApprovalFrame>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` / `tone` | `React.ReactNode` / `"info" \| "warning" \| "success"` | – | Header glyph in a tile tinted by `tone`; the tile sets the glyph's size and stroke. The ready-made cards use info for questions, warning for commands, and success for plans. |
+| `title` | `React.ReactNode` | – | Header copy. |
+| `approveLabel` / `onApprove` / `approveDisabled` | `string` / `() => void` / `boolean` | – / – / `false` | Primary action, disabled until the decision is complete. |
+| `secondaryLabel` / `onSecondary` | `string` / `() => void` | – | Secondary action. |
+| `headerActions` / `footerStart` | `React.ReactNode` | – | Controls at the end of the header, and content at the start of the action row. |
+
+## Install
+
+```bash
+npx banhaten add approval-card
+```
+
+## Examples
+
+Primary registry example: `examples/approval-card-demo.tsx`.
+
+## Token Contract
+
+The card uses `--bh-bg-raised`, `--bh-radius-2xl-12`, `--elevation-02`, and `--bh-space-xl-12` padding. Icon tiles map the info, warning, and success tones to `--bh-bg-info-subtle`, `--bh-bg-warning-subtle`, and `--bh-bg-success-subtle` with the matching content tokens, and stroke their glyph with `--bh-icon-stroke-200`. Options use `--bh-border-subtle`, `--bh-radius-lg-8`, and lift to `--elevation-02` when selected while their Kbd fills with `--bh-bg-inverse`. The command block uses `--bh-font-family-mono` on `--bh-bg-subtle`. Slides and fades use the `--bh-duration-slow` and `--bh-duration-moderate` foundation tokens with `--bh-easing-emphasized`. The countdown ring drains linearly over each one-second tick, and the countdown unmounts when its fade ends.
+
+Covered source files: `components/approval-card.tsx`, the internal `components/approval-frame.tsx` and `components/approval-questions.tsx`, `components/approval-card.css`, and the `button`, `kbd`, `rolling-count`, `task-list`, and `tooltip` registry dependencies.
+
+## RTL Rules
+
+- Header, options, and actions inherit direction and use logical alignment.
+- The command block and working directory stay LTR; the submit arrow mirrors.
+
+## Accessibility
+
+In `ApprovalQuestions`, each question is a group of native radio inputs labelled by its prompt: Tab reaches the group once, arrow keys move the choice without skipping ahead, the letter shown on each option picks it, and Enter confirms the answer. "Something else" is its own radio next to the text field, and Enter in the field commits the typed answer unless it is confirming an IME composition; inactive questions are hidden from assistive technology and removed from the tab order. Enter on the last answered question approves. The previous and next controls form a group named by `questionOf`, such as "Question 2 of 3". The countdown is a polite live region whose ring is also a labelled cancel button with a Tooltip. Slides, rolls, and fades collapse to instant changes under `prefers-reduced-motion`.
+
+<!-- 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/approval-card.tsx: ApprovalCommand, ApprovalFrame, ApprovalPlan, ApprovalQuestions` |
+| `parts` | `ApprovalQuestions`, `ApprovalCommand`, `ApprovalPlan`, `ApprovalFrame` |
+| `registryDependencies` | `button`, `kbd`, `rolling-count`, `task-list`, `tooltip` |
+| `props.questions` | `readonly ApprovalQuestion[]; default null; ApprovalQuestions: single-choice questions, each with a free-text Something else option.` |
+| `props.command` | `string; default null; ApprovalCommand: shell command shown in the mono block.` |
+| `props.cwd` | `string; default null; ApprovalCommand: working directory shown above the command.` |
+| `props.plan` | `readonly ApprovalPlanStep[]; default null; ApprovalPlan: steps with an id and a title, rendered as a pending to-do list. Step details belong in the full plan.` |
+| `props.planPreviewCount` | `number; default "3"; ApprovalPlan: steps shown before the more fold.` |
+| `props.autoApproveSeconds` | `number; default "0"; ApprovalPlan: opt-in countdown; at zero onApprove fires with source timeout. Either action cancels it. A new value restarts it.` |
+| `props.icon` | `React.ReactNode; default null; ApprovalFrame: header glyph, sized and stroked by the tinted icon tile.` |
+| `props.tone` | `"info" \| "warning" \| "success"; default null; ApprovalFrame: tint of the icon tile. Questions use info, commands warning, and plans success.` |
+| `props.onApprove` | `callback; default null; Primary action. ApprovalQuestions passes { answers }, ApprovalPlan passes { source: user \| timeout }, and ApprovalCommand passes nothing.` |
+| `props.onReject` | `() => void; default null; Skip action on ApprovalQuestions and ApprovalCommand.` |
+| `props.onViewPlan` | `() => void; default null; ApprovalPlan secondary action that opens the full plan; it also stops the countdown.` |
+| `props.labels` | `Partial<ApprovalQuestionsLabels> \| Partial<ApprovalPlanLabels>; default "English"; Localized navigation, countdown, and helper copy for the card that uses them.` |
+| `tokens` | `--bh-bg-info-subtle`, `--bh-bg-inverse`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-subtle`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-success-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-information-default`, `--bh-content-inverse`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-default`, `--bh-duration-default`, `--bh-duration-fast`, `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-easing-emphasized`, `--bh-easing-standard`, `--bh-font-family`, `--bh-font-family-mono`, `--bh-icon-stroke-180`, `--bh-icon-stroke-200`, `--bh-icon-stroke-250`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--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-body-2xs-medium-font-size`, `--bh-text-body-2xs-medium-font-weight`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-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-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`, `--elevation-02`, `--elevation-component-focus-ring` |
+<!-- registry-contract:end -->

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

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