Error State Design Review

---
name: Error State Design Review
description: Inventory, classify, and unify every error state in a product into one pattern doc with copy rules and a checklist.
when_to_use: A team wants consistency across toasts, empty states, validation errors, 404s, 500s, and permission denials.
---

# Error State Design Review

## What this skill does
Walks a product's error states through three phases — inventory, classification, unification — and produces a pattern document per error type plus a checklist for future errors. Not a single template; a small set of type-specific patterns that share a grammar.

## When to load this skill
Load when the user says: "our error states are inconsistent", "review every error in our product", "we need an error pattern", "unify our empty states", "the 500 page looks different from the 404", or describes multiple errors and asks how to make them feel like one product.

## The procedure

### Step 1 — Inventory every error state
Ask the user to list every place in the product where something can go wrong or come back empty. Prompt for: form validation errors, submit failures, upload failures, permission denials, not-found (404), server error (500), offline, timeout, rate-limit, empty states (zero search results, zero items, zero messages), and any modals or toasts triggered by failures. If the user misses a category, name it and ask if it exists. The inventory is the foundation — a review that misses half the errors produces a pattern that breaks on the other half.

### Step 2 — Classify into four types
Classify each inventoried error into one of four types. The types have different jobs:

- **Validation error** — the user did something wrong and needs to fix it. Job: tell them what and how, inline, near the thing they're fixing. Should never be modal; should never be a toast.
- **System error** — something broke on our side (server, network, dependency). Job: be honest, apologize briefly, give an alternative path (retry, refresh, contact support).
- **Empty state** — nothing is wrong; there just isn't anything here yet. Job: explain why it's empty and give the user a next action to change that. Never just an illustration.
- **Permission / access error** — the user can't do this because of rights, plan, or auth. Job: say what's needed, offer the path to get it, don't scold.

Each inventoried error gets exactly one type. If it seems to fit two, it's probably written confusingly — rewrite it to fit one. A "you can't afford this feature" error is a permission error, not a validation error. A "you're offline" error is a system error, not a validation error.

### Step 3 — Extract the underlying grammar
For each type, write the grammar: the structural elements every error of that type must have. Across all four types, the universal grammar is: **state the situation plainly, name the cause if known, give the user something to do next.** Per type:

- Validation: what's wrong (specific), why (rule), how to fix. No apology; no emoji; no "oops".
- System: brief apology, honest cause if you can share it, retry or alternative. Tone: calm, not chirpy. A system error is not a fun moment.
- Empty: why empty, what fills it, a button or link to do that.
- Permission: what's blocked, what's needed, how to get it. No lecturing.

Any error state that fails its type's grammar gets rewritten.

### Step 4 — Propose a visual pattern per type
Each type gets one visual pattern. Validation errors: inline, red text below the field, icon-optional, never a toast. System errors: a banner or modal depending on scope; banner for component-level, modal for page-level. Empty states: a centered block with a line of body copy, optional illustration, and a primary action button. Permission errors: a small card explaining what's needed with a clear action. Within a product, every validation error looks the same; every empty state looks the same; and so on.

Document which token (from the design system) each type uses: color-status-danger for validation, color-status-warning for system, color-text-muted + color-action-primary for empty, and so on. If the system doesn't have these tokens, flag it.

### Step 5 — Write example copy for each type
For each type, write three example strings — a good one, a bad one, and one rewritten from the user's inventory. This gives the team a pattern they can match. Examples should be product-specific if possible. Use the product's voice from microcopy review if that skill has run.

### Step 6 — Produce the pattern doc and the checklist
Output:
1. **The inventory** with each error's classification.
2. **The four patterns** — visual, copy, tokens.
3. **Example copy** per type.
4. **A checklist** the team can apply to any new error state: Which type is this? Does it meet the type's grammar? Does it use the type's visual pattern? Does the copy answer what/why/how-to-proceed? Is it announced to assistive tech?
5. **A revision list** — every existing error in the inventory that doesn't meet the pattern, with a proposed fix.

Hand off to [Microcopy Review](/agents/skill-content-design-microcopy-review) for the copy rewrites, and [Form Accessibility Audit](/agents/skill-form-accessibility-audit) for validation-error accessibility.

## A worked example

**User:** We have about a dozen error states across the product. They're all different.

**Claude:** List them.

**User:**
- Form field error: "Invalid." (red text below field)
- Login failed: "Something went wrong. Please try again." (toast)
- 404: "Page not found." (page, centered, big)
- 500: "500 Internal Server Error" (page, top-left, monospace)
- Empty inbox: illustration of an envelope, no text
- Empty search: "No results."
- Can't access feature (free tier): modal, "Upgrade to Pro!" with confetti emoji
- Upload failed: toast, "Upload failed."
- Offline: banner, "You are offline."
- Delete confirmation error: "Cannot delete. Check your connection and try again."

