Multi-step wizard

Linear or branching multi-step flow with per-step validation, step indicator, back-stack semantics, review step, and submit + error recovery. Common in onboarding, provisioning, data import. Modeled after PatternFly Wizard.

Pattern — Multi-step wizard

*tatus* v0.1.0 — Draft. Covers linear + branching variants.

R1 — Linear vs branching

Variant	Use when	Example
inear	Every user goes through the same N steps in fixed order	Onboarding (4 steps), data import (preview → map → validate → commit)
ranching	Step 2 outcome determines which steps 3+ are shown	"What kind of org are you?" → Educational vs Commercial branches

If branches diverge for more than half the remaining steps, consider splitting into two separate flows instead of branching.

R2 — Step indicator

Viewport	Indicator placement
≥ 900px (desktop / tablet)	Vertical sidebar on the left, 240px wide
< 900px (mobile / narrow)	Horizontal progress bar at top: `Step 2 of 4` + dots

Each step entry: number + label + checkmark (when complete) + current-step highlight.

R3 — Per-step validation gate

Next button disabled until step's required fields valid + async checks pass.
Inline error messages appear under each invalid field (per specs/errors/user-facing-messages.kmd).
Wizard does NOT advance to next step if the current step has any pending async validation.

R4 — Back-stack semantics

Back button: returns to previous step. Field values preserved.
Browser back / system back: same behavior (does NOT exit wizard; returns to previous step).
Exit / Cancel: explicit affordance separate from Back; confirms via modal if any data was entered ("Discard 4 fields?").

R5 — Skip semantics

Optional steps render Skip button alongside Next.
Skipping marks step as "skipped" (gray ↷ in indicator) not "complete".
Required steps NEVER show Skip.

R6 — Reviewandsubmit step

Final step is always a Review screen summarizing all collected data, grouped by step.
Each section has an Edit link that jumps back to that step (preserving subsequent step data).
Primary action labeled with the verb that describes the outcome (Create workspace, Import file, Activate plan) — never generic Submit.

R7 — Error recovery on submit

If submit fails, return user to the step containing the offending field with the error message inline.
If failure is server-side / network: stay on Review step with a banner error + retry button.
Telemetry: log step-completion times + abandon points (per product instrumentation, not KDS spec).

R8 — Accessibility

Step indicator: role="list" with each step as role="listitem"; current step has aria-current="step".
Wizard container: focus moves to the new step's heading on advance.
Live-region announces step transitions ("Step 2 of 4: Account details").
Keyboard: Enter on Next/Back honors the button; Tab navigates fields; Esc opens Cancel confirm.

Não-escopo

Persistence across sessions (product-level concern).
A/B-tested step copy variations (product concern).
Specific form library choice (transport-agnostic).