SetupFlow

Anatomy

[WIP image]

Guidelines

When to use

A setup flow walks someone through an ordered set of decisions that ends in one explicit commit — send, create, run, publish. Every step is on the same surface: the open step is expanded, the ones behind it have collapsed into one-line summaries of what was chosen, and the ones ahead are numbered and inert.

Reach for it when all of these hold:

• There are two to five dependent decisions. Later steps are shaped by earlier ones, so the order is part of the design rather than an arbitrary sequence.
• The whole configuration should be reviewable before it is committed. Collapsed summaries keep every decision on screen, and the last step restates them.
• Abandoning midway should discard cleanly. Nothing is saved as you go; a half-filled flow that is closed leaves nothing behind.

Do not use one when:

• It is a single form. A set of fields with one submit is a Form with a FormLayout, not a flow. Splitting one form into steps adds ceremony without adding structure.
• The settings are independent and each saves on its own. That is a settings page built from Panels. A flow implies the decisions add up to one thing.
• You only need to show progress across separate screens. Use a Stepper — see the wizard layout pattern.
• The sections are optional and can be opened in any order. Use an AccordionGroup.

Closing a flow

A flow with unsaved input should guard the way out. Closing the surface it sits on opens a ConfirmationModal: a critical confirm labelled Discard, and a cancel labelled Keep editing. A flow that nobody has typed in closes silently — a confirmation there is noise, and noise trains people to dismiss the next one without reading it.

This belongs to whatever holds the flow, not to the flow itself. The flow tracks which step is open; it does not know whether the surface around it may go away.

SetupFlow vs. Stepper, AccordionGroup, and Form

• SetupFlow keeps an ordered set of dependent decisions on one surface, collapsing each finished step into a summary and ending in a single commit.
• Stepper is a progress indicator. It says where you are in a flow whose steps live on separate screens; it holds no content of its own.
• AccordionGroup shows independent sections that open in any order. Nothing about it says one section has to come before another.
• Form collects a set of fields and submits them together. Reach for it whenever the fields do not depend on each other enough to need an order.

The distinction is dependence. If the steps could be filled in any order without anything changing, the flow is imposing a sequence that is not really there.

Step dependence

Order the steps so each one only asks for what the ones before it have made answerable. A step that could just as well come first is a sign the flow is really a form.

The same dependence works in reverse: editing a finished step leaves the steps after it intact unless the change genuinely breaks their values. Resetting the rest of the flow because someone corrected a name throws away work that was never in question.

Best practices

Final step

The last step is a read-only review of every decision above it, and the commit is the only primary action on it. It never collapses and it has no summary, because it is not a decision — it is the moment of deciding to go ahead.

Step count

Two to five steps, including the review. Fewer than two is a form wearing a flow's clothes. More than five turns a configuration into an errand, and the collapsed summaries stop fitting on one screen — which is the whole reason for the shape.

Length is the other half of the same rule: if a step needs its own scrollbar, it is doing too much and should be split. If two steps are always answered together, merge them.

Summaries

A step shows its summary whenever it is not the open one and has values to show, so give a step its summary once it holds real values and not before. A summary on a step nobody has reached yet promises an answer that has not been given.

Validation

Hold the step until its required inputs are valid. The review at the end is a restatement of what was chosen, not a second chance to catch what a step should have caught, and an invalid step that advances puts its error out of sight behind a summary.

Types

A flow holds two kinds of step. Every flow has one of each: several standard steps, then a single final one.

Appearance

Markers

The marker carries a step's status as color and glyph. A step that has not been reached and the step that is open both show their number; a finished step shows a check; a step that needs another look shows a caution glyph.

Only the upcoming marker has a ring: it sits on the page's own surface, so the ring is the only thing that draws it. Every status the flow has reached is a solid filled coin, which is what separates the steps that have been answered from the ones still ahead.

A disabled step flattens its marker into the disabled palette whatever status it holds, and changes nothing else — its title and summary stay at full strength, because the disabled palette is not legible enough for text that has to be read. See Disabled steps for the contrast that rules out.

Markers are decorative. The number repeats the ordering the list already has, and the status is carried by the label, the summary, and the presence of the body beside it — so nothing is lost when the marker is not perceived. See Markers for how that is expressed.

Steps

Every step is a card, and the flow is those cards stacked with a gap between them. There is no rail or connector joining one step to the next: the order comes from reading down the stack, and the numbers in the markers say where each step sits.

Inside the card, the marker leads a header row that also carries the title and, under it, the summary. The body of the open step lines up with the title rather than the marker, so the inputs sit in one column with the words that introduce them. A step the flow has not reached yet reads a shade lighter in the title, which is what makes the answered steps and the open one stand out from the ones still ahead.

Behaviors

States

A step's status comes from the flow, not from the step itself: the open step is active, a step the flow has recorded as done is complete, and everything else is upcoming.

Advancing

Moving the flow on collapses the open step into its summary, opens the next one, and moves focus to the new step's title, so a keyboard or screen reader user lands on the step they now have to fill in rather than back at the top of the flow. A step that is unavailable is stepped straight over on the way.

A flow that has only just appeared does not take focus — arriving on a screen is not the same as being moved along by it. That holds however the first step was settled, including a flow that works out where to open a moment after it renders.

Editing

A finished step is reopened by its header row. The whole row is the target — the marker, the title, the summary, and the Edit affordance at its trailing edge — so the affordance names what activating the row does rather than being a small target of its own. Reopening a step happens in place, without unwinding the steps after it: reopening the second of five does not throw away the third, fourth, and fifth; the flow returns to that step and the rest of the configuration stays as it was.

The feature can intercept a reopen — to warn first, or to route somewhere else — and can leave the step closed if it needs to.

Invalidation

Only the feature knows what an edit breaks, so invalidation is something it declares rather than something the flow works out. Use it sparingly and precisely:

• Name what changed. A caution summary should say what stopped being true — "2 of 4 fields are no longer available" — not merely that something did.
• Keep whatever still applies. Clearing a step that is mostly still valid makes an edit more expensive than the change that caused it.
• Block the commit until it is re-confirmed. An invalidated step is an unanswered question, and the review at the end should not offer to go ahead over the top of one.
• Never invalidate for a compatible change. Renaming something that a later step refers to by name has not broken anything. A caution marker that turns out to be nothing teaches people to click past the ones that are not.

Content

Step titles

Step titles are short verb phrases in sentence case, parallel in form across the flow, describing the decision rather than the subject.

Mark inputs that can be skipped with a trailing "(optional)" on the field label, the same as anywhere else — a step whose inputs are all optional still has to say so, because a collapsed step with no summary otherwise looks unanswered.

Summary text

A summary is the values that were chosen, not a description of what the step was for. Someone scanning a finished flow is reading their own answers back.

Keep a summary to one line. If the step made more decisions than fit, summarize the ones that would change someone's mind about reopening it and let the step itself hold the rest.

The commit action

The action on the final step names the outcome: Create export, Send for previews, Publish campaign. Finish and Done describe the flow rather than what it does, and a flow is not what anyone came for.

The steps before it all move the flow on, so they all say Continue. Numbering them — Continue to step 3 — repeats what the markers already show.