@d4gger/design-system 2.7.0

package/dist/docs/status.md

@@ -0,0 +1,280 @@
+---
+title: Status
+status: canonical
+category: Components
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/status/Status.tsx
+css_path: packages/d4gger-design-system/src/styles/components/status.css
+props_path: packages/d4gger-design-system/src/components/status/status.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Status.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on: []
+---
+
+# Status
+
+> 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 compact status indicator dot that paints a single semantic color across seven variants — five presence states plus two node-health states (`degraded`, `maintenance`) — with a size scale and an optional pulse animation for live states.
+
+## Anatomy & slots
+
+**Parent:** `Status` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a single `<span>` host element (or a slotted child when `asChild` is set). Status is a non-text indicator; it intentionally does not render any visible body. The semantic state is communicated by the dot's color, by the `data-pulse` animation when present, and by the consumer-supplied `aria-label` or surrounding text.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'online' \| 'offline' \| 'busy' \| 'away' \| 'dnd' \| 'degraded' \| 'maintenance'` | `'online'` | no | Semantic state; writes the `dsx-status--{variant}` modifier class via the prop def bag. `degraded`/`maintenance` are the node-health pair (see Anomalies note below on their token mapping vs. the five presence states). | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Dot diameter; writes the `dsx-status-size-{sm\|md\|lg}` class. | no |
+| `pulse` | `boolean` | `false` | no | When `true`, runs the `dsx-status-pulse` keyframe animation. Writes `data-pulse="true"`. | no |
+| `color` | `string` | `undefined` | no | Free-form color override passed through the prop def bag. The runtime does not currently consume this value to paint the dot. The component still writes `data-accent-color={color}` when a value is provided, so consumers can target it through CSS. | no |
+| `asChild` | `boolean` | `false` | no | Renders the status through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-status`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slotted content when `asChild`; otherwise ignored (Status has no default visual body). | no |
+
+Rules that apply to this row:
+
+- The component extends `Omit<ComponentPropsWithoutRef<'span'>, 'color'>` because `color` is redefined by the prop def bag. Native `<span>` attributes that are not prop def keys are forwarded.
+- `variant`, `size`, and `pulse` are wired through `extractProps` and write both the modifier class and the corresponding `data-*` attribute. `color` is wired through `extractProps` and writes only `data-accent-color`; the CSS does not currently consume it.
+- The `data-slot="status"` attribute is always written; it is a CSS hook, not a public slot.
+- The `color` prop in the prop def has `default: undefined` and an empty `values: [] as const` array, so the runtime accepts any string but the prop def does not enumerate values. The TS type resolves to `string | undefined`. QA should flag this as an open surface (see Anomalies).
+
+## CSS class contract
+
+**Root class:** `dsx-status`
+
+**Modifier classes** (driven by the `variant` and `size` prop defs and the `data-pulse` attribute):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| (class) | `online`, `offline`, `busy`, `away`, `dnd`, `degraded`, `maintenance` | `dsx-status--online`, `dsx-status--offline`, `dsx-status--busy`, `dsx-status--away`, `dsx-status--dnd`, `dsx-status--degraded`, `dsx-status--maintenance` | `status.css` |
+| (class) | `sm`, `md`, `lg` | `dsx-status-size-sm`, `dsx-status-size-md`, `dsx-status-size-lg` | `status.css` |
+| `data-pulse` | `true` | `.dsx-status[data-pulse='true']` | `status.css` |
+| `data-accent-color` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-status[data-accent-color='amber']` etc. (no rule in the source CSS) | n/a |
+| `data-slot` | `status` | (CSS hook only) | n/a |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+
+**Reduced motion:**
+
+- A local `prefers-reduced-motion: reduce` rule removes the pulse animation and shadow. The semantic dot retains its size, tone, and resting fill; no consumer override is required.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Display | `inline-block` | Inline anchor for the dot. |
+| Border radius | `var(--dsx-rounded-full)` | Circle. |
+| Flex shrink | `0` | Do not collapse inside a flex row. |
+| Background (default) | `var(--dsx-color-success)` | Online color; matches the `online` variant. |
+| Background (offline) | `var(--dsx-color-disabled-text)` | Muted presence. |
+| Background (busy) | `var(--dsx-color-error)` | High-stakes presence. |
+| Background (away) | `var(--dsx-color-primary)` | Brand-tinted presence. |
+| Background (dnd) | `var(--dsx-color-error)` | Same as busy; intentional. |
+| Background (degraded) | `var(--dsx-color-tertiary)` | Node-health caution tone; distinct from `error` (down) and `primary` (away). No dedicated warning token exists yet — reuses the bronze/orange tertiary accent. |
+| Background (maintenance) | `var(--dsx-color-secondary)` | Node-health informational tone; the slate/blue-gray secondary accent, distinct from `disabled-text` (offline) so a maintenance window doesn't read as "down". |
+| Size `sm` | `var(--dsx-space-xs)` | Dot diameter. |
+| Size `md` | `var(--dsx-space-sm)` | Default dot diameter. |
+| Size `lg` | `var(--dsx-space-md)` | Larger dot diameter. |
+| Pulse shadow | `var(--dsx-status-tone)` (keyframe 0%) | Pulse glow tint; now tracks the active variant's tone (was hardcoded to `--dsx-color-success` regardless of variant — fixed alongside the new variants). |
+| Pulse spread | `var(--dsx-space-xs)` (keyframe 70%) | Pulse ring thickness; falls back to `transparent` at 100%. |
+| Pulse duration | `var(--dsx-motion-duration-normal)` | Pulse cycle. |
+| Pulse easing | `var(--dsx-motion-easing-in-out)` | Pulse easing. |
+
+Rules:
+
+- `busy` and `dnd` both map to `var(--dsx-color-error)`. This is intentional; the variants stay distinct at the prop level so the consumer can split them later by overriding the CSS class.
+- Every variant sets a shared `--dsx-status-tone` custom property (rather than `background-color` directly); the pulse keyframe reads that property so the ring color always matches the resting fill, for every variant including `degraded`/`maintenance`.
+- The pulse keyframes mix an opaque tone with a `transparent` final frame. Transparency is reserved for the keyframe edge, not the resting fill.
+- `degraded` and `maintenance` reuse the existing `tertiary`/`secondary` accent tokens rather than introducing new warning/info tokens — `DESIGN.md` does not currently define a dedicated semantic warning color. If a future ask needs a warning tone independent of the tertiary accent, that requires a `DESIGN.md` token addition, not a Status-local change.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Pulse animation (`dsx-status-pulse`) | `var(--dsx-motion-duration-normal)` + `var(--dsx-motion-easing-in-out)` | `box-shadow` ring expands from `0 0 0 0 var(--dsx-status-tone)` (the active variant's tone) to `0 0 0 var(--dsx-space-xs) transparent`, then back to `0 0 0 0 transparent`; runs `infinite`. | Local CSS sets `animation: none` and `box-shadow: none`; the resting dot remains visible. |
+
+Rules:
+
+- The component uses CSS keyframes directly; it does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts` and does not use framer-motion. The local media query is the authoritative motion gate.
+
+## Accessibility
+
+**Roles:**
+
+- `img` (status role). The component is a non-text indicator. The runtime does not currently set `role` or `aria-label`; consumers must supply an accessible name (or a surrounding label) for assistive tech.
+
+**Keyboard:**
+
+- Status is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Status has no interactive surface. The dot is not focusable by default.
+
+**Reduced motion:**
+
+- The local stylesheet disables the pulse and preserves the resting semantic dot under `prefers-reduced-motion: reduce`.
+
+**Color and meaning:**
+
+- State is communicated by color alone in the visual treatment. Consumers must pair the dot with text (`Online`, `Away`, etc.) or an `aria-label` to make the state explicit. The five `variant` values map to documented presence semantics; `busy` and `dnd` share the error color but should be labeled distinctly in the UI.
+
+**Naming:**
+
+- The runtime does not auto-generate an accessible name. Consumers must either set `aria-label`, wrap the dot in a labelled element, or pass a label as a sibling. This is the biggest accessibility gap in the current implementation (see Anomalies).
+
+## Playground demo spec
+
+The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+
+**Default story:**
+
+- Renders `Status` with no props. Asserts the root class is `dsx-status`, the modifier classes are `dsx-status--online` and `dsx-status-size-md`, and `data-pulse` is absent.
+
+**Variant story** (one per variant):
+
+- Renders Status with `variant="online"`, `variant="offline"`, `variant="busy"`, `variant="away"`, `variant="dnd"`, `variant="degraded"`, and `variant="maintenance"`. Asserts the matching `dsx-status--{variant}` modifier class on the root.
+
+**Dot+label composition:**
+
+- No new compound API — Status stays a flat, dot-only export. The node-health composition is `Flex` (or any inline layout primitive) + `Status` + `Text`, e.g.:
+
+  ```tsx
+  <Flex align="center" gap="xs">
+    <Status variant="degraded" size="sm" />
+    <Text size="sm">Degraded</Text>
+  </Flex>
+  ```
+
+  This mirrors the existing `aria-label`/pairing guidance above (Status carries no accessible name on its own) and avoids adding a second component whose only job is wrapping a dot and a string. Playground demos this pattern for all seven variants under the Status page's composition section.
+
+**Size story:**
+
+- Renders Status with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `dsx-status-size-{sm|md|lg}` class and `data-size` value.
+
+**State story:**
+
+- Renders Status with `pulse={true}`. Asserts `data-pulse="true"` is present and the keyframe animation runs. Renders the dot paired with a `Text` label and verifies the `aria-label` is set on the wrapper.
+
+**Composition story** (for `asChild`):
+
+- Renders Status with `asChild` wrapping a `<div>` element. Asserts the host element is `div` and the `dsx-status` class is preserved.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. The visible dot color is variant-driven and does not track `data-accent-color`; the story documents that behavior and asserts the dot color is unchanged across the three accents.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default status. Asserts there are no axe violations only when the status is wrapped in a labelled element or carries an `aria-label`. The default story alone is expected to flag a missing accessible name and is documented in the playground as a known issue.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `online` |
+| `size` | select | `md` |
+| `pulse` | boolean | `false` |
+| `color` | text | (empty) |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
+- No DS component composition. The runtime does not import `Badge` or `Icon` even though the roster row lists those as the intended composition. The component is a self-contained dot surface (see Anomalies).
+
+**Used by:**
+
+- App-level presence surfaces (user lists, member directories, status feeds, presence pills). The roster currently lists no DS components that consume `Status`; it is a leaf primitive intended for direct app usage. `Item` and `Avatar` are reasonable composition targets but are not wired today.
+
+**State boundaries:**
+
+- Owned by Status: the root class, the variant modifier class, the size modifier class, the `data-pulse` attribute, the `data-accent-color` attribute when `color` is set, and the `data-slot="status"` attribute.
+- Owned by the consumer: the semantic mapping (which presence state to render), the visible label, the accessible name, and the host element when `asChild` is set.
+
+**Boundary rules:**
+
+- App-owned data: the actual presence state, the user identity behind the dot, and any surrounding avatar or label.
+- DS-owned visuals: token bindings (`--dsx-color-success`, `--dsx-color-error`, `--dsx-color-disabled-text`, `--dsx-color-primary`, `--dsx-color-tertiary`, `--dsx-color-secondary`, `--dsx-rounded-full`, `--dsx-space-xs/sm/md`, `--dsx-motion-duration-normal`, `--dsx-motion-easing-in-out`), the `dsx-status` root class, the `dsx-status--{variant}` and `dsx-status-size-{sm|md|lg}` modifier classes, the shared `--dsx-status-tone` custom property, and the `dsx-status-pulse` keyframes.
+
+## 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 Status. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / Status`.
+- **Dimensions**: `8 × 8` (sm), `12 × 12` (md), `16 × 16` (lg). Defaults to md.
+- **Layout**: `Fixed`.
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: Status / md / online>
+  └── <Shape: dot fill (online color)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | fill (default) | `--dsx-color-success` | Color | `fills` |
+| Root (offline) | fill | `--dsx-color-disabled-text` | Color | `fills` (state) |
+| Root (busy) | fill | `--dsx-color-error` | Color | `fills` (state) |
+| Root (away) | fill | `--dsx-color-primary` | Color | `fills` (state) |
+| Root (dnd) | fill | `--dsx-color-error` | Color | `fills` (state) |
+| Root (degraded) | fill | `--dsx-color-tertiary` | Color | `fills` (state) |
+| Root (maintenance) | fill | `--dsx-color-secondary` | Color | `fills` (state) |
+| Root | stroke | none | n/a | n/a |
+| Root | corner radius | `--dsx-rounded-full` | Radius | `radius` |
+| Root (size sm) | width, height | `--dsx-space-xs` | Sizing | `size` |
+| Root (size md) | width, height | `--dsx-space-sm` | Sizing | `size` |
+| Root (size lg) | width, height | `--dsx-space-md` | Sizing | `size` |
+
+### State transformations
+
+| State | Root fill | Pulse shadow |
+|---|---|---|
+| `online` (default) | `--dsx-color-success` | none |
+| `offline` | `--dsx-color-disabled-text` | none |
+| `busy` | `--dsx-color-error` | none |
+| `away` | `--dsx-color-primary` | none |
+| `dnd` | `--dsx-color-error` | none |
+| `degraded` | `--dsx-color-tertiary` | none |
+| `maintenance` | `--dsx-color-secondary` | none |
+| `pulse=true` | (variant) | ring at `--dsx-space-xs`, colored by the active variant's tone |
+
+### Variant model
+
+- `variant`: `online`, `offline`, `busy`, `away`, `dnd`, `degraded`, `maintenance`. Default `online`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `pulse`: `true`, `false`. Default `false`.
+- Total members: 42 (7 × 3 × 2).
+
+### 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.
+- [ ] `busy` and `dnd` share `--dsx-color-error`; document the intentional duplication at the variant level.
+- [ ] Pulse keyframes are CSS-only; the Penpot recipe does not animate the dot.

package/dist/docs/stepper.md

@@ -0,0 +1,248 @@
+---
+title: Stepper
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/stepper/Stepper.tsx
+css_path: packages/d4gger-design-system/src/styles/components/stepper.css
+props_path: packages/d4gger-design-system/src/components/stepper/stepper.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Stepper.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:
+  - Progress
+  - Separator
+  - Text
+  - Button
+---
+
+# Stepper
+
+> 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 multi-step wizard or progress indicator that pairs a numbered indicator with a label and optional description for each step, separated by connectors. Use `Stepper` for top-of-page progress and for inline wizard navigation. For linear loading progress, use `Progress`.
+
+## Anatomy & slots
+
+**Parent:** `Stepper` (alias of `StepperRoot`). The root is a `<div>` (or `Slot` host when `asChild` is set) with `role="progressbar"` and `aria-orientation` reflecting the chosen orientation.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Stepper` (root) | `<div role="progressbar">` (or `Slot` host) | `dsx-stepper` (with `--horizontal` or `--vertical` modifier) | Root container. Writes `data-size`, `role="progressbar"`, `aria-orientation`. |
+| `Stepper.Item` | `<div>` (or `Slot` host) | `dsx-stepper__item` (with state modifier class) | One step. Writes `data-state`. Holds an `Indicator`, a `Label`, an optional `Description`, and a trailing `Separator`. |
+| `Stepper.Indicator` | `<div>` (or `Slot` host) | `dsx-stepper__indicator` | The numbered badge. Renders the `step` prop as text by default; consumers can pass children to replace the number with an icon. Writes `aria-label="Step <n>"`. |
+| `Stepper.Label` | `<div>` (or `Slot` host) | `dsx-stepper__label` | The step's title text. |
+| `Stepper.Description` | `<div>` (or `Slot` host) | `dsx-stepper__description` | Optional helper text under the label. |
+| `Stepper.Separator` | `<div>` (or `Slot` host) | `dsx-stepper__separator` | Connector between items. In horizontal orientation the connector stretches to fill the available space; in vertical orientation it is a tall, thin bar to the right of the indicator. |
+| `Stepper.Content` | `<div>` (or `Slot` host) | `dsx-stepper__content` | Optional long-form content panel below the indicator rail. The CSS adds a `var(--dsx-space-lg)` top margin so the panel sits below the step labels. |
+
+**Internal layout:**
+
+- The root is a flex container. In `orientation="horizontal"` (the default) it is a `flex-direction: row` with `align-items: center`. In `orientation="vertical"` it is a `flex-direction: column` with `align-items: flex-start`.
+- `Stepper.Item` is a flex container. In horizontal orientation the item itself flips to `flex-direction: column` so the indicator sits above the label / description. In vertical orientation the item stays in a `flex-direction: row` and is `width: 100%` so the indicator, label, description, and content lay out side by side.
+- `Stepper.Indicator` is a circular `var(--dsx-size-md)` badge with a 1px outline. It uses the `label-medium` type ramp. State colors (complete, current, error, disabled) are applied via the parent `Item`'s modifier class.
+- `Stepper.Separator` is the connector. In horizontal orientation it is a `flex: 1` bar that fills the available space; in vertical orientation it is a `var(--dsx-border-width-lg)` wide, `var(--dsx-space-lg)` tall bar offset to the right of the indicator.
+
+## Props contract
+
+**Root props (`Stepper`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Layout direction. Writes `aria-orientation` and the matching `dsx-stepper--horizontal` / `dsx-stepper--vertical` modifier. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size scale. Writes `data-size`. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Item props (`Stepper.Item`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `state` | `'complete' \| 'current' \| 'pending' \| 'error' \| 'disabled'` | `'pending'` | no | Visual state. `complete` recolors the indicator to the success palette, `current` to the primary palette, `error` to the error palette, and `disabled` reduces opacity. Writes `data-state` and the matching `dsx-stepper__item--*` modifier. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Indicator props (`Stepper.Indicator`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `step` | `number` | (none) | **yes** | The numeric step identifier. Renders as the indicator content by default and is used to compose `aria-label="Step <n>"`. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+`step` is required because the indicator renders it as text and writes the `aria-label` from it. Consumers can pass children to override the visual content; the `aria-label` still reflects `step`.
+
+**Label / Description / Separator / Content props:**
+
+These slots accept only `asChild` plus the standard HTML attribute surface for their host elements. None of them have their own design-system props.
+
+## CSS class contract
+
+**Root class:** `dsx-stepper`
+
+**Modifier classes** (driven by `data-*` attributes and variant modifier classes):
+
+| Attribute / class | Allowed values | Class | CSS file |
+|---|---|---|---|
+| Root orientation (class) | `horizontal`, `vertical` | `.dsx-stepper--horizontal`, `.dsx-stepper--vertical` | `stepper.css` |
+| Root size | `sm`, `md`, `lg` | `data-size` (attribute forwarded) | `stepper.css` |
+| Root ARIA | `progressbar`, `vertical` / `horizontal` | `role="progressbar"`, `aria-orientation` | (TSX) |
+| Item state (attribute) | `complete`, `current`, `pending`, `error`, `disabled` | `data-state` | (TSX) |
+| Item state (class) | `complete`, `current`, `pending`, `error`, `disabled` | `.dsx-stepper__item--complete`, `--current`, `--pending`, `--error`, `--disabled` | `stepper.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Stepper` (root) | `dsx-stepper` (+ `--horizontal` / `--vertical` modifier) | `stepper.css` |
+| `Stepper.Item` | `dsx-stepper__item` (+ state modifier) | `stepper.css` |
+| `Stepper.Indicator` | `dsx-stepper__indicator` | `stepper.css` |
+| `Stepper.Label` | `dsx-stepper__label` | `stepper.css` |
+| `Stepper.Description` | `dsx-stepper__description` | `stepper.css` |
+| `Stepper.Separator` | `dsx-stepper__separator` | `stepper.css` |
+| `Stepper.Content` | `dsx-stepper__content` | `stepper.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the stepper in a responsive shell.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Item gap | `var(--dsx-space-sm)` | Gap between indicator and label / description |
+| Indicator size | `var(--dsx-size-md)` | Indicator width and height |
+| Indicator border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Indicator edge |
+| Indicator background | `var(--dsx-color-surface)` | Indicator surface |
+| Indicator radius | `var(--dsx-rounded-full)` | Circular indicator |
+| Indicator type ramp | `var(--dsx-typography-label-medium-*)` | Indicator number |
+| Indicator text color | `var(--dsx-color-on-surface-variant)` | Indicator text |
+| Complete indicator | `var(--dsx-color-success)` (border + background), `var(--dsx-color-on-success)` (text) | Success palette |
+| Current indicator | `var(--dsx-color-primary)` (border + background), `var(--dsx-color-on-primary)` (text) | Primary palette |
+| Error indicator | `var(--dsx-color-error)` (border + background), `var(--dsx-color-on-error)` (text) | Error palette |
+| Disabled item | `var(--dsx-opacity-disabled)` | Disabled opacity |
+| Label type ramp | `var(--dsx-typography-label-large-*)` | Label text |
+| Label color | `var(--dsx-color-on-surface)` | Default label color |
+| Pending / disabled label | `var(--dsx-color-on-surface-variant)` | Pending / disabled label color |
+| Description color | `var(--dsx-color-on-surface-variant)` | Description text |
+| Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text |
+| Separator height | `var(--dsx-border-width-lg)` | Default connector thickness |
+| Separator background | `var(--dsx-color-outline-variant)` | Default connector color |
+| Separator radius | `var(--dsx-rounded-full)` | Connector roundness |
+| Separator min-width | `var(--dsx-space-md)` | Min horizontal connector length |
+| Horizontal separator offset | `margin-top: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `margin-left: var(--dsx-space-sm)`, `margin-right: var(--dsx-space-sm)` | Alignment with the indicator centerline |
+| Vertical separator width | `var(--dsx-border-width-lg)` | Vertical connector thickness |
+| Vertical separator height | `var(--dsx-space-lg)` | Vertical connector length |
+| Vertical separator offset | `flex: 0`, `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `min-height: var(--dsx-space-lg)` | Centered alignment with the indicator centerline |
+| Complete-separator color | `var(--dsx-color-primary)` | Connector after a complete step |
+| Content margin-top | `var(--dsx-space-lg)` | Panel offset |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. State transitions (complete / current / pending / error) are instant recolorings, not animations.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders with `role="progressbar"`, which is the WAI-ARIA pattern for linear progress through a known number of steps.
+- `aria-orientation` is set to `'vertical'` or `'horizontal'` based on the `orientation` prop.
+- The `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes are not set by the component; consumers that want a numeric progress value should set them on the root or on a wrapping element.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through interactive elements placed inside items (e.g. buttons, links). The stepper itself is not focusable. |
+
+**Focus:**
+
+- The component does not render a focus ring on items or indicators. Interactive content provides its own ring.
+
+**Reduced motion:**
+
+- No motion is applied; no `prefers-reduced-motion` override is needed.
+
+**Color and meaning:**
+
+- State is communicated by both color and the indicator text. Consumers can swap the numeric content for an icon (e.g. a checkmark for `complete`, an `!` for `error`) to make the state readable without color.
+- `aria-label="Step <n>"` is written on every `Indicator` so screen readers can announce the position of the indicator even when the visual content is replaced.
+
+**Naming:**
+
+- `Stepper.Indicator` is announced as "Step n" by screen readers. Pair it with a `Stepper.Label` that names the step ("Account", "Profile", "Confirm") so users hear both the position and the meaning.
+- `Stepper.Description` is supplementary context; it does not replace the label.
+
+## Current runtime behavior: vertical-layout bug (resolved)
+
+The vertical `Stepper` layout previously had two visual defects:
+
+1. The `.dsx-stepper--vertical .dsx-stepper__separator` override did not reset the base `flex: 1`, causing the separator to grow along the main axis in vertical orientation.
+2. The `margin-left` was `calc(var(--dsx-size-md) / 2)` without subtracting half the separator width, offsetting the connector from the indicator centerline.
+
+Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)` to center the connector under the indicator.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a horizontal `Stepper` with three items: `state="complete"`, `state="current"`, `state="pending"`, separated by `Stepper.Separator`. Asserts the root has `role="progressbar"`, `aria-orientation="horizontal"`, and the `--horizontal` modifier class. Asserts each item carries the matching `data-state` and modifier class.
+
+**Variant story:**
+
+- Renders one horizontal and one vertical `Stepper`. Asserts the matching modifier class and `aria-orientation` value on each root.
+
+**State story:**
+
+- Renders four items with `state="complete"`, `state="current"`, `state="error"`, and `state="disabled"`. Asserts the matching `data-state` and modifier class on each.
+
+**Composition story:**
+
+- Renders a `Stepper.Item` with `Indicator step={2}`, `Label`, `Description`, and a trailing `Separator`. Asserts all slot classes render.
+
+**Token story:**
+
+- Renders the default stepper inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the current step indicator tracks `--dsx-color-primary` and is not affected by the accent token.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select | `horizontal` |
+| `size` | select | `md` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` on the root and on every named slot.
+
+**Used by:**
+
+- App-level onboarding flows, multi-step forms, and wizard navigation. The roster explicitly calls out that `Stepper` is a composite, not a pattern, and that it must compose primitive `Indicator + Separator + Label` parts rather than a parallel visual shell.
+
+**State boundaries:**
+
+- Owned by Stepper: `orientation`, `size`, item `state`, and the `dsx-stepper__*` slot classes.
+- Owned by the consumer: the step ordering, the `step` number on every `Indicator`, the `aria-valuenow` family on the root, and any interactive elements inside the content area.
+
+**Boundary rules:**
+
+- App-owned data: step list, completion state, current-step index, and click handlers.
+- DS-owned visuals: token bindings, slot classes, state modifier classes, and the indicator type ramp.