Help us improve
Share bugs, ideas, or general feedback.
From builder-design
Use before writing any code for an AI feature's UI. All 7 states must be designed and documented before implementation begins. Blocks "we'll add loading states later" completions.
npx claudepluginhub rbraga01/a-team --plugin builder-designHow this skill is triggered — by the user, by Claude, or both
Slash command
/builder-design:ai-states-requiredThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
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.
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 |
Trigger before:
Map every place the user will see model output in this feature:
Each touchpoint needs its own 7-state design.
For each state, define:
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
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 |
Before sign-off, verify each of these works:
These thoughts mean states were not designed — stop:
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 ✓
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.