Brief Builder

Preparing Brief Builder

Restoring your progress…

How this is built

Solid = NEXT, dashed = BACK, accent labels are guard names on the transition they decide.

The graph is generated from the shipped XState machine, and machine-wide events are listed once rather than drawn from every state. Initial state: projectType. Machine-wide events: SET_ANSWERS, RESET.

Step sequences

webAppprojectType → appScope → appPlatform → constraints → contact → brief
marketingSiteprojectType → siteScope → siteContent → constraints → contact → brief
designSystemprojectType → systemAudit → constraints → contact → brief

XState v5 instead of useReducer

Decision: The flow is an explicit state machine. Branch guards, transition targets, and back-navigation live in machine data rather than reducer branches.
Why: The same definitions drive the running form and this diagram, so the documentation cannot quietly diverge from the behaviour.
Rejected: useReducer with a separately drawn diagram. The diagram would drift the first time a step moved, and nothing in the build would catch it.

Static guarded back-targets instead of a visited stack

Decision: Every BACK transition is declared in the machine and shares the same project-type guards as the forward branch.
Why: Back-navigation is part of the flow contract, so it belongs in the introspectable transition data and appears in the diagram.
Rejected: A visited-state array in context. XState v5 has no dynamic transition target, and a stack would be invisible to machine introspection.

Two state owners with one handoff

Decision: XState owns the step and direction; react-hook-form owns field state. A valid submit sends SET_ANSWERS and then NEXT.
Why: XState evaluates guards before transition actions, so a value-carrying NEXT would be judged against stale context. The two-event handoff commits values first.
Consequence: Progress is saved at step commit. Text typed since the last commit is not restored after a reload.
Rejected: Putting every field in machine context. That would re-render the machine per keystroke and duplicate the validation rules; debounced persistence would add writes and context churn without changing the useful outcome.

Direction-aware choreography with a reduced-motion alternative

Decision: Machine context carries direction. AnimatePresence uses it for a horizontal spring, while reduced motion substitutes a 120 ms crossfade and removes the error shake.
Why: The restored session already knows which way it was moving, and mode="wait" keeps one step in the DOM so heading focus is unambiguous.
Rejected: Animating layout or height. Text reflow makes those transitions jank-prone and can move a focus target during the transition.

Focus the step heading, not the first field

Decision: Each incoming step focuses its heading, while a persistent polite live region announces the step count and title.
Why: Screen-reader users receive the new context before being dropped into a field. The live region never remounts, so the announcement is reliable.
Rejected: Autofocusing the first control. It skips the heading and leaves the user hearing a field label without knowing which step it belongs to.

What the HUD measures here: Nothing here is drawn per frame, so this route has no frame rate of its own. The FPS and ms/frame rows say exactly that instead of reporting the display’s cadence, and the three rows below them are what the route does cost: the milliseconds between your last interaction and the paint that answered it, the number of tasks long enough to block a paint since the HUD mounted, and the step transitions counted this session. The first two are read from the browser’s own performance observers, whose thresholds are declared in the HUD’s sampler rather than restated here; the latency row is that one interaction, not a percentile. A row with nothing observed yet reads measuring, and one this browser cannot report reads a dash.

Why there is no test suite: The repository has no test runner. Instead, the diagram layout is exhaustively typed against the machine states, and the machine, state-id set, and path invariants are checked during static prerendering. A broken branch topology fails pnpm build.