**Claude:** Running classification.

**Validation errors (1):**
- Form field "Invalid." — type: validation. Fails grammar: doesn't say what or how to fix.

**System errors (5):**
- Login failed "Something went wrong" — fails: vague, no cause, no alternative.
- 500 "Internal Server Error" — fails: tone (monospace server lingo is not user-facing), no alternative.
- Upload failed "Upload failed" — fails: no cause, no retry CTA, no next step.
- Offline banner "You are offline" — passes minimal grammar. Could add "Your changes will sync when you reconnect" for reassurance.
- Delete confirmation error — passes partially. Says cause (connection), gives next step (try again). Could be warmer.

**Empty states (2):**
- Empty inbox (illustration only) — fails: no text at all. Users with screen readers get nothing.
- Empty search "No results" — fails: no next step. Rewrite: "No matches for 'josephine'. Try a different spelling or browse all contacts."

**Permission errors (1):**
- Upgrade modal with confetti — fails: tone (celebratory for a blocked action is gaslighting), no clear explanation of what's blocked, no "maybe later" path.

**Not classified yet — where's your 403 (auth)?** If users can hit pages they don't have permission for (shared links, direct URLs), you probably need a permission error for that too.

**Patterns:**

*Validation error pattern:*
- **Visual:** inline, below field, `color-status-danger`, 14px, paired with `aria-describedby` and `aria-invalid`.
- **Copy:** "What's wrong. How to fix." Max two sentences. No apology, no emoji.
- **Good:** "This date is in the past. Enter a future date."
- **Bad:** "Invalid." / "Oops!"
- **Your rewrite:** Replace "Invalid." with field-specific messages. For an email field: "Use the format name@example.com." For a date: "Use MM/DD/YYYY (example: 04/13/2026)."

*System error pattern:*
- **Visual:** banner if component-level, modal or full page if page-level. `color-status-warning` for transient, `color-status-danger` for persistent. Includes an action button (retry, refresh, contact).
- **Copy:** brief apology + plain cause + alternative. Tone calm, not chirpy, not monospace.
- **Good:** "We couldn't sign you in. Check your password, or reset it if you've forgotten."
- **Bad:** "500 Internal Server Error"
- **Your rewrite of the 500 page:** "Something on our end went wrong. We've been notified. You can [refresh the page] or [go back to home]."

*Empty state pattern:*
- **Visual:** centered block, optional illustration (always with alt text), one-line body copy, one primary action.
- **Copy:** why empty + what fills it + next action.
- **Good:** "No messages yet. When someone writes to you, it'll show up here. [Compose a message]"
- **Bad:** illustration with no text
- **Your rewrite of empty inbox:** add "No messages yet. Your conversations will appear here." with a "Start a conversation" button. Illustration alt: "Empty inbox".

*Permission error pattern:*
- **Visual:** small card or modal, `color-text-muted` for explanation, `color-action-primary` for the action.
- **Copy:** what's blocked + what's needed + action. Calm, matter-of-fact. No confetti, no "Unlock"/"Upgrade!" exclamation, no lecture.
- **Good:** "This feature is part of our Pro plan. [See plans] or [Keep using the free plan]."
- **Bad:** "Upgrade to Pro! 🎉 Unlock premium features now!"
- **Your rewrite:** swap the confetti modal for the calm version. The "Keep using the free plan" option matters — it says "we're not holding your product hostage".

**The checklist (laminate it if you want):**
1. Which type? (validation / system / empty / permission)
2. Does the copy answer: what, why, what to do next?
3. Does the visual match the type's pattern and use the right tokens?
4. Is it announced to assistive tech (live region, aria-invalid, role=alert)?
5. Is the tone appropriate for the moment? (never chirpy for system errors; never apologetic for empty states)
6. Is there a path forward?

**Revision list (priority order):**
1. Form field "Invalid" — rewrite all validation errors to be specific.
2. Empty inbox illustration — add text, screen-reader-reachable.
3. 500 page — rewrite with calm copy and action.
4. Upgrade modal — remove confetti, add "keep using free" path.
5. Login failed toast — specific cause, reset link.
6. Upload failed — add retry CTA, show the filename.

## What this skill will NOT do
- Will NOT impose a single template on all error types. Different jobs get different patterns.
- Will NOT accept "Oops!", "Something went wrong", or confetti on errors users didn't celebrate causing.
- Will NOT skip accessibility. Every error gets an assistive-tech check.
- Will NOT write marketing error pages (brand 404s, "we're cool about it" moments). Those belong to marketing, not the product system.
- Will NOT classify an error into two types. Ambiguous errors get rewritten until one type fits.