| name | states |
| description | Design the $machine section — map happy paths, error paths, and all state types into a complete behavioral skeleton |
States: State Machine Design
Design the $machine — the behavioral skeleton of a UXSpec. Every state is a promise to the user about what they can do and what they'll see.
When to Use
When building or revising the $machine section. Also useful for auditing an existing spec's state coverage.
Process
1. Map the Happy Path
Start with the ideal flow: entry → action → outcome. Define compound states (parents) and leaf states (children). Every compound state needs an initial child.
idle --SUBMIT--> loading
loading --HTTP_OK--> success
2. Map the Unhappy Paths
For every transition, ask: what else could happen?
- Network failure — timeout, server error, no connection
- Validation failure — bad input, missing fields, format errors
- Permission failure — expired session, insufficient role, rate limited
- Concurrent conflict — double submission, stale data, race condition
Each failure needs a state (or at least a handled transition) — not just an afterthought.
3. Cover All State Types
A complete machine accounts for:
- Empty — no data yet, no results, first-time use. These are onboarding opportunities.
- Loading — initial fetch, pagination, background refresh. Each may need different visuals.
- Error — network, validation, permissions, rate limiting. Each needs different copy and recovery.
- Success — confirmation, next steps, celebration. What happens after the goal is met?
- Partial — some data loaded, some fields valid. Don't force all-or-nothing.
4. Simplify
For each state, ask: is this truly necessary?
- Can two states merge? (e.g., "loading" and "refreshing" might be one state with a context flag)
- Is a state reachable? (orphaned states are dead weight)
- Does every state have a way out? (no dead ends)
- Look for the 20% of states delivering 80% of value.
5. Wire Transitions
- Map events to transitions with optional guards and actions
- Add
entry/exit actions (set loading flags, clear errors, reset forms)
- Add
invoke for long-running effects (HTTP calls, timers, polling)
- Use
always transitions with guards for automatic routing (e.g., redirect if already authenticated)
Diagram
Present the state graph as text before writing JSON:
idle --SUBMIT--> loading
loading --HTTP_OK--> success
loading --HTTP_ERROR--> error
error --RETRY--> loading
success --RESET--> idle
Principle
A state machine is a contract: "in this state, these things are true and these things are possible." If a state doesn't change what the user sees or can do, it doesn't belong.
