Stepper

Usage

import { Stepper } from '@epasslive/design-system'

const steps = [
  { id: 's1', label: 'Browse', description: 'Find events near you' },
  { id: 's2', label: 'Buy', description: 'Secure checkout in seconds' },
  { id: 's3', label: 'Enjoy', description: 'Show your ticket at the door' },
]

// Progress tracker (default mode)
<Stepper ariaLabel="How it works" steps={steps} currentIndex={1} />

// Marketing walkthrough — neutral numbered steps, no progress state
<Stepper ariaLabel="How it works" steps={steps} mode="explainer" />

// Clickable steps (function prop — render from a client component)
<Stepper
  ariaLabel="Checkout progress"
  steps={steps}
  currentIndex={1}
  onStepClick={(index) => goToStep(index)}
/>

Visual structure (DM-18 three-state, 2026-08-22)

┌───────────────────────┐
│ [✓] Browse            │  circle: btn-primary fill + check tick (completed)
│   Find events...      │  text: min-w-0 flex-1, wraps naturally
└───────────┬───────────┘
            ━━━  connector: flex-1 h-0.5, teal (this leg is done) — aria-hidden
┌───────────────────────┐
│ [2] Buy     (current) │  circle: btn-primary fill + ring-4 ring-ep-teal/20
│   Secure checkout..   │  <li> carries aria-current="step"
└───────────┬───────────┘
            ━━━  connector: border color (this leg is not done yet)
┌───────────────────────┐
│ [3] Enjoy             │  circle: bg-secondary + border, muted number
│   Show your ticket..  │
└───────────────────────┘

Contrast (DM-18): completed/current circles are --ep-btn-primary with an
inverse number/tick — 5.70:1 AA (raw teal was 3.08:1 FAIL). Connectors
stay raw teal: decorative, aria-hidden.
Layout (P5f/P5g/P5h, still current): all columns flex-1 min-w-0 (equal
width); circles flex-shrink-0 (always round); text wraps; connector sits
on the circle's centre line.

Modes — progress vs explainer

mode="progress" (default) is for flows where "where am I?" matters — checkouts, wizards, multi-step forms: completed steps tick, the current step rings and carries aria-current="step", future steps are muted (and disabled when clickable). mode="explainer" is for marketing 1-2-3 walkthroughs ("Browse → Buy → Enjoy") that must not read as "you are mid-checkout": neutral numbered steps, no tick, no ring, nothing disabled. See the live "Explainer mode" preview above.

Step count — 3-6 recommended

3-6 steps is the recommendation (NASA Rule 2); outside that range the component logs a dev-only warning — nothing throws in production. Reality today: the production consumer EventEditorNav passes 7 steps for legacy parity (the legacy event editor had 7 sections), so the dev warning fires in dev builds of the dashboard. A bound decision (relax to ≤8 vs restructure the editor nav) is queued for cascade step 6.

Accessibility

The root element is an <ol role="list"> with an aria-label. Each step is an <li role="listitem">; the current step has aria-current="step" (progress mode only). Steps render as <button type="button"> when clickable, with a focus-visible teal ring. Disabled steps have aria-disabled="true" and tabIndex={-1}.

Touch targets — current state (honest): the hit target is the full circle+label row, but --ep-tap-min (44×44, WCAG 2.5.5) is not yet enforced on the step button — at size="sm" (24px circle) targets can fall below 44×44. A min-h/min-w-[var(--ep-tap-min)] fix is queued (cascade step 6).

Known gap (fix queued): step completion is conveyed visually only — the tick and the filled circle both sit inside an aria-hidden="true" span, so screen readers hear the label but not "completed". An sr-only completed announcement is queued (cascade step 6).

Changelog

• DM-18 (2026-08-22): completed/current circles moved from raw teal (3.08:1 — WCAG AA FAIL with inverse glyph) to btn-primary (5.70:1 AA PASS, theme-stable light + dark). Upcoming stays muted + border; connectors stay raw teal (aria-hidden decorative track).
• Explainer mode (2026-08-20): mode prop added — progress semantics became opt-out for marketing walkthroughs.
• D-HOME-P5e (2026-08-11, reverted 2026-08-12): briefly unified all circles to the same teal + shadow-lg. Reverted the next day — a run of identical circles showed no progress at all and regressed the event editor's step bar. Three states restored in D-UI-08.
• P5f (2026-08-11, still current): equal column widths via flex-1 on all <li>
• P5g (2026-08-11, still current): flex-shrink-0 on circles prevents horizontal compression
• P5h (2026-08-11, still current): layout mechanics — text wraps naturally, connector sits on the circle's centre line, items-start alignment

Used by

• HowItWorks — packages/storefront/src/components/storefront/HowItWorks.tsx (storefront home marketing section; switches to variant="vertical" below md via matchMedia). Currently runs default progress mode with a static currentIndex={1}; adopting mode="explainer" is queued (cascade step 6).
• EventEditorNav — packages/storefront/src/components/dashboard/EventEditorNav.tsx (dashboard event editor; clickable steps via onStepClick + allowJumpAhead for edit-existing-events, size="sm", 7 steps — see Step count).

Props