@d4gger/design-system 2.7.0

package/dist/docs/accordion.md

@@ -0,0 +1,250 @@
+---
+title: Accordion
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/accordion/Accordion.tsx
+css_path: packages/d4gger-design-system/src/styles/components/accordion.css
+props_path: packages/d4gger-design-system/src/components/accordion/accordion.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Accordion.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/navigation.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Collapsible
+  - Icon
+---
+
+# Accordion
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A vertically stacked set of disclosure items that reveal or hide related content. Each item carries a header with a trigger and a content region; the whole list can be configured as single-open or multi-open. Use Accordion for FAQs, settings disclosure, and progressive disclosure of dense content. For a single show/hide region inside a card or panel, use `Collapsible` instead.
+
+## Anatomy & slots
+
+**Parent:** `Accordion` (alias of `AccordionRoot`). Wires the Radix Accordion primitive and exposes a local context (`density`, `disabled`) for descendants.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Accordion` (root) | `<div>` (or `Slot` host) | Radix `AccordionPrimitive.Root` + class | Root host. Accepts `type`, `value`, `defaultValue`, `onValueChange`, `collapsible`, `orientation`, `dir` from Radix. Writes `dsx-accordion` and provides `AccordionContext`. |
+| `Accordion.Item` | `<div>` (or `Slot` host) | Radix `AccordionPrimitive.Item` + class | Single disclosure row. Carries the Radix `value` and `disabled` props. Writes `dsx-accordion__item`. |
+| `Accordion.Header` | `<h3>` (or `Slot` host) | Radix `AccordionPrimitive.Header` + class | Heading region that hosts the trigger. Writes `dsx-accordion__header`. The host defaults to `h3`; consumers can swap with `asChild` to use a different heading level. |
+| `Accordion.Trigger` | `<button>` (or `Slot` host) | Radix `AccordionPrimitive.Trigger` + class | The clickable control. Renders a flex row with the children in a leading `<span>` and one trailing indicator. The indicator defaults to `Icon name="chevron-down"`, can be replaced through `indicator`, and can be hidden with `indicator={false}`. Writes `dsx-accordion__trigger` and forwards Radix's `data-state` (`open` / `closed`). |
+| `Accordion.Content` | `<div>` (or `Slot` host) | Radix `AccordionPrimitive.Content` + class | The expanded region. Renders an inner `dsx-accordion__content-inner` wrapper for padding. Mounts the component-local motion styles via `useAccordionMotionStyles` and writes `dsx-accordion__content`. |
+| `Accordion.ItemBody` | `<div>` (or `Slot` host) | Wraps `AccordionPrimitive.Content` | Deprecated compatibility alias for `Accordion.Content`. It writes `data-slot="accordion-item-body"` and `dsx-accordion__body`; use it instead of, never inside, `Accordion.Content`. |
+| `Accordion.ItemIndicator` | `<div>` (or `Slot` host) | Pure host element | Deprecated compatibility visual slot. Prefer `Accordion.Trigger indicator`. It defaults to a chevron and must not be composed alongside the trigger's built-in indicator. |
+
+**Context:**
+
+`AccordionContext` carries `{ density, disabled }`. `useAccordionStyles()` reads it for descendants that need to read the accordion's effective disabled state. The context is created with a default of `{ density: 'comfortable', disabled: false }` so consumers can call the hook outside an `Accordion` if needed, but the published contract targets in-tree usage.
+
+## Props contract
+
+**Root props (in addition to Radix `AccordionPrimitive.Root` props):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `disabled` | `boolean` | `false` | no | Disables every trigger inside the root and feeds `AccordionContext.disabled`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-accordion`. | no |
+
+The root also accepts and forwards all `React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>` (this includes `type`, `value`, `defaultValue`, `onValueChange`, `collapsible`, `orientation`, `dir`).
+
+**Item props:** `value` and `disabled` come from Radix's `AccordionPrimitive.Item`. The DS adds `asChild` and `className`.
+
+**Header props:** Radix `AccordionPrimitive.Header` props. The DS adds `asChild` and `className`.
+
+**Trigger props:** Radix `AccordionPrimitive.Trigger` props. The DS adds
+`asChild`, `className`, and `indicator?: React.ReactNode`. When `indicator` is
+`undefined`, one built-in chevron renders. `false` hides the indicator. Any
+other node replaces the built-in chevron inside the rotating
+`data-slot="accordion-trigger-indicator"` wrapper.
+
+**Content props:** Radix `AccordionPrimitive.Content` props (including `forceMount`). The DS adds `asChild` and `className`.
+
+**ItemBody props:** Deprecated compatibility API. It accepts `asChild`,
+`className`, and standard `<div>` HTML attributes. The body always wraps its
+children in `dsx-accordion__body-inner` for padding. Prefer
+`Accordion.Content`.
+
+**ItemIndicator props:** Deprecated compatibility API. It accepts `asChild`,
+`className`, and standard `<div>` HTML attributes. `children` override the
+default chevron. Prefer `Accordion.Trigger indicator`.
+
+Rules:
+
+- Every public slot has `asChild` and a `dsx-accordion__*` class on the consumer's chosen host. The default host is the listed element (`div`, `h3`, `button`).
+- The root does not emit `data-size`, `data-variant`, `data-radius`, `data-accent-color`, or `data-high-contrast` (the contract calls for none of those).
+- `disabled` on the root is read once and stored in `AccordionContext`; per-item `disabled` is read from the item props directly.
+- A trigger owns exactly one indicator by default. Use the `indicator` prop to replace or hide it; do not add `Accordion.ItemIndicator` to the natural compound composition.
+- `Accordion.ItemBody` and `Accordion.ItemIndicator` remain exported for compatibility only. Do not nest `ItemBody` inside `Content`.
+- The motion styles for `Accordion.Content` and `Accordion.ItemBody` are inserted into the document head by `useAccordionMotionStyles` and shared across all instances on the page (the insertion effect is idempotent and uses a fixed `id` of `dsx-accordion-motion-styles`).
+
+## CSS class contract
+
+**Root class:** `dsx-accordion`
+
+**Modifier classes** (driven by Radix's `data-state` on the trigger and content):
+
+| Attribute | Source | Class | CSS file |
+|---|---|---|---|
+| `data-state` on trigger | Radix | `.dsx-accordion__trigger[data-state='open']` | `accordion.css` |
+| `data-state` on content | Radix | `.dsx-accordion__content[data-state='open']`, `.dsx-accordion__content[data-state='closed']` | `accordion.css` (animation hooks live in the runtime-inserted style block) |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Accordion` (root) | `dsx-accordion` | `accordion.css` |
+| `Accordion.Item` | `dsx-accordion__item` | `accordion.css` |
+| `Accordion.Header` | `dsx-accordion__header` | `accordion.css` |
+| `Accordion.Trigger` | `dsx-accordion__trigger` | `accordion.css` |
+| Trigger label span | `dsx-accordion__label` | `accordion.css` |
+| Trigger indicator wrapper | `dsx-accordion__chevron`, `data-slot="accordion-trigger-indicator"` | `accordion.css` |
+| `Accordion.Content` | `dsx-accordion__content` | `accordion.css` |
+| Content inner padding wrapper | `dsx-accordion__content-inner` | `accordion.css` |
+| `Accordion.ItemIndicator` | `dsx-accordion__indicator` | `accordion.css` |
+| `Accordion.ItemBody` | `dsx-accordion__body` | `accordion.css` |
+| Item body inner padding wrapper | `dsx-accordion__body-inner` | `accordion.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. The motion and layout are single-value only.
+
+**Reduced motion:**
+
+- The runtime-injected style block includes:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    .dsx-accordion__content[data-state='open'],
+    .dsx-accordion__content[data-state='closed'] {
+      animation: none !important;
+    }
+  }
+  ```
+  The expand/collapse keyframes (`dsx-accordion-expand`, `dsx-accordion-collapse`) are gated off when the user prefers reduced motion. The chevron rotation uses `var(--dsx-motion-duration-fast)` and is not explicitly gated at the CSS level; the token layer should map it to `0` under reduced motion.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Item bottom border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge between adjacent items; removed on `:last-child` |
+| Trigger color | `var(--dsx-color-on-surface)` | Closed trigger text |
+| Trigger padding | `var(--dsx-space-md)` | Internal gutter |
+| Trigger label type | `var(--dsx-typography-label-large-font-family)`, `var(--dsx-typography-label-large-font-size)` | Trigger text ramp |
+| Trigger open color | `var(--dsx-color-primary)` | Open trigger text |
+| Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
+| Chevron size | `var(--dsx-space-lg)` | Chevron icon size |
+| Chevron transition | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-in-out)` | Rotate transition |
+| Content inner padding | `var(--dsx-space-md)` | Inner content gutter |
+| Content text | `var(--dsx-color-on-surface-variant)` | Body text color |
+| Content type | `var(--dsx-typography-body-medium-font-family)`, `var(--dsx-typography-body-medium-font-size)` | Body text ramp |
+| Expand/collapse duration | `var(--dsx-motion-duration-normal)` | Keyframe duration |
+| Expand/collapse easing | `var(--dsx-motion-easing-in-out)` | Keyframe easing |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| `dsx-accordion__content` height + opacity | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | 200ms in-out (token-dependent) | `animation: none !important` via the runtime-inserted `prefers-reduced-motion` block |
+| `dsx-accordion__chevron` rotate | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | 150ms in-out (token-dependent) | Token-layer override; the chevron transition is not explicitly gated at the CSS level |
+
+## Accessibility
+
+**Roles:**
+
+- `Accordion` is rendered through Radix's `AccordionPrimitive.Root`, which exposes a region of `Disclosure`-pattern groups. The Radix primitive pairs each `Header` with its `Content` via `aria-labelledby` and `aria-controls`. The DS does not duplicate the wiring.
+- `Accordion.Header` is a heading by default (`h3`); consumers that need a different heading level should use `asChild` and supply a different element.
+- `Accordion.Trigger` is rendered as a `<button>` with the `aria-expanded` and `aria-controls` attributes Radix writes.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the next focusable element. |
+| `Shift` + `Tab` | Moves focus to the previous focusable element. |
+| `Enter`, `Space` | Activates the focused trigger and toggles the corresponding `Content`. |
+| Arrow keys | When `type="single"`, Radix navigates between triggers. Behavior is owned by Radix. |
+| `Home`, `End` | When `type="single"`, Radix focuses the first or last trigger. Behavior is owned by Radix. |
+
+**Focus:**
+
+- The trigger renders a visible focus ring via `box-shadow: var(--dsx-shadow-focus-ring)` on `:focus-visible`.
+
+**Reduced motion:**
+
+- The runtime-inserted style block disables the expand/collapse keyframes when `prefers-reduced-motion: reduce` matches. The chevron rotation is not explicitly gated; consumers should rely on the global motion token override.
+
+**Color and meaning:**
+
+- Open/closed state is communicated by `data-state`, the trigger color, the chevron rotation, and the `aria-expanded` attribute. No information is conveyed by color alone.
+
+**Naming:**
+
+- `Accordion.Trigger` is the interactive element; the consumer's `children` become the button's accessible name. `Accordion.Header` should be associated with its `Content` via Radix's pairing, not via consumer-supplied `aria-*` attributes.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Accordion` with `type="single"`, `collapsible`, and two items. Asserts the root class is `dsx-accordion` and triggers render with the chevron icon.
+
+**State story:**
+
+- Renders with `type="single"`, `defaultValue="item-1"`. Asserts the open trigger carries `data-state="open"` and the open content is visible.
+- Renders with `type="multiple"`, `defaultValue={["item-1", "item-2"]}`. Asserts both items expand at once.
+
+**Disabled story:**
+
+- Renders the root with `disabled`. Asserts every trigger is disabled and `useAccordionStyles()` reports `disabled: true` to descendants.
+
+**Composition story:**
+
+- Renders the default trigger and asserts exactly one built-in indicator.
+- Renders `indicator={false}` and a custom indicator node to demonstrate the supported ownership choices.
+- Compatibility tests keep `Accordion.ItemBody` and `Accordion.ItemIndicator` available without presenting them as the canonical composition.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Accordion does not track `data-accent-color`; the story asserts the open trigger color continues to resolve through `var(--dsx-color-primary)`.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `type` | select | `single` |
+| `collapsible` | boolean | `true` |
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-accordion`: supplies `Root` / `Item` / `Header` / `Trigger` / `Content` and the disclosure state machine.
+- `@radix-ui/react-slot`: enables `asChild` on every slot.
+- `Icon`: renders the default trailing chevron in `Accordion.Trigger` and the deprecated `Accordion.ItemIndicator`.
+
+**Used by:**
+
+- App-level FAQ, settings disclosure, and progressive-disclosure surfaces. The roster currently lists no DS components that consume `Accordion` directly; it is a leaf surface.
+
+**State boundaries:**
+
+- Owned by Accordion: the open/closed state of items, the `AccordionContext` (`density`, `disabled`), the motion styles injection, and the `dsx-accordion__*` slot classes.
+- Owned by the consumer: the `value` / `defaultValue` / `onValueChange` triplet, the `type` (single / multiple), the heading level on `Accordion.Header`, and the surrounding layout.
+
+**Boundary rules:**
+
+- App-owned data: the disclosure model (`type="single"` vs `type="multiple"`, `collapsible`), the persistent value store, and any state synchronization with the URL.
+- DS-owned visuals: token bindings, the slot classes, the motion preset, and the trigger-indicator wrapper/rotation.

package/dist/docs/alert-dialog.md

@@ -0,0 +1,313 @@
+---
+title: AlertDialog
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/alertDialog/AlertDialog.tsx
+css_path: packages/d4gger-design-system/src/styles/components/alert-dialog.css
+props_path: packages/d4gger-design-system/src/components/alertDialog/alertDialog.props.ts
+test_path: packages/d4gger-design-system/src/test/components/AlertDialog.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Dialog
+---
+
+# AlertDialog
+
+> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A high-stakes modal dialog that demands an explicit acknowledge or cancel decision before the user can return to the page. Reserve `AlertDialog` for destructive, irreversible, or commitment actions.
+
+## Anatomy & slots
+
+**Parent:** `AlertDialog` (alias of `AlertDialog.Root`). The compound is required because the alert dialog owns the trigger, overlay, content, action, and cancel parts as separate slots.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `AlertDialog.Root` | Radix `Root` | DS wrapper | Owns open state, presence context, and `PortalThemeBoundary`. `defaultOpen` defaults to `false`. |
+| `AlertDialog.Trigger` | Radix `Trigger` | DS primitive | Wires the element that opens the dialog. |
+| `AlertDialog.Portal` | Radix `Portal` (via `DialogPortal`) | DS primitive | Reuses the `Dialog` portal so the theme boundary lives in one place. |
+| `AlertDialog.Overlay` | Radix `Overlay` (via `DialogOverlay`) | DS primitive + class `dsx-alert-dialog__overlay` | Dismisses on click. Reuses `Dialog` overlay class merging. |
+| `AlertDialog.Content` | Radix `Content` wrapped in `motion.div` | DS wrapper + class `dsx-alert-dialog__content` | Hosts title, description, action, and cancel. `showClose` is forced to `false`; close affordance is the `Cancel` slot. |
+| `AlertDialog.Title` | Radix `Title` | DS primitive + class `dsx-dialog__title` | Required for the `alertdialog` accessible name. |
+| `AlertDialog.Description` | Radix `Description` | DS primitive + class `dsx-dialog__description` | Body copy. |
+| `AlertDialog.Action` | Radix `Action` | DS wrapper + class `dsx-alert-dialog__action` | Confirms the action; closes the dialog. |
+| `AlertDialog.Cancel` | Radix `Cancel` | DS primitive + class `dsx-alert-dialog__cancel` | Dismisses without committing. |
+
+## Props contract
+
+**Root props (`AlertDialog`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `defaultOpen` | `boolean` | `false` | no | Initial open state when uncontrolled. | no |
+| `open` | `boolean` | `undefined` | no | Controlled open state. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slot content. | no |
+
+`AlertDialog.Root` mirrors the Radix root type. All other Radix root props pass through.
+
+**Content props (`AlertDialog.Content`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Width band. Writes `data-size` and modifier class. | no |
+| `width` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-width`. | yes |
+| `minWidth` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-min-width`. | yes |
+| `maxWidth` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-max-width`. | yes |
+| `height` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-height`. | yes |
+| `minHeight` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-min-height`. | yes |
+| `maxHeight` | `string` | `undefined` | no | CSS custom property `--dsx-dialog-content-custom-max-height`. | yes |
+| `onOpenAutoFocus` | `(event: Event) => void` | `undefined` | no | Radix `onOpenAutoFocus` event. | no |
+| `onCloseAutoFocus` | `(event: Event) => void` | `undefined` | no | Radix `onCloseAutoFocus` event. | no |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | `undefined` | no | Radix escape handler. | no |
+| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | `undefined` | no | Radix pointer handler. | no |
+| `onInteractOutside` | `(event: Event) => void` | `undefined` | no | Radix interact handler. | no |
+| `forceMount` | `boolean` | `undefined` | no | Forces the content to stay mounted while closed. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Title, description, action, cancel. | no |
+
+`AlertDialog.Content` does not accept `showClose`. The internal default is `false`; the package forces the close button off so consumers must wire `AlertDialog.Cancel` deliberately.
+
+**Action props (`AlertDialog.Action`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'primary' \| 'destructive'` | `'primary'` | no | Color treatment. Writes `data-variant`. | no |
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`; consumer supplies the element. | no |
+
+`AlertDialog.Action` forwards the rest of the Radix `Action` props (for example `onClick`).
+
+**Cancel, Title, Description props:**
+
+Each slot accepts the standard Radix props for that part. None of the slots expose a `size`, `variant`, or any DS-only prop besides the action's `variant`.
+
+Rules:
+
+- `size`, `width`, `minWidth`, `maxWidth`, `height`, `minHeight`, and `maxHeight` are wired through `extractProps` and the `alertDialogContentPropDefs` bag. Mismatches between this table and `alertDialog.props.ts` fail `qa:contracts`.
+- `variant` and `asChild` on `AlertDialog.Action` are wired through `extractProps` and the `alertDialogActionPropDefs` bag.
+
+## CSS class contract
+
+**Root class:** `dsx-alert-dialog` (used implicitly through the `Dialog` shared `dsx-dialog__*` chain and the `dsx-alert-dialog__content` modifier).
+
+**Modifier classes** (driven by the prop def bag, applied through `extractProps`):
+
+| Prop | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `size` (on `AlertDialog.Content`) | `sm`, `md`, `lg` | `.dsx-alert-dialog__content[data-size='sm']`, `[data-size='md']`, `[data-size='lg']` | `alert-dialog.css` |
+| `variant` (on `AlertDialog.Action`) | `primary`, `destructive` | `.dsx-alert-dialog-action-variant-primary`, `.dsx-alert-dialog-action-variant-destructive` | `alert-dialog.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `AlertDialog.Content` | `dsx-alert-dialog__content` | `alert-dialog.css` |
+| `AlertDialog.Title` | `dsx-dialog__title` | `dialog.css` (shared) |
+| `AlertDialog.Description` | `dsx-dialog__description` | `dialog.css` (shared) |
+| `AlertDialog.Action` | `dsx-alert-dialog__action` | `alert-dialog.css` |
+| `AlertDialog.Cancel` | `dsx-alert-dialog__cancel` | `alert-dialog.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `width`, `minWidth`, `maxWidth`, `height`, `minHeight`, and `maxHeight` are `responsive: true`; the `extractProps` runtime emits breakpoint-prefixed CSS custom properties.
+- `size` is a single value, not responsive.
+
+**Reduced motion:**
+
+- The `motion.div` in `DialogContent` collapses to `MOTION_TRANSITIONS.reduced` when `usePrefersReducedMotion` matches.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Action background (`primary`) | `var(--dsx-color-primary)` | Default confirm action. |
+| Action color (`primary`) | `var(--dsx-color-on-primary)` | Confirm action label. |
+| Action background (`destructive`) | `var(--dsx-color-error)` | Destructive confirm. |
+| Action color (`destructive`) | `var(--dsx-color-on-error)` | Destructive label. |
+| Cancel background | `transparent` | Ghost cancel. |
+| Cancel color | `var(--dsx-color-on-surface)` | Default label. |
+| Cancel border | `var(--dsx-color-outline)` | Edge. |
+| Action padding | `var(--dsx-space-sm) var(--dsx-space-md)` | Internal gutter. |
+| Action min height | `var(--dsx-size-xl)` | Tap target. |
+| Action radius | `var(--dsx-rounded-full)` | Pill shape. |
+| Hover overlay (cancel) | `var(--dsx-effect-hover-ghost)` | Hover state. |
+| Hover color (cancel) | `var(--dsx-color-primary)` | Hover state. |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus. |
+| Transition tokens | `var(--dsx-motion-duration-fast)`, `var(--dsx-motion-easing-standard)` | Color transition. |
+| Title typography | `var(--dsx-typography-headline-medium-*)` | Title. |
+| Description typography | `var(--dsx-typography-body-medium-*)` | Description. |
+| Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
+| Content width (`sm`) | `min(calc(100vw - var(--dsx-dialog-viewport-gap)), var(--dsx-dialog-content-width-sm))` | Compact alert. |
+| Content width (`lg`) | `min(calc(100vw - var(--dsx-dialog-viewport-gap)), var(--dsx-dialog-content-width-lg))` | Wide alert. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `alert-dialog.css`.
+- Alert dialog reuses `Dialog` for the base overlay, content, and theme mirroring. Token changes to overlay or content go in `dialog.css`.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Content scale and opacity | `MOTION_TRANSITIONS.dialog` (inherited from `Dialog.Content`) | `duration.normal`, `ease.emphasized` | `MOTION_TRANSITIONS.reduced` |
+| Action color transitions | `var(--dsx-motion-duration-fast)`, `var(--dsx-motion-easing-standard)` | `150ms ease` | inherits `prefers-reduced-motion` via the same tokens |
+
+The action button has a CSS transition for `background-color`, `border-color`, `box-shadow`, and `color`. The transition respects the same motion tokens used across the system. The scale-and-fade mount animation lives in `DialogContent` and gates on `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- `AlertDialog.Content` renders a Radix `Content` that exposes `role="alertdialog"`. The `aria-modal` attribute is set on the inner content by `DialogContent`. The `aria-labelledby` reference comes from `AlertDialog.Title` and `aria-describedby` from `AlertDialog.Description`.
+- `AlertDialog.Action` and `AlertDialog.Cancel` render `<button>` elements via Radix. They participate in the standard focus trap.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the next focusable element inside the dialog. Focus is trapped while the dialog is open. |
+| `Shift` + `Tab` | Moves focus to the previous focusable element. |
+| `Enter`, `Space` | Activates the focused action or cancel button. |
+| `Escape` | Closes the dialog (Radix default). |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-shadow-focus-ring)` on action and cancel buttons.
+- Focus is trapped inside the dialog while open. Focus returns to the trigger on close.
+- `onOpenAutoFocus` and `onCloseAutoFocus` are forwarded for apps that need to override focus management.
+
+**Reduced motion:**
+
+- Mount and exit motion collapses to `MOTION_TRANSITIONS.reduced` when `prefers-reduced-motion: reduce` matches.
+
+**Color and meaning:**
+
+- The action variant (`primary` vs `destructive`) is communicated by color plus the visible label. The label is the source of truth; do not rely on color alone.
+
+**Naming:**
+
+- `AlertDialog.Title` is required for the accessible name. `AlertDialog.Description` provides a longer description. The action and cancel buttons must have visible labels; the default close affordance is intentionally disabled so consumers always wire `AlertDialog.Cancel` with explicit copy.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders an `AlertDialogRoot` with a destructive trigger button. The content shows a title, description, cancel, and action. Asserts the root class is `dsx-alert-dialog__content` on the content wrapper and the action has `data-variant="primary"` by default.
+
+**Size story** (one per size value):
+
+- Renders `AlertDialogContent` with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size` on the content.
+
+**Action variant story** (one per variant):
+
+- Renders `AlertDialogAction` with `variant="primary"` and `variant="destructive"`. Asserts `data-variant` on the action.
+
+**Composition story:**
+
+- Renders every slot in a single composition: `Root`, `Trigger`, `Content`, `Title`, `Description`, `Action`, `Cancel`. Asserts each slot renders the right class.
+
+**State story:**
+
+- Opens the dialog from the trigger using `userEvent`. Asserts the `alertdialog` role appears, and dismisses via the `Cancel` slot.
+
+**A11y story:**
+
+- Uses `vitest-axe` against an open dialog. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `width` | text | (empty) |
+| `minWidth` | text | (empty) |
+| `maxWidth` | text | (empty) |
+| `height` | text | (empty) |
+| `minHeight` | text | (empty) |
+| `maxHeight` | text | (empty) |
+
+`AlertDialog.Action` exposes `variant` as a `select` between `primary` and `destructive`.
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-alert-dialog`: provides the dialog state, focus trap, and the `Title` / `Description` / `Action` / `Cancel` primitives.
+- `@radix-ui/react-slot`: enables `asChild` on `AlertDialog.Action`.
+- `Dialog` (from `../dialog/Dialog`): the content, overlay, and portal are reused so the theme mirror, motion preset, and overlay class merging live in one place. `AlertDialog` does not duplicate the portal or overlay plumbing.
+
+**Used by:**
+
+- Destructive flows: account deletion, sign-out confirmation, irreversible record removal, hard reset.
+- High-stakes commitments: subscription downgrade with loss of features, profile merge, data export with side effects.
+
+**State boundaries:**
+
+- Owned by `AlertDialog`: open state when uncontrolled, presence context, portal theme mirroring, and motion preset.
+- Owned by the consumer: the title copy, the description copy, the action label, the cancel label, and the actual destructive handler on `AlertDialog.Action`.
+
+**Boundary rules:**
+
+- App-owned data: the destructive operation, the affected entity, the confirmation copy, the analytics event.
+- DS-owned visuals: the overlay, the content frame, the action and cancel button styles, the focus ring, the motion preset.
+
+## Penpot build recipe
+
+The content frame, overlay, and title typography mirror `Dialog`. The action and cancel button styles are specific to `AlertDialog` and the destructive variant swaps the action palette to `var(--dsx-color-error)`.
+
+### Root board
+
+- **Name**: `Components / AlertDialog`.
+- **Dimensions**: `420 × 220` (default `size="md"`).
+- **Layout**: `Flex`, vertical.
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board>
+  ├── <Overlay rect, var(--dsx-z-index-overlay)>
+  └── <Content frame>
+        ├── <Title text>
+        ├── <Description text>
+        └── <Action row>
+              ├── <Action button (primary | destructive)>
+              └── <Cancel button>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | radius | `var(--dsx-rounded-xl)` | Radius | `borderRadius` |
+| `<Action button (destructive)>` | fill | `var(--dsx-color-error)` | Color | `fills` |
+| `<Action button (destructive)>` | text fill | `var(--dsx-color-on-error)` | Color | `fills` |
+| `<Cancel button>` | stroke | `var(--dsx-color-outline)` | Color | `strokes` |
+| `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
+
+### State transformations
+
+| State | Action fill | Action text | Cancel fill | Cancel text |
+|---|---|---|---|---|
+| `default` | `var(--dsx-color-primary)` (or `var(--dsx-color-error)` for destructive) | `var(--dsx-color-on-primary)` (or `var(--dsx-color-on-error)`) | `transparent` | `var(--dsx-color-on-surface)` |
+| `hover (destructive)` | `var(--dsx-color-error-container)` | `var(--dsx-color-on-error-container)` | `var(--dsx-effect-hover-ghost)` | `var(--dsx-color-primary)` |
+| `focus-visible` | `var(--dsx-color-primary)` + `var(--dsx-shadow-focus-ring)` | `var(--dsx-color-on-primary)` | `var(--dsx-shadow-focus-ring)` | `var(--dsx-color-on-surface)` |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `action.variant`: `primary`, `destructive`. Default `primary`.
+- Total members: `3 * 2 = 6`.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.