@d4gger/design-system 2.7.0

package/dist/docs/popover.md

@@ -0,0 +1,312 @@
+---
+title: Popover
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/popover/Popover.tsx
+css_path: packages/d4gger-design-system/src/styles/components/popover.css
+props_path: packages/d4gger-design-system/src/components/popover/popover.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Popover.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: []
+---
+
+# Popover
+
+> 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
+
+An interactive floating surface anchored to a trigger. `Popover` is more interactive than `Tooltip` (it accepts form controls and links) and less blocking than `Dialog`. Use it for pickers, filters, and inline editors that must stay open while the user works.
+
+## Anatomy & slots
+
+**Parent:** `Popover` (alias of `Popover.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Popover.Root` | Radix `Root` | DS wrapper | Owns open state and the `PortalThemeBoundary`. |
+| `Popover.Trigger` | Radix `Trigger` | DS primitive | Element that toggles the popover. |
+| `Popover.Anchor` | Radix `Anchor` | DS primitive | Optional alternative anchor for positioning. |
+| `Popover.Positioner` | `<div>` (or `Slot` when `asChild`) | DS primitive + class `dsx-popover__positioner` | Optional layout hint for `side` and `align`. |
+| `Popover.Arrow` | `<svg>` (or `Slot` when `asChild`) | DS primitive + class `dsx-popover__arrow` | Optional pointer. |
+| `Popover.Content` | Radix `Content` wrapped in `motion.div` | DS wrapper + class `dsx-popover__content` | Hosts the body. Auto-wires `aria-labelledby` and `aria-describedby` to `Popover.Title` and `Popover.Description` via `useId`. |
+| `Popover.Title` | `<h3>` | DS primitive + class `dsx-popover__title` | Optional heading. Wired to the `aria-labelledby` of `Content` when present. |
+| `Popover.Description` | `<p>` | DS primitive + class `dsx-popover__description` | Optional body copy. Wired to the `aria-describedby` of `Content` when present. |
+| `Popover.Close` | Radix `Close` | DS primitive + class `dsx-popover__close` | Closes the popover. |
+
+## Props contract
+
+**Root props (`Popover`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `defaultOpen` | `boolean` | `undefined` | 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 |
+
+**Content props (`Popover.Content`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size band. Writes `data-size`. | no |
+| `showArrow` | `boolean` | `false` | no | Whether the arrow is rendered. Writes `data-show-arrow`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`; consumer supplies the element. | no |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `undefined` | no | Radix side. | no |
+| `sideOffset` | `number` | `8` | no | Offset from the trigger. | no |
+| `align` | `'start' \| 'center' \| 'end'` | `undefined` | no | Radix align. | no |
+| `alignOffset` | `number` | `undefined` | no | Radix align offset. | no |
+| `forceMount` | `boolean` | `false` | no | Mount the content unconditionally. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Popover body. | no |
+
+**Positioner props (`Popover.Positioner`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | no | Side hint. Writes `data-side`. | no |
+| `sideOffset` | `number` | `8` | no | Offset from the trigger. | no |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | no | Align hint. Writes `data-align`. | no |
+| `alignOffset` | `number` | `0` | no | Align offset. | no |
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Positioner content. | no |
+
+**Arrow props (`Popover.Arrow`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `width` | `number` | `10` | no | SVG width. | no |
+| `height` | `number` | `5` | no | SVG height. | no |
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`. | no |
+
+**Title and Description props:**
+
+`Popover.Title` and `Popover.Description` accept the standard React props for `<h3>` and `<p>`. They expose `id` for explicit override; the default `id` comes from a `React.useId()` value inside `Popover.Content`.
+
+**Close props:**
+
+`Popover.Close` accepts the standard Radix `Close` props.
+
+Rules:
+
+- `size`, `showArrow`, and `asChild` are wired through `extractProps` and the `popoverContentPropDefs` bag. Mismatches between this table and `popover.props.ts` fail `qa:contracts`.
+- The DS does not invent a `variant` prop on `Popover`. The popover stays single-styled; size and arrow presence carry the visible variance.
+
+## CSS class contract
+
+**Root class:** `dsx-popover` (implicit; the visible root is the `Content` wrapper).
+
+**Modifier classes** (driven by `data-*` attributes):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-popover__content[data-size='sm']`, `[data-size='md']`, `[data-size='lg']` | `popover.css` |
+| `data-show-arrow` | `true`, `false` | `.dsx-popover__content[data-show-arrow='true']` | `popover.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Popover.Content` | `dsx-popover__content` | `popover.css` |
+| `Popover.Title` | `dsx-popover__title` | `popover.css` |
+| `Popover.Description` | `dsx-popover__description` | `popover.css` |
+| `Popover.Close` | `dsx-popover__close` | `popover.css` |
+| `Popover.Positioner` | `dsx-popover__positioner` | `popover.css` |
+| `Popover.Arrow` | `dsx-popover__arrow` | `popover.css` |
+
+`Popover.Trigger` and `Popover.Anchor` have no DS class; the Radix primitives are used directly.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Size is single-value only; the prop def is not `responsive: true`.
+
+**Reduced motion:**
+
+- The `motion.div` in `Popover.Content` collapses to opacity-only transitions on `MOTION_TRANSITIONS.reduced` when `usePrefersReducedMotion` matches. The default preset is `MOTION_TRANSITIONS.popover`.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Content background | (inherited from `baseDialog.css`) | Surface for the popover. |
+| Content border radius | `var(--dsx-rounded-lg)` | Rounded corners. |
+| Content padding | `var(--dsx-space-md)` | Internal gutter. |
+| Content gap | `var(--dsx-space-md)` | Vertical rhythm. |
+| Content min width | `var(--dsx-popover-min-width)` | Min surface width. |
+| Content max width | `min(var(--dsx-popover-max-width), calc(100vw - var(--dsx-dialog-viewport-gap)))` | Cap on the wider side. |
+| Show-arrow overflow | `overflow: visible` | Allows the arrow to escape the rounded frame. |
+| 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. |
+| Positioner z-index | `var(--dsx-z-index-popover, 50)` | Stacking. |
+| Close button size | `var(--dsx-size-lg)` | Square tap target. |
+| Close button radius | `var(--dsx-rounded-full)` | Round close. |
+| Motion duration | `var(--dsx-motion-duration-*)` | Mount and exit. |
+| Motion easing | `var(--dsx-motion-easing-*)` | Mount and exit. |
+
+Rules:
+
+- The content background and surface tokens come from `baseDialog.css` (the shared overlay surface).
+- No raw color, spacing, radius, or motion values in `popover.css`.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Content mount and exit | `MOTION_TRANSITIONS.popover` | opacity 0 to 1, y 4 to 0 | opacity only on `MOTION_TRANSITIONS.reduced` |
+
+## Accessibility
+
+**Roles:**
+
+- `Popover.Content` renders a Radix `Content` that is non-modal by default. Consumers decide whether to add `role="dialog"` for a focused popover.
+- `aria-labelledby` and `aria-describedby` are wired automatically when `Popover.Title` or `Popover.Description` is present. The `id` for each comes from `React.useId()` inside `Popover.Content`. Consumers can override `id` explicitly when needed.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through the popover body. |
+| `Shift` + `Tab` | Moves focus backward. |
+| `Enter`, `Space` | Activates the focused control inside the popover. |
+| `Escape` | Closes the popover. |
+
+**Focus:**
+
+- The trigger retains focus while the popover is open. Focus is not trapped.
+- The trigger's `aria-expanded` reflects the open state through Radix.
+
+**Reduced motion:**
+
+- Mount and exit motion collapses to opacity-only fades on `prefers-reduced-motion: reduce`.
+
+**Color and meaning:**
+
+- The popover does not communicate state by color alone. Any status indicator inside the popover must carry a label or icon.
+
+**Naming:**
+
+- `Popover.Trigger` should have a meaningful label. Icon-only triggers require `aria-label`.
+- When `Popover.Title` is omitted, the popover must still have an accessible name. Use `aria-label` on the trigger or on the content wrapper.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `PopoverRoot` with a `Trigger` and `Content`. Asserts the content has `dsx-popover__content` and `data-size="md"`.
+
+**Size story** (one per size value):
+
+- Renders `Popover.Content` with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size`.
+
+**Arrow story:**
+
+- Renders `Popover.Content` with `showArrow={true}`. Asserts `data-show-arrow="true"` and the Radix `Arrow` element is rendered.
+- Renders `Popover.Arrow` with `width={16}` and `height={8}`. Asserts the SVG attributes.
+
+**Title and Description story:**
+
+- Renders `Popover.Content` with `Popover.Title` and `Popover.Description`. Asserts the `aria-labelledby` and `aria-describedby` on the content match the `id` on the title and description.
+
+**Positioner story:**
+
+- Renders `Popover.Positioner` with `side="top"`, `align="end"`. Asserts `data-side` and `data-align` on the positioner element.
+
+**Close story:**
+
+- Opens the popover with `userEvent.click`. Asserts the body appears, then dismisses with the `Escape` key.
+
+**Composition story:**
+
+- Renders every slot: `Root`, `Trigger`, `Content`, `Title`, `Description`, `Close`. Asserts each slot renders the right class.
+
+**A11y story:**
+
+- Uses `vitest-axe` against an open popover. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `showArrow` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-popover`: provides the open state machine, the `Trigger` host, the portal, and the positioner.
+- `@radix-ui/react-slot`: enables `asChild` on the positioner, arrow, and content.
+- `framer-motion`: provides the `motion.div` for mount and exit. The reduced motion preset is read from `usePrefersReducedMotion`.
+- `baseDialog.css`: the shared overlay surface and theme-mirror utilities.
+
+**Used by:**
+
+- Filter popovers on table and list headers.
+- Inline editors in cards, list rows, and table cells.
+- Menu-style pickers that need a small floating surface (prefer `DropdownMenu` for the canonical menu anatomy).
+
+**State boundaries:**
+
+- Owned by `Popover`: open state when uncontrolled, presence context, portal theme mirroring, motion preset, and the auto-wired `aria-labelledby` / `aria-describedby`.
+- Owned by the consumer: the trigger label, the popover body, and the close behavior (via `Popover.Close` or `Escape`).
+
+**Boundary rules:**
+
+- App-owned data: the picker options, the inline edit value, the trigger surface.
+- DS-owned visuals: surface tokens, padding, radius, motion, positioner layout hints.
+
+## Penpot build recipe
+
+### Root board
+
+- **Name**: `Components / Popover`.
+- **Dimensions**: `320 × 200` (default `size="md"`).
+- **Layout**: `Flex`, vertical.
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board>
+  ├── <Trigger button>
+  ├── <Content frame>
+  │     ├── <Title text>
+  │     ├── <Description text>
+  │     └── <Body area>
+  └── <Arrow svg> (optional)
+```
+
+### 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-lg)` | Radius | `borderRadius` |
+| `<Content frame>` | spacing | `var(--dsx-space-md)` | Spacing | `padding` |
+| `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
+| `<Description text>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |
+| `<Arrow svg>` | fill | `currentColor` | Color | `fills` |
+
+### State transformations
+
+| State | Content fill | Content shadow |
+|---|---|---|
+| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-2)` |
+| `open` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `showArrow`: `true`, `false`. Default `false`.
+- 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.

package/dist/docs/progress.md

@@ -0,0 +1,296 @@
+---
+title: Progress
+status: canonical
+category: Primitives
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/progress/Progress.tsx
+css_path: packages/d4gger-design-system/src/styles/components/progress.css
+props_path: packages/d4gger-design-system/src/components/progress/progress.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Progress.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/display.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - '@radix-ui/react-progress (Root + Indicator, internal)'
+---
+
+# Progress
+
+> 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 determinate progress indicator for known-duration work. The public `Progress` is a single export that internally composes the Radix progress primitive's `Root` and `Indicator` to render a filled track. For indeterminate loading, use `Spinner` instead.
+
+## Anatomy & slots
+
+**Parent:** `Progress` (single public export; the Radix `Indicator` is not exposed as a public subcomponent).
+
+**Slots:**
+
+No public subcomponents. The component renders a single Radix `ProgressPrimitive.Root` host that contains:
+
+| Internal region | Element | Renders | Notes |
+|---|---|---|---|
+| Track | `<ProgressPrimitive.Root>` | `dsx-progress` + size, variant, accent, radius, and complete data attributes | The outer bar. |
+| Filled region | `<ProgressPrimitive.Indicator>` | `dsx-progress__indicator` with `transform: translateX(-{remaining}%)` | The filled portion; width tracks the ratio. |
+
+The `Indicator` is internal. The public surface is a single `Progress` component. The `value` prop and the `value` / `max` ratio drive the indicator transform internally.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the track through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `highContrast` | `boolean` | `false` | no | When true, writes `data-high-contrast="true"` on the track. | no |
+| `indicatorClassName` | `string` | `undefined` | no | Extra classes appended to `dsx-progress__indicator`. | no |
+| `value` | `number \| null` | `0` | no | Current progress value. The indicator width is computed as `clamp(value, 0, max) / max`. | no |
+| `max` | `number` | `100` | no | Maximum progress value. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Maps to `data-size` on the track and selects a height token. | no |
+| `variant` | `'default' \| 'indeterminate'` | `'default'` | no | Default renders a filled track. `indeterminate` triggers a left-to-right-to-left sliding animation. | no |
+| `color` | `'primary' \| 'primary-container' \| 'secondary' \| 'secondary-container' \| 'tertiary' \| 'tertiary-container' \| 'success' \| 'success-container' \| 'error' \| 'error-container' \| 'surface' \| 'surface-raised' \| 'surface-overlay' \| 'surface-sunken' \| 'background' \| 'outline' \| 'outline-variant'` | `undefined` | no | Free-form accent color name forwarded to `data-accent-color`. | yes (initial, xs, sm, md, lg, xl, 2xl) |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | `'full'` | no | Maps to `data-radius` on the track. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-progress`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the track. | no |
+
+Rules that apply to this row:
+
+- The component spreads `PrimitiveProgressProps` (from `Progress.radix.tsx`) into the public type, so any standard Radix `Root` attribute (`aria-label`, `aria-valuetext`, `aria-valuemin`, etc.) is available.
+- `color` is `responsive: true` in the prop def. The runtime forwards the value verbatim; responsive prefixes land on the same track through `extractProps`.
+- `radius` is the only override for the track's `border-radius`; the default is `full`.
+- `value` and `max` are the only props that drive the indicator width. When `value` reaches `max`, the track takes the `dsx-progress--complete` modifier class and the indicator switches to the success color token.
+- The `indeterminate` variant animates the indicator with the `dsx-progress-indeterminate` keyframes; the runtime does not need a separate `value` range for it.
+
+## CSS class contract
+
+**Root class:** `dsx-progress`
+
+**Internal indicator class:** `dsx-progress__indicator`
+
+**Modifier classes** (driven by `data-*` attributes and the completion state):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-progress[data-size='sm']`, `.dsx-progress[data-size='md']`, `.dsx-progress[data-size='lg']` | `progress.css` |
+| `data-variant` | `default`, `indeterminate` | `.dsx-progress[data-variant='indeterminate']` | `progress.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full` | `.dsx-progress[data-radius='...']` | `progress.css` |
+| `data-accent-color` | (any color token name) | `.dsx-progress[data-accent-color='...']` | `progress.css` |
+| `data-high-contrast` | `true` | `.dsx-progress[data-high-contrast='true']` | `progress.css` |
+| (no attribute) | (presence) | `.dsx-progress--complete` (applied when `value >= max`) | `progress.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| Filled region | `dsx-progress__indicator` | `progress.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. The track is breakpoint-agnostic. Responsive `color` values are emitted through `extractProps` when the prop def has `responsive: true`.
+
+**Reduced motion:**
+
+- The CSS file turns the `indeterminate` animation off inside `@media (prefers-reduced-motion: reduce)` by setting `animation: none` on the indicator. The track's transition is the only motion in the determinate path; it is not gated by a CSS class but the global `prefers-reduced-motion` block in `input.css` covers shell-style transitions for the same family of components. Progress itself does not import the global block, so the indicator's `transform` transition (`var(--dsx-motion-duration-fast)`) runs even when reduced motion is requested. Consumers that need to gate determinate motion should set their own media-query overrides.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Track background | `var(--dsx-color-surface)` | Empty portion of the bar. |
+| Indicator background (default) | `var(--dsx-color-primary)` | Filled portion of the bar in the `primary` accent. |
+| Indicator background (success) | `var(--dsx-color-success)` | Filled portion when `value >= max` or when the success accent is set. |
+| Indicator background (error) | `var(--dsx-color-error)` | Filled portion for the `error` accent. |
+| Indicator background (secondary) | `var(--dsx-color-secondary)` | Filled portion for the `secondary` accent. |
+| Indicator background (tertiary) | `var(--dsx-color-tertiary)` | Filled portion for the `tertiary` accent. |
+| Track height (md) | `var(--dsx-progress-height)` (default 8px) | Default bar height. |
+| Track height (sm) | `var(--dsx-progress-height-sm)` (default 4px) | Small bar height. |
+| Track height (lg) | `var(--dsx-progress-height-lg)` (default 12px) | Large bar height. |
+| Border radius | `var(--dsx-rounded-full)` default, plus `data-radius` overrides | Track roundness. |
+| Transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Indicator transform on `value` change. |
+| Indeterminate animation | `var(--dsx-motion-easing-in-out)` | Indeterminate variant animation. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `progress.css`. The color tokens cover the documented accent list; new accent colors need a token first.
+- The complete state is a single token swap to `--dsx-color-success`. It is not a separate `data-complete` attribute; the runtime computes it from the `value` vs `max` ratio.
+- Alpha is not used. All painted values are solid.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Indicator transform | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | `transform: translateX(-{remaining}%)` on `value` change | Relies on the global `prefers-reduced-motion` block. Progress does not currently gate this transform in CSS. |
+| Indeterminate animation | `var(--dsx-motion-easing-in-out)` (1.5s infinite) | `dsx-progress-indeterminate` keyframes | `animation: none` via the reduced-motion block. |
+
+Rules:
+
+- Progress does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. The motion is plain CSS, sourced from the duration and easing tokens.
+- The `indeterminate` animation respects `prefers-reduced-motion` through a dedicated `@media` block in `progress.css`. The transform transition does not have a dedicated reduced-motion block; it is meant to be sub-200ms and is typically acceptable.
+
+## Accessibility
+
+**Roles:**
+
+- `role="progressbar"` is written by `@radix-ui/react-progress` on the track. The runtime sets `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` based on `value` and `max`.
+
+**Keyboard:**
+
+- Progress is not interactive. No keyboard contract beyond the page-level Tab order. The track is intentionally not focusable.
+
+**Focus:**
+
+- Progress has no interactive surface. Focus management is the consumer's responsibility. The track does not show a focus ring.
+
+**Reduced motion:**
+
+- The indeterminate animation is paused inside `@media (prefers-reduced-motion: reduce)`. The determinate transform transition is not gated in CSS.
+
+**Color and meaning:**
+
+- The `complete` state is communicated by the success color plus the visible full bar. The `value` and `max` are also exposed through `aria-valuenow` and `aria-valuemax` for assistive tech, so the meaning is not color-only.
+- The `color` prop swaps the indicator color, but the bar's filled ratio is the same source of truth.
+
+**Naming:**
+
+- The component does not generate an accessible name. Pair it with `aria-label`, `aria-labelledby`, or visible text so screen readers can announce what the bar tracks. The runtime accepts `aria-label` and forwards it to the track.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Progress` with `value={60}`. Asserts the track has `dsx-progress`, `data-size="md"`, `data-variant="default"`, and `aria-valuenow="60"`.
+
+**Variant story** (one per variant):
+
+- Renders Progress with `variant="default"` and `variant="indeterminate"`. Asserts the matching `data-variant` attribute on the track.
+
+**Size story** (one per size):
+
+- Renders Progress with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` value and the matching height token via the rendered bar.
+
+**Color story** (one per accent):
+
+- Renders Progress with `color="primary"`, `color="secondary"`, `color="tertiary"`, `color="success"`, and `color="error"`. Asserts the matching `data-accent-color` attribute on the track.
+
+**Radius story** (one per radius value):
+
+- Renders Progress with `radius="none"`, `radius="sm"`, `radius="md"`, `radius="lg"`, `radius="xl"`, `radius="2xl"`, and `radius="full"`. Asserts the matching `data-radius` attribute on the track.
+
+**State story:**
+
+- Renders Progress with `value={100}` and asserts the `dsx-progress--complete` modifier class is on the track.
+- Renders Progress with `value={50}` and asserts the modifier class is absent.
+- Renders Progress with `highContrast` and asserts `data-high-contrast="true"` is on the track.
+
+**Composition story** (for `asChild`):
+
+- Renders Progress with `asChild` wrapping a custom track. Asserts the host is the consumer's element and the `dsx-progress` class is preserved.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the indicator color tracks the wrapper accent. Renders a separate `Progress` with `color="error"` and asserts `data-accent-color="error"`.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a rendered default Progress. Asserts there are no axe violations and the progressbar role has an accessible name.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `value` | number (slider) | `60` |
+| `max` | number | `100` |
+| `size` | select (`sm`, `md`, `lg`) | `md` |
+| `variant` | select (`default`, `indeterminate`) | `default` |
+| `color` | select (color values + free text) | (none) |
+| `radius` | select (`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`) | `full` |
+| `highContrast` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-progress` (`Root` + `Indicator`): provides the `role="progressbar"` semantics, the `aria-valuenow` / `aria-valuemax` reflection, and the indicator transform contract.
+- `@radix-ui/react-slot`: enables `asChild` for the track.
+
+**Used by:**
+
+- `Stepper` (composite multi-step wizard): the `Indicator` slot reuses Progress's visual rhythm.
+- App-level upload, download, and loading flows where the work has a known duration.
+
+**State boundaries:**
+
+- Owned by Progress: the track chrome, the data attributes, the indicator transform, the `complete` modifier class, and the `aria-valuenow` reflection.
+- Owned by the consumer: the `value`, the `max`, the `aria-label`, the high-contrast flag, and the host element when `asChild` is set.
+
+**Boundary rules:**
+
+- App-owned data: the actual progress value, the maximum, and the label that names the bar.
+- DS-owned visuals: token bindings for track surface, indicator color (including the success and error accents), height tokens per size, and the indeterminate animation.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for Progress. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Primitives / Progress`.
+- **Dimensions**: `240 × 8` (md).
+- **Layout**: `Fixed`.
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: Progress / md / default>
+  ├── <Frame: track (background)>
+  └── <Frame: filled region (transform: translateX(...))>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Track | fill | `--dsx-color-surface` | Color | `fills` |
+| Track | radius | `--dsx-rounded-full` | Radius | `radius` |
+| Indicator | fill | `--dsx-color-primary` | Color | `fills` |
+| Indicator (success) | fill | `--dsx-color-success` | Color | `fills` (state) |
+| Indicator (error) | fill | `--dsx-color-error` | Color | `fills` (state) |
+| Indicator (secondary) | fill | `--dsx-color-secondary` | Color | `fills` (state) |
+| Indicator (tertiary) | fill | `--dsx-color-tertiary` | Color | `fills` (state) |
+| Track (sm) | height | `--dsx-progress-height-sm` | Sizing | `size` |
+| Track (md) | height | `--dsx-progress-height` | Sizing | `size` |
+| Track (lg) | height | `--dsx-progress-height-lg` | Sizing | `size` |
+
+### State transformations
+
+| State | Track fill | Indicator fill | Indicator transform |
+|---|---|---|---|
+| `default` | `--dsx-color-surface` | `--dsx-color-primary` | `translateX(-{100 - ratio*100}%)` |
+| `complete` | `--dsx-color-surface` | `--dsx-color-success` | `translateX(0%)` |
+| `indeterminate` | `--dsx-color-surface` | `--dsx-color-primary` | `dsx-progress-indeterminate` keyframes |
+| `error` | `--dsx-color-surface` | `--dsx-color-error` | ratio-based transform |
+| `high-contrast` | `--dsx-color-surface` | `--dsx-color-primary` (token-saturated) | ratio-based transform |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `default`, `indeterminate`. Default `default`.
+- `radius`: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`. Default `full`.
+- `color`: the documented accent list plus `undefined`. Default `undefined`.
+- `highContrast`: `true`, `false`. Default `false`.
+- `asChild`: `true`, `false`. Default `false`.
+- Total members: 252 (3 × 2 × 7 × 3 × 2 × 2).
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Primitives`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] The `complete` state swaps to the success color; document the swap, do not treat it as a separate variant.
+- [ ] The `indeterminate` animation is motion-token-driven; document the duration and easing in the board metadata.

package/dist/docs/prose.md

@@ -0,0 +1,26 @@
+---
+title: Prose
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/prose/Prose.tsx
+css_path: packages/d4gger-design-system/src/styles/components/prose.css
+---
+
+# Prose
+
+## Purpose
+
+Read-side article typography with an approximately `68ch` measure and `1.65` reading line height. It styles semantic headings, paragraphs, links, lists, blockquotes, inline and block code, figures, captions, images, tables, and authored blocks.
+
+## API and security
+
+`Prose` accepts semantic React children or `html`. The `html` value must already be sanitized by the consumer. The design system does not sanitize and never declares untrusted HTML safe.
+
+## Accessibility
+
+Consumers preserve heading order, stable IDs, meaningful image alt text, captions, and table headers. Wide tables scroll horizontally rather than hiding data.
+
+## Playground demo spec
+
+Render all supported semantic elements, sanitized HTML, a wide table at mobile width, and each exported authored-node renderer.