Wizard

Problem Context

• The task creates or configures something with dependencies, such as an integration, report, import, automation rule, device setup, or account configuration.
• Later steps depend on earlier selections or credentials and may need tests, generated previews, or external validation.
• Users need a clear path to finish or cancel without accidentally activating an incomplete setup.

Selection Rules

• Choose a wizard when the product must guide users through a strict or mostly strict setup sequence with dependent choices.
• Use multi-step form instead when the task is primarily collecting submitted answers across saved pages.
• Use step navigation only as progress display inside a wizard or multi-step form, not as the wizard logic itself.
• Use a process list when users need to understand or complete a broader process outside one controlled assistant.
• Use a single-page form when all inputs are short, related, and safer to scan together before one save.
• Gate Next, Review, and Finish using real prerequisites such as a valid choice, credential, import mapping, test result, or generated preview.
• Use step-specific primary actions when they describe the real work better than Next, such as Test connection, Map columns, Generate preview, or Confirm review.
• Provide Cancel or Close behavior that preserves, pauses, or explicitly discards setup state rather than silently losing it.
• Retest or mark later steps stale when an earlier connector, template, permission, mapping, or option changes.

Required States

• Not-started state that explains what the wizard will configure and how many major steps follow.
• Current guided step with a clear heading, local controls, and step-specific primary action.
• Disabled future step state before prerequisites pass.
• Completed step state based on saved valid setup data.
• Validation or test-failed state that keeps users on the owning step with recovery guidance.
• Generated preview or test-passed state before review unlocks.
• Review state that summarizes choices and generated consequences before finish.
• Cancel or close state that explains draft preservation or discard.
• Finished state only after required steps, tests, and review are complete.
• Stale dependent step state after an earlier wizard choice changes.

Interaction Contract

• Next validates and stores the current step before moving forward.
• Step links can move only to completed or currently available steps unless the wizard explicitly supports non-linear editing.
• Back preserves entered data and returns to the previous guided step without activating finish or rerunning side effects.
• Step-specific actions such as Run test or Generate preview must complete before Review or Finish unlocks.
• Cancel and Close never discard a partial setup without an explicit saved, paused, or discard state.
• Changing an upstream setup choice invalidates or recomputes dependent tests, previews, review summaries, and finish eligibility.
• Finish performs the final commit only once all required steps and review gates are satisfied.

Implementation Checklist

• Model wizard steps with stable IDs, route or panel ownership, prerequisites, completion rules, side effects, and stale-dependency rules.
• Write step-specific footer actions and disable or explain unavailable future steps.
• Persist draft state before navigation and restore it on Back, close, refresh, validation errors, and return from review.
• Separate local step validation from final Finish side effects.
• Provide test, preview, or generated-output states for steps that create external consequences.
• Add a review step for irreversible, high-cost, external, or generated setup changes.
• Confirm cancel or clearly communicate whether the wizard draft is saved, paused, or discarded.
• Move focus to the new step heading or first invalid control after navigation and validation.
• Test keyboard navigation through step list, footer actions, disabled steps, cancel, review change links, and final finish.

Common Generated-UI Mistakes

• Using wizard chrome for a short edit form with no dependent sequence.
• Letting users finish before required tests, previews, or review pass.
• Treating step navigation as the whole wizard while leaving draft state and finish behavior undefined.
• Hiding conditional steps until after users relied on the displayed count.
• Using generic Next on steps whose actual obligation is Test, Map, Preview, or Confirm.
• Discarding partial setup on Cancel without a warning or draft recovery.
• Keeping stale generated settings after an earlier connector or template changes.

Critique Questions

• What dependency makes this a wizard rather than an ordinary multi-step form?
• Which step-specific action proves a step is complete?
• Can users cancel safely without losing work unexpectedly?
• What later steps become stale when each earlier choice changes?
• Is Finish impossible until every required test, preview, and review gate has passed?
• Would a process list or task list be more honest because users can work out of order?