Model UI state before adding features

The decision

Before wiring a feature to a backend, describe the screens a person can reach and the events that connect them. A single state value is often clearer than several booleans that can contradict each other. For example, “loading” and “failed” should not both be true for the same submission.

A worked example

A file import moves through idle, validating, uploading, processing, ready, or failed. Validation failures return to editing with the file still selected. An upload failure permits retry. A processing job can survive a refresh because its identifier is stored on the server. The ready state includes the result ID rather than merely displaying a green check mark.

How to put it into practice

1. Name states in the language of the operation, and list what actions are possible in each.
2. Represent success with the data needed for the next step, not just a boolean.
3. Keep errors close to the control that caused them and use a live region for status changes.
4. Define cancellation behavior. Stopping a browser request does not necessarily cancel a server job.

type ImportState =
  | { status: "idle" }
  | { status: "processing"; jobId: string }
  | { status: "ready"; resultId: string }
  | { status: "failed"; message: string };

A failure to plan for

Try it on your project

Draw a small transition table for an import. Try to reach “ready” without a result ID and “processing” without a job ID. If your types allow those combinations, tighten the state model before adding more controls.