Skip to main content
Version: 1.1 Last Updated: 2026-06-30
Conformance tiers (PF-135): The authoritative L0/L1/L2 wizard conformance model lives in WIZARD_DEVELOPMENT_GUIDE.md § “Wizard Conformance Tiers”. This document describes the visual/UX standard a wizard must meet at L0; it does not restate the tier definitions (PF-135 NFR-maint-1, single-canonical-source rule).
This document defines the standard wizard and multipage form experience across Encore OS, aligned with the v0-multi-form-wizard employee onboarding style.

​
Quick Reference

​
Layout variants

Use one of three layout variants via WizardShell or ModuleWizardRenderer:
  • Breakpoint: Use lg: (1024px) for desktop vs mobile. Consistent with ModuleWizardRenderer.
  • Dialog wizards: Use DialogWizardShell with layout="horizontal" (fixed) and dialogSize: sm | md | lg | xl per dialog-size-standards.

​
When to use which renderer

Choose the right component based on where the flow is defined: Wizard config types: FW-31 WizardConfig (platform/forms) and PF-41 WizardConfig (platform/wizards) are intentionally separate. on_next (FW-31) is semantically equivalent to on_advance (PF-41). Do not attempt to unify the two types. Configurable mode support: useWizardMode supports hr, rh, fa, fw, lo, fm, gr, pf, it, ce, cl, and pm using module settings use_configurable_wizards.

​
Progress and stepper

  • MUST: Show progress (stepper, dots, or progress bar) so the user knows current step and total steps.
  • Step states: Completed (checkmark), current (border-2 + icon/label “In progress”), future (muted).
  • Semantic tokens: bg-primary, text-primary, bg-success, text-muted-foreground, etc. No hardcoded colors.
  • Touch targets: Minimum 44px for step controls and nav buttons.
  • Accessibility: aria-current="step" on current step, aria-label on step buttons including “(completed)” / “(current)” where relevant.

​
Step icons

  • SHOULD: Provide a Lucide icon for each wizard step to improve visual scanning and user orientation.
  • Rendering priority: Completed step shows checkmark. Current/future step shows icon (if provided) or step number (fallback).
  • Icon sizing: size-4 (16px) inside the step circle for all layouts. Step circle is size-9 (36px) on desktop, size-11 (44px) on mobile.
  • For WizardShell (presentational): Pass Lucide icon components directly via step.icon.
  • For PF-41 templates (JSON config): Use string keys from WIZARD_STEP_ICONS catalog (e.g. "user", "calendar", "review"). Resolve with resolveStepIcon() from @/platform/wizards.
  • Consistency: Use the same icon key for semantically equivalent steps across all wizards platform-wide. See WIZARD_DEVELOPMENT_GUIDE.md § Step Icons for the recommended mapping table.
  • Anti-patterns:
    • Do not use module-level icons (e.g. the HR icon) as step icons — these represent the module, not the step’s purpose.
    • Do not repeat the same icon on every step — this defeats the purpose of visual differentiation.
    • Do not use decorative icons that don’t relate to the step’s content.

​
Step content and transitions

  • Step transition: Use StepTransition (150ms fade+slide). Auto-focus first h2 in the new step for keyboard/screen-reader users.
  • Step content: Clear step title (h2) and optional description; single main content area (card or equivalent).
  • Completion step: Use WizardCompleteStep for the final success state (icon, title, description, optional next-steps list, optional summary card, action buttons).
  • MUST: Provide Previous / Next (or Submit on last step). Footer MUST remain visible on the last step so the user can submit.
  • MUST: Preserve user input when navigating Back; do not lose step data.
  • SHOULD: Optional “Save draft” and “Exit” with confirmation when the wizard has more than one step.
  • Validation: Validate before advancing when applicable (e.g. on_advance or on_next).
  • Mobile: Prefer fixed footer for nav on small screens so Back/Next are always visible.

​
Draft and exit

  • MUST: For wizards with more than 3 steps, provide auto-save or “Save draft” so progress is not lost.
  • MUST: If the user has unsaved changes and attempts to exit (close dialog, navigate away), prompt to confirm (e.g. “You have unsaved changes. Leave anyway?”).
  • Save draft: Optional; show “Saved X ago” and “Save draft” button. Use min-h-[44px] for buttons.
  • Exit: Optional “Exit” control; confirm if there are unsaved changes.
  • Dialog wizards: Closing the dialog is the exit path; no separate Exit button required unless you want one.

​
Draft persistence decision guide

For new template-driven wizards, prefer platform wizard draft hooks over module-specific draft implementations.

​
References

  • .cursor/rules/wizard-patterns.md — Quick-reference for AI agents
  • .cursor/rules/dialog-size-standards.md — Dialog size tiers
  • WIZARD_DEVELOPMENT_GUIDE.md — Full development lifecycle + step icon standards
  • ICON_GUIDE.md — Platform icon assignment, sizing, and accessibility rules
  • src/platform/wizards/components/WizardShell/ — Shell implementation
  • src/platform/wizards/components/StepTransition.tsx — Step transition component
  • src/platform/wizards/components/WizardCompleteStep.tsx — Completion step component
  • src/platform/wizards/utils/stepIcons.ts — Step icon catalog and resolveStepIcon() utility