State Machine Sketch
Lists every state a feature can be in before any of them get coded, so the ugly ones are not discovered in production.
When to reach for it
Before building anything with more than two conditions on screen — a form that submits, an upload, a checkout, anything that waits on a network.
What changes
- The agent enumerates the states as a plain list — including loading, empty, partial, stale and error — before writing the component.
- Combinations that cannot happen are made impossible to represent, instead of being policed by a pile of booleans.
- Every state gets a decided appearance, including the ones normally forgotten: submitted twice, succeeded but the list has not refreshed.
- Transitions are written down, which exposes the missing ones — most often the way back out of an error.
- You review a fifteen-line list in a minute instead of finding the missing state as a blank screen next week.
Pairs with
- Motion BudgetFixes how many things may move on a screen before any of them are built, because quantity of motion gives away machine-made work faster than any single effect.
- Name Things OnceSettles what everything is called before the code is written, so one idea does not arrive under four names.
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
State Machine Sketch
Enumerate the states before writing the code that produces them.
1. List every state
Write them as a flat list of names, starting with the ones that are easiest to forget:
- Nothing has happened yet: first render, no input.
- Loading, both the first time and on a refresh that has old data to show.
- Empty — a successful result with nothing in it.
- Partial — some of it arrived, some of it failed.
- Error, split by what the person can do about it: retry, fix the input, sign in again, give up.
- Success, and then success gone stale.
- In flight after a second click on the same button.
- Offline, if that can happen here.
Delete the ones that genuinely cannot occur, and say why.
2. One state value, not five booleans
Three booleans describe eight combinations and about four of them are nonsense. Use a single value with one name per state, and attach the data each state needs to that state rather than scattering it beside it.
3. Decide what each state looks like
One line per state: what is on screen, what is disabled, where focus sits. Include the boring answers where they apply — "identical to idle, plus a spinner inside the button".
4. Write the transitions
For each state, list what can happen and where it leads. Then read the list hunting two specific gaps: a state with no way out, and an error with no path back to something working.
5. Show the sketch, then build it
Fifteen lines, read in a minute, corrected in two. Get it agreed before building a component around it.
Rules
- Do not treat loading as a kind of empty. They look identical in the data and mean opposite things to the person waiting.
- Do not leave a state undesigned and let the layout decide. An unstyled error is still a design, just not one anybody chose.
- Do not add a state for something that is really data. "Has three items" is not a state; "loaded" is.
- Do not implement a transition the sketch does not have. If you need one while coding, put it in the sketch first and check what else it changes.