thedaviddias/wizard

Wizard / Stepper

Multi-step forms and processes

What it solves

A Wizard / Stepper pattern helps teams create a reliable way to break a long process into ordered steps with visible progress and review checkpoints. It is most useful when teams need onboarding and setup. Compared with adjacent patterns, this pattern should reduce friction without hiding the state, rules, or recovery paths people need to keep moving.

When to use

• Onboarding and setup
• Checkout and application flows
• Multi-step internal tooling

When to avoid

• Use a simpler visible navigation or single-page flow when the product surface is still small.
• Avoid advanced interaction patterns if the team cannot support their state complexity well.
• Do not introduce hidden power-user behavior before the plain path is already strong.

Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example.
2. Start from the anatomy and examples in references/pattern.md, then choose the smallest viable variation.
3. Apply accessibility, performance, and interaction guardrails before layering visual polish.
4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

Accessibility guardrails

Keyboard Interaction

• [ ] Verify that wizard / stepper can be completed using keyboard alone.
• [ ] Keep focus order logical when the pattern opens, updates, or reveals additional UI.
• [ ] Preserve a visible focus state that is still readable at high zoom.

Screen Reader Support

• [ ] Use semantic elements first, then add ARIA only where semantics alone are not enough.
• [ ] Announce state changes such as errors, loading, or completion in the right place and with the right politeness.
• [ ] Connect labels, hints, and status text with aria-describedby or structural headings when useful.

Visual Accessibility

• [ ] Do not rely on color alone to convey severity, completion, or selection state.

Common mistakes

Designing only the happy path

The Problem: The pattern feels polished until loading, empty, and failure states appear.

How to Fix It? Specify the full lifecycle alongside the default state so implementation does not improvise later.

Letting interaction and content drift apart

The Problem: Users work harder when controls, status, and supporting information feel disconnected.

How to Fix It? Keep the information architecture of the pattern close to the interaction model.

Treating accessibility as a final pass

The Problem: Keyboard, announcement, and reading-order issues become expensive once the interaction is already fixed.

How to Fix It? Bake semantics, focus behavior, and announcements into the first implementation.

Related patterns

• https://uxpatterns.dev/patterns/e-commerce/checkout
• https://uxpatterns.dev/patterns/forms/form-validation
• https://uxpatterns.dev/patterns/user-feedback/progress-indicator

---

For full implementation detail, examples, and testing notes, see references/pattern.md.

Pattern page: https://uxpatterns.dev/patterns/advanced/wizard