Practical decision guide
5 min read
Updated
Loading, empty or broken: show the right next step
Distinguish waiting, first-use emptiness, no matching results and a failed service.
Direct answer
Treat loading, an empty account, filtered emptiness and failure as different states. Preserve context and offer an action that can actually help. A skeleton describes waiting, not proof that data exists. Retry should retain the query and filters rather than silently resetting the task.
01
Map response states
For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence.
Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case.
- loading empty and error states
- my list will not load
For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence. Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case.
02
Choose waiting feedback
Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate.
Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame.
Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate. Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame.
03
Example: three empty lists
A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query.
Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request.
A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query. Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request.
04
Reject stale responses
When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned.
Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops.
When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned. Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops.
05
Verify each next action
Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination.
Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct.
Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination. Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct.
Keep this
Verify in your product
- 01Loading is not emptiness.
- 02Initial and filtered emptiness differ.
- 03Failure retains input.
- 04Retry has a bounded effect.
- 05Late data cannot overwrite current data.
- 06Status survives motion removal.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Understanding status messages (opens in a new tab)W3C WAI · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
- AbortController (opens in a new tab)MDN · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Loading, empty or broken: show the right next step” step by step
# Apply the “Loading, empty or broken: show the right next step” guide in your agent ## Objective Treat loading, an empty account, filtered emptiness and failure as different states. Preserve context and offer an action that can actually help. A skeleton describes waiting, not proof that data exists. Retry should retain the query and filters rather than silently resetting the task. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Distinguish waiting, first-use emptiness, no matching results and a failed service. - Preserve the correct decisions already in place. ## Guide steps - 1. Map response states — For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence. Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case. - 2. Choose waiting feedback — Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate. Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame. - 3. Example: three empty lists — A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query. Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request. - 4. Reject stale responses — When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned. Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops. - 5. Verify each next action — Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination. Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct. ## Acceptance criteria — Verify in your product - Loading is not emptiness. - Initial and filtered emptiness differ. - Failure retains input. - Retry has a bounded effect. - Late data cannot overwrite current data. - Status survives motion removal. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:ddf58ba759c28f48e931550526c366b753a404faef7f9cc65c572506bfa32ee7
Diagnose a problem
Diagnose a “Loading, empty or broken: show the right next step” guide gap
# Diagnose a failed application of the “Loading, empty or broken: show the right next step” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. Map response states — For a project list, name not requested, loading, populated, empty and failed states. Add refreshing with old data if necessary. Associate each state with actual response evidence. Do not convert every failure into an empty array. No projects is a valid result; a failed request leaves the contents unknown. Permission denial is another distinct case. - 2. Choose waiting feedback — Use a loading label for unknown duration. A skeleton reserves a known shape; a percentage needs measurable work and a total. Do not simulate a fake completion rate. Keep independent controls usable. Label old results during refresh so they are not mistaken for new results. Avoid repeating announcements on every animation frame. - 3. Example: three empty lists — A new workspace offers Create a project. A filter with no matches shows active criteria and Clear filters. A network failure offers Try again while retaining the query. Do not offer all three actions indiscriminately. If creation is forbidden, explain the access boundary and the available contact route without pretending to submit an automatic request. - 4. Reject stale responses — When a new query replaces the first, cancel or ignore the older result. Its late success must not overwrite the current query’s failure or matches. Keep query and displayed data aligned. Browser cancellation does not undo server work. For read-only lists it prevents obsolete rendering; writes need a separate recovery contract. Avoid unbounded automatic retry loops. - 5. Verify each next action — Exercise one response per state and two responses out of order. Verify each action changes the right condition. If a focused retry control disappears, provide a sensible focus destination. Keep status understandable without motion and at 320 px. DOM roles alone do not prove actual screen-reader announcements; keep that qualification distinct. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Verify in your product - Loading is not emptiness. - Initial and filtered emptiness differ. - Failure retains input. - Retry has a bounded effect. - Late data cannot overwrite current data. - Status survives motion removal. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:63d0abf5036c40a567697074573c1d51998324d4a1d3693f23a9849feb2a9d87
Pack digest: sha256:f4fb46d07b33a2a646d38dcfb597ddb9610c97914ac067da25bf0e9cc589d57c