ux-error-handling
Skill21 starsChanged 5 months agoMITView on GitHub
Error handling UX: destructive action confirmation, undo, empty states, descriptive error messages, crash recovery, and server error handling. This is also the canonical home for empty-state standards. Use when designing or reviewing error states, confirmation dialogs, undo flows, or any screen that needs to handle failure.
In this repository17 other files it gives its agents.
- ux-accessibilitySkill
- ux-ai-automationSkill
- ux-contentSkill
- ux-formsSkill
- ux-generalSkill
- ux-help-onboardingSkill
- ux-information-architectureSkill
- ux-navigationSkill
- ux-networkSkill
- ux-notificationsSkill
- ux-reviewSkill
- ux-safety-privacySkill
- ux-searchSkill
- ux-settingsSkill
- ux-user-accountSkill
- ux-utilitySkill
- ux-visual-designSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Every error is a broken promise.
- Distinctive: line 68
Every empty state has four parts:
- Distinctive: line 84
Never leave a dead end: every empty state offers a next step or a path back.
- Distinctive: line 95
Never use "OK" or "Yes" as the label on a destructive confirm button.
- Distinctive: line 96
Never reverse the button positions.
- Distinctive: line 113
When applying this checklist to a screen, flow, or codebase:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Error Handling UX
Every error is a broken promise. How you handle it determines whether the user forgives you or leaves. Good error handling is preventive, informative, and always leaves a path forward.
Checklist
| Item | Guidance |
| Destructive action confirmation | Single dialog. Action button is styled red. Cancel appears on the left. |
| Undo action | Snackbar with an "Undo" button for 5 to 7 seconds after deletions and moves. |
| Empty state screens | Every empty screen follows the empty-state standards below. |
| Reduce human error | Inputs are constrained, defaults are smart, and validation catches mistakes early. |
| Descriptive error messages | States what failed, why if relevant, and what the user can do next. |
| Crash recovery | App restores the previous state on relaunch after a crash. |
| Server error handling | 5xx and timeout errors show a human-readable message and a Retry button. |
Error Message Formula
[What happened] + [Why, if it helps] + [What to do next]Examples that work:
- "We couldn't save your post. Check your connection and tap Save again."
- "Your session expired. Sign in to continue."
- "This username is already taken. Try adding numbers or a different word."
- "Payment declined. Your card ending in 4242 was not charged. [Try another card]"
Error Types and UI Patterns
| Error type | Pattern |
| Validation | Inline, below the field. Shown when focus leaves the field. |
| Recoverable server error | Toast or inline message with a Retry button |
| Blocking server error | Full-screen error page with Retry and Contact Support options |
| Auth error | Redirect to login. Preserve the user's intended destination. |
| Permission denied | Explain the issue and link to Settings to resolve it. |
| Network error | Top banner with offline mode fallback |
| Empty state | Positive framing with an invitation to act |
| Content not found (404) | Friendly message with suggestions and a path to Home |
| Crash | Offer to report the crash and restore the previous state |
Empty State Standards
This is the canonical empty-state guidance for the whole skill set — other
skills (ux-search, ux-visual-design, ux-help-onboarding) reference it.
Every empty state has four parts:
- Visual — an illustration or icon that matches the app's style.
- Heading — short, positive, and specific ("No saved articles yet").
- Message — one line explaining what this space is for.
- Action — an optional primary button inviting the first step ("Browse articles").
Variants and what changes:
| Variant | Framing |
| First use | Invite the first action: "Add your first task" — never a bare empty list |
| No search results | Pair "No results for X" with a spelling suggestion and related categories |
| Error-caused empty | Explain the failure and offer Retry — do not disguise an error as an empty state |
| Cleared / completed | Celebrate: "All caught up" with a positive visual |
Never leave a dead end: every empty state offers a next step or a path back.
Confirmation Dialog Standards
Title should state the action and what it affects: "Delete conversation?" Body should state the consequence: "This will permanently remove 48 messages." The confirm button label should match the title verb: "Delete" in red. Cancel should appear on the left, confirm on the right.
Never use "OK" or "Yes" as the label on a destructive confirm button. Never reverse the button positions.
Undo vs Confirm
| Use undo when | Use a confirm dialog when |
| The action can be reversed | The action is permanent or irreversible |
| The cost of a mistake is low | The cost of a mistake is high |
| Speed is important | The user should slow down and think |
| Example: archive a message | Example: delete an account |
How to Review
When applying this checklist to a screen, flow, or codebase:
- Go through every checklist item and mark it Pass, Fail, or N/A — never skip items silently.
- Cite specific evidence for each finding: the screen, component, file, or line it applies to.
- Tag each failure with a severity: Blocker (breaks the experience), Major (hurts usability), or Minor (polish).
- End the review with the top 3 recommended fixes, ranked by user impact.
Related Skills
ux-content— error message tone and microcopy patternsux-network— connectivity-specific error statesux-forms— inline validation and error recovery in forms
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.