Guided Flows

Overview

Guided flows are step-by-step workflows that help users complete a task with:

• progressive disclosure
• focused decisions
• contextual explanation
• a final review or consequence preview

This pattern is broader than "create new thing." In this system, it is a good fit for:

• create flows
• import flow
• onboarding and setup
• assignment and ownership workflows
• conversion or strategy changes
• review-before-commit workflows

The main component implementation for this pattern is GuidedFlow.

When Guided Flow Fits

Use a guided flow when:

• the task has a clear sequence
• showing everything at once would feel noisy or intimidating
• later choices depend on earlier context
• users benefit from explanation between steps
• a final review materially reduces errors

Good examples:

• import a franchisee and decide entity assignment plus invite behavior
• onboard a workspace through several setup choices
• guide a user through converting or reconfiguring an object
• step through permission or strategy choices before applying them

When It Does Not Fit

Do not use a guided flow when:

• the form is simple enough to show all at once
• each step is really a full independent workspace
• the process has too many branches to feel linear
• there is no meaningful reason to split the task into stages

In those cases, a normal form, Panel, or multi-screen workflow is often a better fit.

Core Pattern

A strong guided flow usually includes:

1. A clear step question
2. Only the fields needed for that step
3. Optional contextual help
4. ProgressionPips that show step progress and support guarded navigation
5. Step actions such as Back, Continue, and the final commit action
6. A review or preview step before commit when it materially reduces mistakes

<GuidedFlow.ProgressionPips
  steps={steps}
  currentStep={currentStep}
  onStepClick={goToStep}
  canNavigateToStep={(stepIndex) => stepIndex <= furthestStep}
/>

<GuidedFlow.Step stepKey={currentStep} direction={stepDirection}>
  <GuidedFlow.StepQuestion title="Who are you adding?" />
  {/* step fields */}
</GuidedFlow.Step>

ProgressionPips should generally be used in guided flows.

They help the user understand:

• how many meaningful steps remain
• where they are in the flow
• whether they can return to an earlier step

Without them, guided flows are much easier to misread as disconnected screens instead of one staged workflow.

ProgressionPips Rule

Treat GuidedFlow.ProgressionPips as the default navigation treatment for guided flows.

Use them in almost all cases where:

• the flow has a known step sequence
• the user benefits from seeing overall progress
• earlier choices unlock later steps

The main exception is a path-selection first step.

If the first step is only choosing a path and that choice determines how many real steps exist, do not show ProgressionPips on that first step yet.

Instead:

• let the user choose the path first
• derive the actual step list from that choice
• start showing ProgressionPips once the real step sequence is known

This avoids lying about the step count before the workflow has actually branched.

const activeSteps =
  selectedPath === null ? [] : getStepsForPath(selectedPath);

{selectedPath !== null && (
  <GuidedFlow.ProgressionPips
    steps={activeSteps}
    currentStep={currentStep}
    onStepClick={goToStep}
    canNavigateToStep={(stepIndex) => stepIndex <= furthestStep}
  />
)}

Step Design Rules

Keep Each Step Focused

Each step should answer one question well.

Good:

• "Who are you adding?"
• "What entity are they a part of?"
• "Send portal invite?"

Bad:

• mixing identity, ownership, permissions, and notifications all in one step

Reveal Complexity Gradually

Only introduce later operational choices after the user has supplied the earlier context they depend on.

This is one of the main reasons to use a guided flow instead of a large form.

If the opening step is just choosing which path the flow should take, treat that as setup for the flow rather than as part of the visible pip sequence.

End With Review

A final preview or summary step is usually worth it when the workflow:

• creates something significant
• triggers downstream automation
• affects ownership or permissions
• sends notifications or invitations

Steps Need Clear Actions

Every guided-flow step should have clear actions.

Typical patterns:

• intermediate steps use Back and Continue
• the final meaningful step owns the commit action such as Create, Import, Assign, or Finish
• optional step clicks through ProgressionPips should still respect guarded navigation rules

The user should always understand whether they are:

• moving to the next step
• returning to a previous step
• actually completing the workflow

Success State Rule

A guided flow may show a success state, but it should not appear as an extra step in the visible progression.

If a success state is used:

• the commit action still belongs to the true final step
• the success state replaces that final step after completion
• ProgressionPips should continue to reflect only the meaningful decision or review steps

This keeps the visible step count honest and makes it clear to the user when they are already on the last real step.

If the success message adds little beyond confirmation, prefer closing the flow, refreshing the surrounding context, opening the resulting entity, or showing a toast instead.

Modal Vs Panel Vs Page

In A Modal

Use a modal when:

• the flow is focused
• there are only a few steps
• the user should stay anchored to the current page

This is the current strongest implementation pattern for GuidedFlow.

Keep the whole guided flow inside that one modal.

Do not:

• open another Modal on top of it
• open a Panel on top of it

In A Panel

Use a panel when:

• the flow is part of a broader object-management workflow
• the user may need surrounding detail context while completing it

On A Full Page

Use a full page when:

• the process is long enough to deserve its own workspace
• the surrounding information architecture matters more than local context

Navigation Rules

Allowing step clicks is useful, but only when it does not undermine the workflow.

Prefer:

• free navigation back to completed steps
• guarded navigation forward
• explicit continue/back controls

Avoid:

• letting users jump into future steps with no required context

Representative Usage

Relationship To Forms

Guided flows often contain forms, but they are not just a form pattern.

Use GuidedFlow when the important thing is the staged workflow and the user’s confidence through it.

Use a normal form when:

• the user can understand everything at once
• the fields do not need to be sequenced
• a review step would not add real value

Guidelines

• Do use guided flows for staged decisions with meaningful review
• Do keep each step narrowly focused
• Do use contextual help only where it genuinely clarifies the decision
• Do end with a preview when the workflow has important consequences
• Do keep modal-based guided flows inside a single modal shell
• Do use GuidedFlow.ProgressionPips by default
• Do hide ProgressionPips on an initial path-selection step until the real step count is known
• Do make each step’s action explicit, especially the final commit action
• Do replace the final step with a success state instead of adding a separate extra success step when a success state is genuinely useful
• Don't use a guided flow just to make a simple form feel more impressive
• Don't stack a Modal or Panel on top of a modal-based guided flow
• Don't show misleading pip counts before the user has chosen a branch that defines the real flow
• Don't add a counted extra success step after the user has already reached the final real step
• Don't split a flow into steps unless the steps improve comprehension or reduce mistakes