> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wizard UX Standard

> Version: 1.1

**Version:** 1.1

**Last Updated:** 2026-04-14

This document defines the standard wizard and multipage form experience across Encore Health OS, aligned with the v0-multi-form-wizard employee onboarding style.

***

## Quick Reference

| Need                                | Use                                              |
| ----------------------------------- | ------------------------------------------------ |
| Dialog-based wizard (import, setup) | `DialogWizardShell` + `layout="horizontal"`      |
| Full-page wizard (5+ steps)         | `WizardShell` + `layout="timeline"` or `sidebar` |
| Template-driven module wizard       | `ModuleWizardRenderer`                           |
| Multi-page FW form                  | `MultiPageFormRenderer`                          |
| Completion/success step             | `WizardCompleteStep`                             |
| Step transition animation           | `StepTransition`                                 |
| Touch target minimum                | 44px for step controls and nav buttons           |

***

## Layout variants

Use one of three layout variants via `WizardShell` or `ModuleWizardRenderer`:

| Layout         | When to use                                       | Desktop                                                                                    | Mobile                                 |
| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- |
| **horizontal** | Simple 3-5 step wizards, dialog wizards           | Sticky header with horizontal step circles + labels, full-width content, sticky footer nav | Same; labels optional on small screens |
| **timeline**   | Complex full-page wizards (5+ steps)              | Vertical timeline sidebar (w-56) with connecting lines, bordered card content              | Dot indicators + progress bar          |
| **sidebar**    | Data-heavy operational wizards (e.g. payroll run) | Full sidebar (w-72) with nav list, progress %, context card                                | Dot indicators                         |

* **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](../../.cursor/rules/dialog-size-standards.md).

***

## When to use which renderer

Choose the right component based on where the flow is defined:

| Renderer                            | Use when                                                                         | Typical usage                                                                                            |
| ----------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **MultiPageFormRenderer**           | The multi-step flow is defined by an FW form (`fw_forms` with pages/settings).   | FormEmbed, portal forms, form previews.                                                                  |
| **ModuleWizardRenderer**            | The flow is defined by a PF-41 wizard template (`pf_wizard_templates`).          | Module-specific wizards: onboarding, admission, payroll run, budget creation, etc.                       |
| **WizardShell / DialogWizardShell** | Building a custom (hardcoded) wizard with ad-hoc steps not driven by a template. | Import dialogs, setup wizards, inline operational wizards (e.g. contact import, bulk credential import). |

**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](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).

***

## Navigation

* **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

| Scenario                                                           | Preferred draft mechanism                  | Storage target                           |
| ------------------------------------------------------------------ | ------------------------------------------ | ---------------------------------------- |
| FW form-driven multi-page flow (`MultiPageFormRenderer`)           | `useFormDraft` / forms draft hooks         | `fw_form_submissions` (`status='draft'`) |
| PF-41 template wizard (`ModuleWizardRenderer`)                     | `@/platform/wizards` draft/progress hooks  | `pf_wizard_executions`                   |
| Hardcoded wizard with no template and module-specific requirements | Module-local draft hook (only when needed) | Module-specific/local storage strategy   |

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

***

## References

* [.cursor/rules/wizard-patterns.md](../../.cursor/rules/wizard-patterns.md) — Quick-reference for AI agents
* [.cursor/rules/dialog-size-standards.md](../../.cursor/rules/dialog-size-standards.md) — Dialog size tiers
* [WIZARD\_DEVELOPMENT\_GUIDE.md](WIZARD_DEVELOPMENT_GUIDE.md) — Full development lifecycle + step icon standards
* [ICON\_GUIDE.md](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