Featured image from my graph theory class in MiNI in 2015.
Lessons from a few years of working on WordPress.com’s signup flows. You can see the code and a short video here. If you want your agent to use this for inspo, please point it to my AGENTS.md.
Since most of us consume sign-up flows more than we construct them, we tend to assume sign-up flows are linear narratives, so this is the first mistake you’ll make when designing a flow; assuming it’s a linear flow during construction, even though it is only linear during consumption.
It is linear until you want a “skip” button. Or logged-in users shouldn’t see the account step. Or a user opens two tabs at your flow. Or users in the EU should accept some terms. Or there’s an A/B test, and a partner campaign with its own copy. Six months later, your neat array of steps is spaghetti, and nobody knows why the second step sends people to the sixth in some edge cases.
I’ve watched this happen over and over with linear signup frameworks. At WordPress.com we eventually built a framework called Stepper that finally fixed this. But the framework isn’t the interesting part, it’s the philosophy, so here goes.
Rule 1: A flow is a graph, not a list
The first thing to accept is that a wizard is not a series of steps. It’s a graph. Only the first step is known upfront. Every next step depends on what the user submitted, whether they’re logged in, what they already own, which experiment they’re in, hell even the weather.
I say a graph, but ideally you should treat it as a finite-state machine: a fixed set of states, and the user is always in exactly one of them. But this is difficult to enforce across multiple flows and owners, so you need a restrictive framework to help guide flow creators into that thinking. Stepper is one of these frameworks.
Rule 2: Steps are dumb by design
Steps should have zero understanding of the flow they’re running in. Consider HTML form inputs, is there any business logic inside them? No. The logic is the form’s job, not the radio buttons and the checkboxes. Steps should mimic form inputs; to only submit the info they collected from the user.
Steps shouldn’t make decisions or talk to each other.
A step should behave like a native <input>. It may receive some props, it may have some internal state (think of a checkbox), and it submits a value. That’s it. A good step:
- Doesn’t navigate. No “go next”, “go back”, or “exit”.
- Doesn’t talk to other steps. No sneaky query params or globals.
- Doesn’t have side effects. No writing to local storage, no API calls that change things.
- Doesn’t know which flow it’s in, nor the names of the other steps.
“But what if the user wants to skip?” Then the step submits { action: 'skip' }, and the flow decides what skipping means.
Here’s what it looks like when you break this rule:

On the right, every arrow is a hidden dependency, and the state machine is thrown out of the window. It even gets worse once steps are reused in other flows: a side effect that a step has in flow A quietly changes how it behaves in flow B. On the left, there’s a single place where all the thinking happens. You can read the whole flow in one file.
The smarter the step, the more fragile the flow. Treat your steps as buttons.
Rule 3: The flow is the brain
If the steps don’t decide, something has to. A flow is essentially one function that receives every submission, stores what matters, and picks the next state.
function onSubmit( step: StepName, data: Submission ) { switch ( step ) { case 'name': state.name = data.name; return goTo( 'plans' ); case 'plans': state.plan = data.plan; startTask( () => createSite( state ) ); return goTo( 'creating' ); case 'creating': if ( data.failed ) return goTo( 'error' ); return data.plan.isPaid ? redirect( '/checkout' ) : redirect( '/dashboard' ); }}
That switch is the graph. Nothing else. Want to add a skip button? It’s one new case. Want logged-in users to skip a step? One if, in one place.
If you use TypeScript, go one step further and declare the list of steps upfront, with the shape each one submits. Then goTo( 'plnas' ) is a compile error, and state.plan has a real type instead of any. Bugs that used to show up in production show up as red squiggles.
Rule 4: Resilience is at the edges
Users don’t walk the happy path. Often they refresh or lose connections. Sometimes they log in halfway through, others they open the link on their phone. A resilient flow survives all of that, and almost all of it follows from the rules above:
- Persist the flow’s state instead of the step’s. Since all the data passes through the flow, store it there (in a session or on the server), and a refresh loses nothing.
- Make auth a property of steps, not a step you hard-code. Mark which steps need a logged-in user, and let the flow insert the login step and bring the user back afterward. Don’t hand-roll redirects in every flow.
- Run slow work in one place, with an explicit failure state. Store your promises in your state store and have a loading step await that, then the loading step submits success or failure back to the flow.
setHeavyTask( task ); goToStep( 'loading' ) - Make every step reachable by URL. If a step can be deep-linked and rebuilt from a stored state, then refreshes, back buttons, and “continue on another device” mostly work for free.
Rule 5: Customize with props, not ifs
The most common smell I see in code reviews is if ( flow === 'black-friday' ) inside a step. It’s tempting, and it slowly turns a reusable component into a pile of special cases.
If a step is almost right for your flow, let the flow pass props instead:
- Name props after their visible effect, like
hideFreePlanorheaderText. Notconfig. - Make every prop optional, with defaults that keep today’s behavior. Other flows rely on that.
- Never change what the step submits while you’re at it. That’s a different problem.
In Stepper, this is acheived by useStepsProps hook.
Rule 6: Each flow should have a style.css
Each flow should be a folder, not a file, with a style.css in it. This allows you to style the steps in the context of the flow, without messing with the general CSS of the steps. This means you don’t mess with how other flows render the steps.
Rule 7: Plan for your flow’s death
This is subjective, but it’s worth mentioning: most flows die. Experiments end, campaigns finish, and the winning variant replaces the rest. So:
- Keep a flow’s logic, styles, and helpers in its own folder. Deleting it should be one
rm -rf. - Write down how to test it, next to the code. Future you, and your reviewers, will thank you.
- When you delete it, redirect its URL to a happy path. Old links in emails live forever.
The beauty of TypeScript
Wizards are mostly glue. Step A’s output becomes step C’s input. Typing your steps cleanly (with what they accept and what they submit) allows the flow to have a static model of all the state it will have at any point.
Step< { // This steps submits `platform` and `url` strings. submits: { platform: 'WordPress' | 'Pressable'; url: string; }; // And it accepts the following props. Adding them here will make them available in the `props` object. accepts: { title?: string; subTitle?: string; };}
Thanks to Rule 3, the flow is the only place where data moves. So you can describe that whole graph with types. Start by declaring, upfront, every step and what it submits:
Since your flow is bunch of steps, aggregating their submits gives you the state of the whole flow ✨
See the example flow here.
Conclusion
If I had to boil it down to one line: let steps collect, let the flow decide.
Before writing any code, draw the graph. If an arrow in your drawing starts from a step instead of the flow, that is your future bug. Make sure to develop a framework that prevents you from doing that.