The Law
AN AI FEATURE WITHOUT DESIGNED STATES IS HALF A FEATURE.
"We'll add error states later" means users see broken UI in production.
"The happy path looks great" is not a UI design — it is a demo.
All 7 states designed, documented, and approved IS a complete AI feature design.
The 7 Required States
Every AI feature touchpoint must have a designed state for each:
| State | When It Appears | What Users Need |
|---|---|---|
| Loading | Request sent, waiting for first token | Progress signal, estimated wait, cancel option |
| Streaming | Tokens arriving, response building | Readable partial content, clear "generating" signal |
| Success | Generation complete, full response available | Result, confidence signal, actions (copy, retry, share) |
| Error | API failure, timeout, server error | Human error message, recovery action, no raw stack trace |
| Partial | Model answered but incompletely | Clear indication of incompleteness, option to continue |
| Uncertain | Low confidence, hedged response | Uncertainty signal, source citation, human review option |
| Empty | No input yet / no history / first run | Guidance, examples, prompt suggestions — not a blank void |
When to Use
Trigger before:
- Any PR that adds a new AI-powered UI feature
- Any PR that adds a new model call with user-visible output
- Designing a new agent interface or chat UI
- Adding AI capabilities to an existing feature
When NOT to Use
- Background AI jobs with no user-facing output (batch processing, background classification)
- Developer-only tooling where no end user sees the output
The Process
Step 1 — List Every AI Touchpoint
Map every place the user will see model output in this feature:
- Main response area
- Any inline predictions (autocomplete, suggestions)
- Status indicators (sidebar, header badges)
- Any secondary outputs (citations, related items, follow-up questions)
Each touchpoint needs its own 7-state design.
Step 2 — Design Each State
For each state, define:
- Visual treatment — skeleton / spinner / streaming cursor / error icon / empty illustration
- Copy — what the UI says in this state (not placeholder text, actual final copy)
- Actions — what the user can do from this state
- Transition — how it moves to the next state
State: Error
Visual: Red border on output area, error icon (⚠), inline message
Copy: "Something went wrong generating your response. Try again or refresh."
Actions: [Try again] [Dismiss]
Transition: Retry → Loading state; Dismiss → Empty state
Step 3 — Document in a State Map
Create design/ai-states/<feature-name>.md with the state map:
## Feature: <name>
### Touchpoint: <main output area>
| State | Visual | Copy | Actions | Transition |
|---|---|---|---|---|
| Loading | Skeleton (3 lines) | "Generating..." | [Cancel] | Cancel → Empty; First token → Streaming |
| Streaming | Streaming cursor, partial text | Live text | [Stop] | Complete → Success; Error → Error |
| Success | Full response | — | [Copy] [Retry] [👍 👎] | Retry → Loading |
| Error | Red border, inline message | "Something went wrong. Try again." | [Try again] | → Loading |
| Partial | Dashed border, "▾ Response cut off" | "Response was cut off. Continue?" | [Continue] [Accept] | Continue → Loading |
| Uncertain | Amber border, ⚠ badge | "Low confidence — verify this." | [Show sources] | — |
| Empty | Prompt suggestions, example queries | "Ask anything about X…" | [Example 1] [Example 2] | User types → Loading |
Step 4 — Review the Edge Cases
Before sign-off, verify each of these works:
- What if the stream is interrupted mid-word?
- What if the error message from the API is user-readable vs. a raw 500?
- What if the model returns an empty string?
- What if the response is extremely long (>2000 words)?
- What if the user submits again before the first response finishes?
Rationalization Red Flags
These thoughts mean states were not designed — stop:
- "We'll add error states in a follow-up" — follow-up PRs for error states ship 3 weeks late, after the first 3am incident
- "The happy path is what matters for the demo" — users encounter every state; you only rehearsed one
- "Just show a spinner" — a spinner with no copy, no cancel, and no timeout handling is not a loading state
- "The streaming state is just the loading state with text" — streaming and loading have different affordances; conflating them produces UI that feels broken
- "Empty state can be a blank screen with a text input" — blank screens communicate nothing; empty states are onboarding moments
Completion Statement Format
When ai-states-required is satisfied, state it like this:
AI states designed.
Feature: <name>
Touchpoints covered: <N>
State map: design/ai-states/<feature>.md ✓
All 7 states documented for each touchpoint (must match state map file — no vague descriptions):
Loading: <named element: skeleton/spinner/pulse + exact copy text> ✓
Streaming: <cursor type + exact copy text> ✓
Success: <actions listed: Copy / Retry / 👍 👎 + copy text if any> ✓
Error: <border colour + icon + exact error copy + recovery action label> ✓
Partial: <dashed/truncated indicator + exact copy + continuation action label> ✓
Uncertain: <amber bar / ⚠ badge + exact verify copy + next-action label> ✓
Empty: <illustration type + exact heading copy + N example prompts listed> ✓
Edge cases reviewed: stream interruption, empty response, duplicate submit ✓
Why This Matters
AI features fail visually in ways deterministic software does not. A form either submits or fails. An LLM call can stream, stall, truncate, hallucinate, refuse, or produce an empty response — and users see all of these. Designing only the success state means every other state ships as broken UI.