Enumerate user-visible states
Designs default to the happy path and ship the rest by accident. This skill enumerates every state a user can actually observe, so none is improvised in production.
Procedure
Name the entity and the screen in states.md, e.g. orders list.
List the states from the data's point of view: loading (request in flight), empty (zero results, not an error), partial (some pages loaded), populated, stale (cached while revalidating), error (request failed), offline (no network), permission-denied, and disabled (feature gated).
For zero results, separate no data yet from no data matches your filter; they need different copy and a different call to action.
For each state specify the visible text, the primary action, and what the user can do next. A state with no next action is a dead end (see audit-a-flow-for-dead-ends).
Mark which states can appear simultaneously, e.g. stale plus partial; test the combinations users actually hit, not every permutation.
Note the transition that leaves the state and its trigger: retry, refresh, next page, back.
Check each message against the rules in write-actionable-error-copy.
Confirm no state can persist indefinitely: every loading and stale needs a timeout and a fallback.
Add the zero-width and very-long-content cases: an empty string, a 5000-character name, an emoji in a title.
Note the slow-network state separately from offline; a request that takes 30 seconds is its own experience.
Give the error state its own error code visible to support, so a screenshot identifies the failure precisely.
Pitfalls
Treating an empty list as an error; users see a red banner where a friendly nudge belongs.
A loading state with no timeout, so a hung request spins forever.
Copy that says "something went wrong" with no path forward.
Forgetting permission-denied, so the screen renders as empty and looks like lost data.
Designing from the API's shape rather than the user's; a 200 with an empty array is still empty.
Specifying the loading skeleton but never the failure state it resolves to.
Forgetting the state after a successful action, such as the post-submit confirmation.
Naming states after components rather than after what the user perceives.
Verification
grep -cEi '^state:|loading|empty|partial|error|offline|denied' states.md
Report the state list and any state with no defined next action or no exit transition.
1---2name: enumerate-user-visible-states3description: Use when specifying a screen, component, or flow. Lists every state a user can see — loading, empty, partial, error, offline — before the happy path is built.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/enumerate-user-visible-states6---78# Enumerate user-visible states910Designs default to the happy path and ship the rest by accident. This skill enumerates every state a user can actually observe, so none is improvised in production.1112## Procedure13141. Name the entity and the screen in `states.md`, e.g. `orders list`.152. List the states from the data's point of view: `loading` (request in flight), `empty` (zero results, not an error), `partial` (some pages loaded), `populated`, `stale` (cached while revalidating), `error` (request failed), `offline` (no network), `permission-denied`, and `disabled` (feature gated).163. For zero results, separate `no data yet` from `no data matches your filter`; they need different copy and a different call to action.174. For each state specify the visible text, the primary action, and what the user can do next. A state with no next action is a dead end (see `audit-a-flow-for-dead-ends`).185. Mark which states can appear simultaneously, e.g. `stale` plus `partial`; test the combinations users actually hit, not every permutation.196. Note the transition that leaves the state and its trigger: retry, refresh, next page, back.207. Check each message against the rules in `write-actionable-error-copy`.218. Confirm no state can persist indefinitely: every `loading` and `stale` needs a timeout and a fallback.229. Add the zero-width and very-long-content cases: an empty string, a 5000-character name, an emoji in a title.2310. Note the slow-network state separately from offline; a request that takes 30 seconds is its own experience.242511. Give the error state its own error code visible to support, so a screenshot identifies the failure precisely.2627## Pitfalls2829- Treating an empty list as an error; users see a red banner where a friendly nudge belongs.30- A `loading` state with no timeout, so a hung request spins forever.31- Copy that says "something went wrong" with no path forward.32- Forgetting `permission-denied`, so the screen renders as `empty` and looks like lost data.33- Designing from the API's shape rather than the user's; a 200 with an empty array is still `empty`.34- Specifying the loading skeleton but never the failure state it resolves to.35- Forgetting the state after a successful action, such as the post-submit confirmation.3637- Naming states after components rather than after what the user perceives.3839## Verification4041 grep -cEi '^state:|loading|empty|partial|error|offline|denied' states.md4243Report the state list and any state with no defined next action or no exit transition.