@hegemonart/get-design-done 1.16.0 → 1.19.0

package/reference/components/skeleton.md

@@ -0,0 +1,197 @@
+# Skeleton — Benchmark Spec
+
+**Harvested from**: Polaris, Carbon, Atlassian, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A skeleton screen is a loading placeholder that mirrors the shape of the content it will replace — text lines, images, cards, avatars. It reduces perceived wait time by showing the structural layout before real data arrives, preventing the jarring reflow that occurs when content suddenly appears. Use skeleton when the content shape is known; use an indeterminate spinner or progress bar when shape is unknown. *(Polaris, Carbon, Atlassian, Mantine agree: skeleton = shape-matched placeholder, not generic spinner)*
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│  ████ (avatar-circle, 40px)      │  ← aria-hidden="true"
+│  ██████████████████ (text-line)  │
+│  █████████████ (text-line 75%)   │
+│  ████████████████████ (text-line)│
+└──────────────────────────────────┘
+↑ container: aria-busy="true" aria-label="Loading…"
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Container | Yes | `aria-busy="true"` + `aria-label="Loading…"` or `aria-labelledby` |
+| Skeleton elements | Yes | `aria-hidden="true"` on each shape element |
+| Text-line shape | No | Width 60–90% (varied) to mimic text flow |
+| Image/card block | No | Fixed aspect-ratio; fills the same space as the loaded image |
+| Avatar circle | No | Circular shape; diameter matches the final avatar size |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Text lines | One or more lines at varying widths (60–90%) | All |
+| Image block | Rectangular/aspect-ratio shape for images | Polaris, Carbon, Mantine |
+| Avatar | Circular placeholder at avatar diameter | Polaris, Atlassian, Mantine |
+| Card | Full card-sized block with text-line children | All |
+| Table row | Row-shaped block with column-width children | Carbon, Mantine |
+
+**Norm** (≥4/18 systems agree): shimmer animation (left-to-right gradient sweep); vary text-line widths 60–90%; `aria-hidden` on skeleton elements; `aria-busy` on container.
+**Diverge**: Polaris renders skeleton as named sub-components (`SkeletonBodyText`, `SkeletonDisplayText`); Carbon uses CSS class modifiers; Mantine uses a generic `Skeleton` with width/height props; Atlassian uses a shape prop.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| loading | data fetch in progress | Shimmer animation looping | `aria-busy="true"` on container |
+| loaded | data resolves | Skeleton removed, real content appears | `aria-busy="false"` or remove attr |
+
+---
+
+## Sizing & Spacing
+
+| Shape | Default sizing | Notes |
+|-------|----------------|-------|
+| Text-line | 16px height | Matches body line-height slot |
+| Text-line (heading) | 24–28px height | Matches h2/h3 slot |
+| Avatar | Match target avatar diameter | 32px, 40px, 48px common |
+| Image block | Match target image aspect ratio | 16:9, 1:1, 4:3 common |
+| Gap between text lines | 8px | Matches body line-height rhythm |
+
+**Norm**: Match exact pixel dimensions of the content being replaced — layout shift score is zero when skeleton matches final content size *(Polaris, Mantine)*.
+
+---
+
+## Typography
+
+Skeleton shapes are purely visual — no typography content. However:
+- Text-line height should match the `line-height` of the real text it replaces
+- Heading skeleton height should match the heading's `font-size` + leading
+- Do NOT use placeholder text ("Loading…") inside skeleton shapes — use `aria-label` on the container instead
+
+Cross-link: `reference/typography.md` — line-height scale for matching skeleton dimensions
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: no role on skeleton shapes; container uses `aria-busy`
+> **Required attributes**: `aria-hidden="true"` on each skeleton element; `aria-busy="true"` + `aria-label="Loading…"` on container
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| (none) | Skeleton shapes are not interactive; no keyboard interaction |
+
+Skeleton elements must not receive focus. The container is not focusable unless it wraps focusable content that appears after loading.
+
+### Accessibility Rules
+
+- Every skeleton shape element MUST have `aria-hidden="true"` — blank shapes announced by screen readers ("image", "text") confuse users *(Polaris, Carbon)*
+- The container MUST have `aria-busy="true"` while loading, set to `false` (or removed) when content appears *(WAI-ARIA APG)*
+- The container MUST have `aria-label="Loading…"` or equivalent — this is what screen readers announce while `aria-busy="true"` *(WAI-ARIA APG)*
+- Do NOT use skeleton as the only loading indicator for screen reader users — announce loading state via live region if the transition is programmatic *(Carbon)*
+- Shimmer animation MUST be suppressed under `prefers-reduced-motion` — use static fill instead *(WCAG 2.3.3)*
+
+Cross-link: `reference/accessibility.md` — `aria-busy`, `prefers-reduced-motion`
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Shimmer sweep | 1.5s | ease-in-out | 130° gradient: transparent → surface-highlight → transparent |
+| Loop delay | 0.5s | — | Pause between sweeps to avoid strobing |
+| Skeleton → content | 200ms | ease-out | Fade-in real content over skeleton |
+
+Shimmer gradient direction: 130 degrees (roughly top-left to bottom-right) — matches natural reading direction.
+Background: `surface-variant` token (slightly darker than background surface, lighter than border).
+
+**BAN**: High-contrast shimmer (e.g. white → gray on dark) — too visually noisy. Do NOT use spinner animation inside a skeleton shape. Under `prefers-reduced-motion`, remove the sweep entirely and use static fill.
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: static fill, no gradient sweep
+
+---
+
+## Do / Don't
+
+### Do
+- Match skeleton dimensions exactly to target content to avoid layout shift *(Polaris, Mantine)*
+- Vary text-line widths 60–90% to simulate natural text flow *(Carbon, Atlassian)*
+- Set `aria-hidden="true"` on every skeleton shape element *(WAI-ARIA APG, Polaris)*
+- Set `aria-busy="true"` + `aria-label="Loading…"` on the container *(WAI-ARIA APG)*
+
+### Don't
+- Don't use a spinner when content shape is known — skeleton is always preferred for layout-bearing slots *(Carbon, Polaris)*
+- Don't use strong contrast for shimmer — use `surface-variant` (low contrast) *(Atlassian, Mantine)*
+- Don't animate shimmer under `prefers-reduced-motion` — use static fill *(WCAG 2.3.3)*
+- Don't add visible "Loading…" text inside skeleton shapes — put it on the container via `aria-label` *(Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Spinner used when content shape is known | `reference/anti-patterns.md#ban-spinner-overuse` |
+| Missing aria-hidden on visual-only elements | `reference/anti-patterns.md#ban-aria-hidden` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-hidden="true" on skeleton shapes | WAI-ARIA APG, Polaris, Carbon |
+| aria-busy="true" on container | WAI-ARIA APG |
+| Text-line widths 60–90% varied | Carbon, Atlassian, Mantine |
+| Shimmer 130° gradient sweep 1.5s | Polaris, Mantine |
+| Suppress shimmer under prefers-reduced-motion | WCAG 2.3.3 |
+| Match exact target dimensions to prevent layout shift | Polaris, Mantine |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Skeleton shapes missing aria-hidden
+grep -rn 'skeleton\|Skeleton' src/ | grep -v 'aria-hidden="true"' | grep -v 'aria-busy\|container'
+
+# Skeleton container missing aria-busy
+grep -rn 'skeleton\|Skeleton' src/ | grep 'container\|wrapper\|section' | grep -v 'aria-busy'
+
+# Shimmer animation without prefers-reduced-motion guard
+grep -rn 'shimmer\|skeleton.*animation\|@keyframes.*skeleton' src/ | grep -v 'prefers-reduced-motion'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: skeleton shapes with no aria-hidden, container with no aria-busy -->
+<div class="card-skeleton">
+  <div class="skeleton-avatar"></div>
+  <div class="skeleton-line skeleton-line--80"></div>
+  <div class="skeleton-line skeleton-line--60"></div>
+</div>
+```
+
+**Why it fails**: Screen readers traverse the skeleton shapes and announce them as empty elements ("image", unlabeled regions). There is no `aria-busy="true"` to signal a loading state. No `aria-label` tells the user what is loading. When content loads, no `aria-busy="false"` transition signals completion.
+**Grep detection**: `grep -rn 'skeleton' src/ | grep -v 'aria-hidden\|aria-busy'`
+**Fix**: Add `aria-busy="true" aria-label="Loading card content"` to the container; add `aria-hidden="true"` to every skeleton child shape.

package/reference/components/slider.md

@@ -0,0 +1,208 @@
+# Slider — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG Slider pattern, Material 3, Radix Slider, Carbon Design System
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/slider.md`
+
+---
+
+## Purpose
+
+A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum — volume, price, opacity, temperature — and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
+
+---
+
+## Anatomy
+
+```
+Single:
+[ ●────────────────────── ]  ← track
+   thumb
+
+Range:
+[ ──────●────────●──────── ]
+        min      max
+        thumb    thumb
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Track | Yes | Full-width bar; inactive segments use muted color |
+| Active range fill | Yes | Filled portion between min-edge and thumb (single) or between thumbs (range) |
+| Thumb | Yes | Draggable handle; visual ≥12px; touch target ≥44px via ::before padding |
+| Value label (tooltip) | No | Shows current value above/beside thumb on interaction |
+| Tick marks | No | Shown for discrete steps when ≤10 steps |
+| Min/Max labels | No | Static text at track ends |
+| Numeric input | No | Paired `<input type="number">` for precise entry |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Single | One thumb; selects a scalar value | WAI-ARIA APG, Material 3, Carbon, Radix |
+| Range | Two thumbs; selects min and max of a range | Material 3 (RangeSlider), Carbon, Radix |
+| Discrete | Step-snapping with tick marks (≤10 steps) | Material 3, Carbon |
+| Continuous | No snapping; free movement | Material 3, Carbon, Radix |
+| Vertical | `aria-orientation="vertical"`; track runs top-to-bottom | WAI-ARIA APG, Carbon |
+
+**Norm** (≥3/4 systems agree): horizontal orientation is default; thumb is a circle on a horizontal track; active range fills in brand color.
+**Diverge**: Carbon shows tick labels below the track; Material 3 shows a floating value tooltip on drag; Radix delegates tooltip entirely to the consumer.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Track + thumb at resting position | `aria-valuenow` reflects current value |
+| hover | Pointer over thumb | Thumb expands or shows halo | — |
+| focus | Keyboard focus on thumb | Focus-visible ring on thumb | — |
+| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | — |
+| disabled | `disabled` / `aria-disabled` | 38% opacity; cursor: not-allowed | `aria-disabled="true"` |
+
+---
+
+## Sizing & Spacing
+
+| Size | Track Height | Thumb Visual | Thumb Hit Area | Notes |
+|------|-------------|--------------|----------------|-------|
+| sm | 2px | 12px | 44px (via ::before) | Compact; pair with numeric input |
+| md (default) | 4px | 20px | 44px (via ::before) | Standard; tick labels at 14px |
+| lg | 6px | 24px | 44px | High-emphasis; price/volume controls |
+
+**Norm**: 4px track height (Material 3, Carbon). Thumb visual diameter 20px with ::before/::after expanding the touch target to ≥44px without inflating layout.
+
+Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use padding trick, not enlarged visual.
+
+---
+
+## Typography
+
+- Value tooltip: caption-sm, weight 500, centered above thumb
+- Tick labels: caption-xs, secondary color, centered below tick mark
+- Min/Max endpoint labels: caption-sm, secondary color, flush with track ends
+
+Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digits don't shift width during drag.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `slider`
+> **Required attributes**: `aria-valuenow`, `aria-valuemin`, `aria-valuemax`; `aria-valuetext` for human-readable value (e.g., "$45" or "45%"); `aria-label` or `aria-labelledby`; `aria-orientation="vertical"` when vertical
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/slider/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Right Arrow / Up Arrow | Increase value by one step |
+| Left Arrow / Down Arrow | Decrease value by one step |
+| Page Up | Increase value by a larger step (typically 10% of range) |
+| Page Down | Decrease value by a larger step (typically 10% of range) |
+| Home | Set value to minimum |
+| End | Set value to maximum |
+
+*For vertical slider (`aria-orientation="vertical"`), Up Arrow increases and Down Arrow decreases.*
+
+### Accessibility Rules
+
+- Every slider thumb MUST have `aria-valuenow`; update it continuously during drag
+- `aria-valuetext` MUST be provided when raw number is not human-readable (e.g., "Low", "Medium", "High" for a quality setting, or "$45" for a price)
+- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) — identical labels confuse screen readers
+- Thumb touch target MUST be ≥44×44px; use `::before`/`::after` pseudo-element padding if visual thumb is smaller
+- Do not use `<input type="range">` hidden behind a custom div without ARIA — the native element is preferable when no custom styling is required
+- Disabled sliders: use `aria-disabled="true"`; keep thumb in tab order so AT can announce the current value
+
+Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidance.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Thumb drag | 0ms | — | No easing on drag — follows pointer exactly |
+| Keyboard step | 80ms | ease-out | Smooth snap to new position |
+| Value tooltip appear | 100ms | ease-out | Fade in on focus/drag |
+| Value tooltip dismiss | 150ms | ease-in | Fade out on blur |
+| Tick mark appear | 120ms | ease-out | When switching to discrete mode |
+
+**BAN**: Do not add momentum or inertia easing to thumb drag — feels broken and breaks accessibility (thumb does not match pointer).
+
+Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step animation; thumb jumps instantly.
+
+---
+
+## Do / Don't
+
+### Do
+- Provide `aria-valuetext` with a human-readable label when the raw number needs context *(WAI-ARIA APG)*
+- Give each range thumb a unique, descriptive `aria-label` *(WAI-ARIA APG, Radix Slider docs)*
+- Expand thumb touch target to ≥44px with pseudo-element padding *(Material 3, Carbon)*
+- Show tick marks only for discrete sliders with ≤10 steps *(Material 3, Carbon)*
+
+### Don't
+- Don't build a slider from `<div>` with mouse events only — no keyboard, no ARIA *(diverges from all 4 systems)*
+- Don't omit `aria-valuenow` updates during drag — AT users hear a stale value *(WAI-ARIA APG)*
+- Don't let the visual thumb area be smaller than 12px with no hit-area expansion — fails WCAG 2.5.8 *(Material 3)*
+- Don't use identical `aria-label` for both range thumbs *(WAI-ARIA APG)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-09 | Custom interactive widget with mouse events only, no keyboard — `reference/anti-patterns.md#ban-09` |
+| BAN-11 | Touch target below 44px without padding expansion — `reference/anti-patterns.md#ban-11` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="slider" + aria-valuenow/min/max required | WAI-ARIA APG Slider pattern |
+| Arrow key step, Page key 10% step, Home/End to extremes | WAI-ARIA APG keyboard contract |
+| 4px track height default | Material 3, Carbon |
+| Thumb touch target ≥44px via pseudo-element | Material 3, Carbon accessibility guidelines |
+| aria-valuetext for non-numeric human-readable values | WAI-ARIA APG, Radix Slider docs |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Slider thumb missing aria-valuenow (ARIA contract violation)
+grep -rn 'role="slider"' src/ | grep -v 'aria-valuenow'
+
+# Custom slider div with mouse events only — no keyboard handler
+grep -rn 'class.*slider\|\.slider' src/ | grep 'onMouseDown\|mousedown' | grep -v 'onKeyDown\|keydown\|role="slider"'
+
+# Thumb element potentially below 44px with no hit-area expansion
+grep -rn '\.thumb\|slider-thumb' src/ | grep 'width:\s*[0-9]\{1,2\}px\|height:\s*[0-9]\{1,2\}px' | grep -v '::before\|::after\|padding'
+
+# Range slider thumbs with identical aria-label
+grep -rn 'role="slider"' src/ -A2 | grep 'aria-label' | sort | uniq -d
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: custom slider using <div> with mouse events only — no keyboard, no ARIA -->
+<div class="slider-track" onmousedown="startDrag(event)">
+  <div class="slider-thumb" style="left: 45%"></div>
+</div>
+```
+
+**Why it fails**: Not reachable by keyboard; no `role="slider"`; no `aria-valuenow`, `aria-valuemin`, or `aria-valuemax`; AT cannot read or change the value; touch users cannot interact via assistive touch.
+**Grep detection**: `grep -rn '<div.*slider\|class="slider' src/ | grep -v 'role="slider"'`
+**Fix**: Use native `<input type="range">` or add `role="slider"` + `aria-valuenow` + `aria-valuemin` + `aria-valuemax` + `aria-valuetext` + full keyboard event handlers (Arrow, Page, Home, End) to the thumb element.

package/reference/components/stepper.md

@@ -0,0 +1,220 @@
+# Stepper / Wizard — Benchmark Spec
+
+**Harvested from**: Carbon (ProgressIndicator + StepNavigation), Material 3 Stepper, Atlassian Design System, Mantine Stepper
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/stepper.md`
+
+---
+
+## Purpose
+
+A Stepper (or Wizard) guides users through a sequential multi-step flow — onboarding, checkout, multi-page forms, settings setup. It communicates how many steps exist, which step is current, which are complete, and which are upcoming. Unlike Tabs (free navigation), a linear Stepper enforces order: the user must complete the current step before advancing. *(Carbon, Material 3, Atlassian, Mantine agree: step indicator list + content area + explicit Next/Back buttons is the canonical wizard pattern.)*
+
+---
+
+## Anatomy
+
+```
+Step indicator (role="list"):
+  ● Step 1: Account    ✓ Step 2: Profile    ○ Step 3: Confirm
+  aria-current="step"  completed             upcoming
+
+Content area:
+  [ Current step form/content ]
+
+Actions:
+  [ Back ]                              [ Next ] / [ Submit ]
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Step indicator list | Yes | `role="list"`; each step is `role="listitem"` |
+| Step labels | Yes | Visible text per step; described state (e.g., "completed") |
+| Current step marker | Yes | `aria-current="step"` on active step |
+| Content area | Yes | Shows current step content (single panel or accordion) |
+| Next button | Yes | Explicit label "Next" or "Continue"; validates current step first |
+| Back button | Yes (if non-first step) | Returns to previous step; "Back" label |
+| Submit button | Yes (final step) | "Submit" or context-specific label; replaces Next on last step |
+| Step connector line | No | Visual line between step dots; decorative, `aria-hidden="true"` |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Linear / locked | Must complete steps in order; no jumping ahead | Carbon, Material 3, Atlassian, Mantine |
+| Non-linear | Can jump to any previously completed step | Carbon (StepNavigation), Mantine (allowNextStepsSelect) |
+| Horizontal | Step indicators in a row across the top | All systems (default) |
+| Vertical | Step indicators stacked on the left | Carbon, Material 3 |
+| Accordion stepper | All steps visible; current step expanded | Material 3 (docked), Mantine (vertical) |
+| Simple (no icons) | Text + number only, no check icons | Atlassian (compact) |
+
+**Norm** (≥3/4 systems agree): horizontal orientation is default; completed steps show a checkmark; current step is visually distinct; upcoming steps are muted.
+**Diverge**: Material 3 uses filled circles with numbers; Carbon uses custom step icons; Mantine supports icons per step; Atlassian uses numbered circles.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| upcoming | Step not yet reached | Muted circle/number, secondary text color | — |
+| current | Active step | Brand-color filled circle; bold label | `aria-current="step"` |
+| completed | Step passed + valid | Check icon; full-opacity; clickable if non-linear | `aria-label="Step N: [name] - completed"` |
+| error | Step has validation errors | Error color circle; error icon | `aria-label="Step N: [name] - has errors"` |
+| disabled | Future step in linear flow | Muted; not clickable | Implicit (no click handler; cursor: default) |
+
+---
+
+## Sizing & Spacing
+
+| Size | Step Circle | Connector Height | Label Font | Gap Between Steps |
+|------|-------------|-----------------|------------|-------------------|
+| sm | 20px | 1px | 12px | 32px |
+| md (default) | 32px | 2px | 14px | 48px |
+| lg | 40px | 2px | 16px | 64px |
+
+**Norm**: Step circles 32px default *(Carbon, Mantine)*. Horizontal spacing between steps should scale with the available width so the indicator spans the container. Connector line is centered between circles.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px touch target for clickable step indicators.
+
+---
+
+## Typography
+
+- Step label: body-sm (completed/upcoming) → body-sm weight 600 (current)
+- Step number/icon inside circle: caption-sm, center-aligned
+- Step description (optional sub-label): caption-sm, secondary color
+- Action buttons: body-md, weight 500 — same as standard button spec
+
+Cross-link: `reference/typography.md` — label weight change for current state.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `list` (step indicator container), `listitem` (each step), `button` (clickable completed steps in non-linear mode)
+> **Required attributes**: `aria-current="step"` on active step; descriptive `aria-label` on completed steps (include state: "Step 2: Profile - completed"); `aria-label` on connector lines if not `aria-hidden`
+
+### Keyboard Contract
+
+*Derived from WAI-ARIA APG list and button patterns — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus through interactive elements: clickable completed steps (non-linear), Back button, Next/Submit button |
+| Enter / Space | Activate focused Back, Next, Submit button; activate clickable completed step (non-linear) |
+| (No arrow-key navigation) | Steps are NOT tabs — do not implement roving tabindex / arrow-key navigation between steps |
+
+Steps are NOT `role="tab"` and do not use the tab keyboard pattern. Upcoming steps are not focusable in linear mode. Only completed steps are interactive (and focusable) in non-linear mode.
+
+### Accessibility Rules
+
+- Step indicators MUST use `role="list"` + `role="listitem"` — not `role="tablist"` + `role="tab"` (tabs allow free navigation; wizard steps do not)
+- Current step MUST have `aria-current="step"` — this is the correct token (not `aria-selected` or `aria-checked`)
+- Completed steps in non-linear mode MUST be `<button>` elements (or have `role="button"` + `tabindex="0"`) with `aria-label` including the step name and "completed" state
+- Step connector lines MUST be `aria-hidden="true"` — they are purely decorative
+- Validate current step before allowing Next; display inline error messages with `aria-describedby` associations
+- "Next", "Back", and "Submit" MUST be explicit text labels — do not use icon-only navigation buttons
+- Announce step transitions via `aria-live="polite"` on the content region header (e.g., "Step 2 of 4: Profile")
+
+Cross-link: `reference/accessibility.md` — aria-current values, list semantics.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Step complete animation | 200ms | ease-out | Circle fill → checkmark draw |
+| Content area transition | 250ms | ease-in-out | Fade or slide left/right between steps |
+| Error state appear | 150ms | ease-out | Circle color change + icon fade in |
+| Back navigation | 200ms | ease-in-out | Slide right (reverse direction) |
+
+**BAN**: Do not use the same slide direction for both forward and backward step navigation — direction must be consistent with the mental model (forward = left, backward = right).
+
+Cross-link: `reference/motion.md` — reduced-motion: skip slide; cross-fade content area only.
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="list"` for the step indicator — steps are a list, not a tab set *(WAI-ARIA APG, Carbon)*
+- Set `aria-current="step"` on the active step *(WAI-ARIA spec §aria-current)*
+- Validate the current step before advancing and show inline errors *(Carbon, Atlassian)*
+- Label Back/Next/Submit buttons explicitly — not icons or chevrons *(Material 3, Carbon, Mantine)*
+
+### Don't
+- Don't use `role="tablist"` for steps — tabs allow free navigation; wizard steps are ordered and gated *(diverges from all 4 systems)*
+- Don't allow jumping to future unvisited steps in linear mode — breaks the sequential contract *(Carbon, Atlassian)*
+- Don't use `aria-selected` on steps — `aria-current="step"` is the correct token *(WAI-ARIA spec)*
+- Don't omit the Back button — users must be able to correct previous steps *(Material 3, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-14 | Stepper using role="tablist" — semantically incorrect navigation model — `reference/anti-patterns.md#ban-14` |
+| BAN-07 | Missing aria-current on active step — `reference/anti-patterns.md#ban-07` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Step indicator is role="list", not role="tablist" | WAI-ARIA APG, Carbon, Atlassian design docs |
+| aria-current="step" on active step | WAI-ARIA spec §aria-current, Carbon a11y guide |
+| Completed steps need aria-label with state | Carbon ProgressIndicator a11y docs, Atlassian |
+| Validate before Next; show inline errors | Carbon, Atlassian wizard pattern guidelines |
+| Explicit Next/Back/Submit text labels required | Material 3, Carbon, Mantine |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Step indicator using role="tablist" (incorrect — steps are not tabs)
+grep -rn 'stepper\|wizard\|step-indicator\|StepIndicator' src/ | grep 'role="tablist"'
+
+# Missing aria-current on active step
+grep -rn 'stepper\|wizard\|\.step\b\|step--active\|step--current' src/ | grep -v 'aria-current'
+
+# Step connector lines not aria-hidden (extraneous AT noise)
+grep -rn 'step.*connector\|connector.*step\|\.step-line\|StepConnector' src/ | grep -v 'aria-hidden'
+
+# Icon-only Next/Back buttons (no text label)
+grep -rn 'wizard.*next\|stepper.*next\|wizard.*back\|stepper.*back' src/ | grep -v 'Next\|Back\|Continue\|Submit\|aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: stepper using <ul role="tablist"> with <li role="tab"> — semantically wrong -->
+<ul role="tablist" class="stepper">
+  <li role="tab" aria-selected="true" class="step step--active">
+    <span class="step-number">1</span>
+    <span class="step-label">Account</span>
+  </li>
+  <li role="tab" aria-selected="false" class="step step--upcoming">
+    <span class="step-number">2</span>
+    <span class="step-label">Profile</span>
+  </li>
+  <li role="tab" aria-selected="false" class="step step--upcoming">
+    <span class="step-number">3</span>
+    <span class="step-label">Confirm</span>
+  </li>
+</ul>
+```
+
+**Why it fails**: `role="tablist"` implies that all tabs are independently activatable and content switches freely — this is correct for Tabs but wrong for a wizard where steps are gated. AT users expect arrow-key navigation between tabs; in a wizard this would allow jumping to uncompleted future steps. `aria-selected` is the tab token; the correct token for a wizard is `aria-current="step"`.
+**Grep detection**: `grep -rn 'role="tablist"' src/ | grep -i 'step\|wizard'`
+**Fix**: Replace `<ul role="tablist">` with `<ol role="list">` (ordered list signals sequence), each `<li>` with `role="listitem"`, remove `aria-selected`, and add `aria-current="step"` to the current step. Make only completed steps keyboard-focusable (as `<button>`) in non-linear mode; upcoming steps are not interactive.