Skip to main content

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.

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

NeedUse
Dialog-based wizard (import, setup)DialogWizardShell + layout="horizontal"
Full-page wizard (5+ steps)WizardShell + layout="timeline" or sidebar
Template-driven module wizardModuleWizardRenderer
Multi-page FW formMultiPageFormRenderer
Completion/success stepWizardCompleteStep
Step transition animationStepTransition
Touch target minimum44px for step controls and nav buttons

​
Layout variants

Use one of three layout variants via WizardShell or ModuleWizardRenderer:
LayoutWhen to useDesktopMobile
horizontalSimple 3-5 step wizards, dialog wizardsSticky header with horizontal step circles + labels, full-width content, sticky footer navSame; labels optional on small screens
timelineComplex full-page wizards (5+ steps)Vertical timeline sidebar (w-56) with connecting lines, bordered card contentDot indicators + progress bar
sidebarData-heavy operational wizards (e.g. payroll run)Full sidebar (w-72) with nav list, progress %, context cardDot 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.

​
When to use which renderer

Choose the right component based on where the flow is defined:
RendererUse whenTypical usage
MultiPageFormRendererThe multi-step flow is defined by an FW form (fw_forms with pages/settings).FormEmbed, portal forms, form previews.
ModuleWizardRendererThe flow is defined by a PF-41 wizard template (pf_wizard_templates).Module-specific wizards: onboarding, admission, payroll run, budget creation, etc.
WizardShell / DialogWizardShellBuilding 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 § 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

ScenarioPreferred draft mechanismStorage target
FW form-driven multi-page flow (MultiPageFormRenderer)useFormDraft / forms draft hooksfw_form_submissions (status='draft')
PF-41 template wizard (ModuleWizardRenderer)@/platform/wizards draft/progress hookspf_wizard_executions
Hardcoded wizard with no template and module-specific requirementsModule-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 — 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