Step progress

Problem Context

• The workflow has named stages whose statuses matter independently of the current page.
• Some stages may wait on validation, document review, payment authorization, eligibility checks, approval, or background processing.
• Users may return later and need a snapshot of what is done, what is current, what is blocked, and what cannot start yet.
• The product may show the indicator inside a broader form, wizard, checkout, import, onboarding, or approval flow without making the indicator own the whole flow.

Selection Rules

• Choose step progress when users need status for named workflow stages, not only a route position.
• Mark a stage complete only after saved data, accepted upload, passed validation, approved review, or another defined proof event exists.
• Use waiting status when a stage is in progress outside the current page, such as document scan, compliance review, payment authorization, or approval.
• Use blocked or cannot-start status when a future stage depends on a prior answer, upload, permission, or system check, and provide the reason nearby.
• Use skipped status for optional or inapplicable stages so users can distinguish deliberate omission from missing work.
• Use failed status on the stage that owns the failure and keep recovery actions close to the failed stage or current page.
• Use step navigation when the indicator is primarily how users move between pages in a linear journey.
• Use progress bar when the underlying progress is numeric system work with a reliable total.
• Use meter when users need to interpret a current value inside a bounded range.
• Avoid fixed totals when dependent stages can appear or disappear; disclose inserted stages or show required versus optional groups.

Required States

• Not started or pending stage.
• Current stage with aria-current step or equivalent current-step semantics.
• Completed stage with the proof event reflected in text.
• Waiting stage for review, scan, authorization, approval, or another external event.
• Blocked or cannot-start stage with a visible reason.
• Failed stage with recovery route or retry action.
• Skipped or not-applicable stage for deliberate omissions.
• Dynamic dependent stage inserted after a qualifying answer.
• Compact responsive state that preserves current step and total or remaining context.

Interaction Contract

• The indicator reads from the same workflow state that controls route availability, validation, saved answers, and submission gates.
• Only one step is current at a time and the current item is exposed with current-step semantics.
• Completed stages retain enough text to explain what proof made them complete, such as Saved, Accepted, Approved, or Authorized.
• Blocked and failed stages expose the reason and recovery path instead of relying on a red segment alone.
• If the indicator is read-only, segments do not look clickable; if segments are navigable, unavailable stages explain why they cannot open.
• Dynamic or conditional stages do not silently rewrite history; newly required stages are introduced with text that explains why they appeared.
• Status changes are announced at meaningful transitions such as failed, ready, waiting, unblocked, or complete.

Implementation Checklist

• Define each stage ID, label, status vocabulary, proof event, owning route, recovery action, and dependency before rendering the indicator.
• Represent steps as an ordered list or equivalent semantic structure and expose the current step with aria-current="step" when appropriate.
• Keep the current step label, page heading, saved state, and route state synchronized after every Continue, Back, retry, upload, review, and background event.
• Pair icons and colors with text labels such as Complete, Current, Waiting, Blocked, Failed, Skipped, or Cannot start yet.
• Make read-only segments visually noninteractive, or implement keyboard focus and activation only for stages that users can actually open.
• Handle conditional stages by grouping them, inserting them with a reason, or excluding them from the total until they are required.
• Test revisiting after refresh, failed server validation, asynchronous completion, optional-stage skipping, inserted dependent stages, narrow layouts, keyboard traversal, and screen-reader announcements.

Common Generated-UI Mistakes

• Treating visited pages as completed stages.
• Using the indicator as the only page heading or only explanation of current status.
• Showing all future stages as clickable when prerequisites are missing.
• Hiding blocked, waiting, skipped, or failed states behind color alone.
• Using a percent progress bar for named workflow stages.
• Changing the total number of steps without explaining the dependent condition.
• Letting the visual step status drift from saved answers, server validation, or route state.

Critique Questions

• What event proves each stage is complete?
• Is this indicator reporting status, enabling navigation, or trying to do both?
• Which stage owns each validation error, failed check, waiting review, and retry action?
• Can users tell the difference between pending, blocked, waiting, skipped, and failed without color?
• How will conditional stages appear without making the total feel dishonest?
• Does the page heading, route, focus target, and current-step status all identify the same stage?