Stepper · Step

Stepper — where the user is in a flow with named steps: onboarding, a new client, a multi-page setup.

Beta · Navigation and overlay · packages/css/src/components/stepper.css

.pui-stepper · .pui-step (--complete --current / aria-current="step"; __circle __label). The connector grows between steps.

Stepper · Step — every size and every stateOpen in the workshop

Sizes across, states down. It is 736 px wide, more than this column holds — scroll the frame sideways, or open it in the workshop.

What it is for

• Steps 1–4 exposed — label, number, State; Has step 4 (three- or four-step flows; a flow may run to six steps — the component carries four today, and a five- or six-step row is a later addition)
• One row, horizontal, 720 wide in the specimen; a vertical stepper is a later variant
• The flow’s Back and Next (Questionnaire’s footer, or the page’s) move the current step; a completed step may be a link

Use when a flow has three to six named steps a user may look back at — add a client, set up an account, onboard a publisher.

Do not use when the steps have no names worth a rail (Questionnaire’s Progress); a single form; a checklist that is not ordered (Checkbox list); a task’s share (Progress).

Relates to Step, Questionnaire, Progress, Breadcrumb, Tabs, Button group.

Anti-patterns seven or more steps · a stepper that is also tabs (steps are ordered) · a current step without its number · a fill changed on the instance.

Keywords: stepper, wizard, steps, flow, onboarding, new client

Figma — page Stepper: Stepper (1 variants) · Step (3 variants)

The markup — copy this

The class, the parts, and nothing that is not in the package. The same block opens stepper.css.

<ol class="pui-stepper">
  <li class="pui-step pui-step--complete"><span class="pui-step__circle"><span class="pui-icon">…check…</span></span><span class="pui-step__label">Details</span></li>
  <li class="pui-step pui-step--current" aria-current="step"><span class="pui-step__circle">2</span><span class="pui-step__label">Budget</span></li>
  <li class="pui-step"><span class="pui-step__circle">3</span><span class="pui-step__label">Creatives</span></li></ol>

The modifiers

	What it is	Note
State	(none) upcoming · --current / [aria-current=“step”] · --complete	—

Rule — a step is a place, not a button — Back and Next move between them.

Accessibility — measured, not assumed

Every number here is measured on the rendered component: contrast (npm run contrast:render), the focus ring (npm run focus) and the keyboard (npm run keyboard). The floors are principle 12’s.

Contrast

ink on ground	reads	floor	the matrix calls it
#544d4d on #ffffff	8.24	4.5	text.muted on surface.page (promised)	ok
#0b0202 on #ffffff	20.51	4.5	text.default on surface.page (promised)	ok
#ffffff on #0b0202	20.51	4.5	Primary button label (promised)	ok

3 distinct pair(s) rendered, 0 that axe calls a violation.

The focus ring

Nothing in this component takes focus.

Keyboard

Nothing in this component claims an ARIA role with a keyboard contract; its controls are ordinary ones and the browser already gives them their keys.

Tab order across the whole library is document order over 344 stops, and Shift+Tab is its exact reverse — no keyboard trap anywhere (WCAG 2.1.2).