/status-colors-and-errors

name: status-colors-and-errors
description: Few semantic colours, each meaning one thing, and errors with a way forward. Use when designing status indicators, validation, alerts or error states.
metadata:
  priority: 8
  pathPatterns:
    - "**/*.css"
    - "**/*.scss"
    - "**/tokens/**"
    - "**/theme/**"
    - "tailwind.config.*"
    - "design-system/**"
    - "components/**"
    - "**/*.tsx"
    - "**/*.jsx"
  promptSignals:
    phrases:
      - "error"
      - "warning"
      - "success"
      - "alert"
      - "status"
      - "validation"
      - "feedback"
      - "toast"
      - "notification"
retrieval:
  aliases:
    - error states
    - status colours
    - semantic colours
    - alerts
    - form validation
    - error recovery
    - feedback system
  intents:
    - design error states
    - set up semantic colours
    - handle errors gracefully
    - show validation feedback
    - communicate status to users
  examples:
    - what colours should I use for errors and warnings
    - how should I handle a failed API call
    - design the error state for this form

Status Colours and Error Design

Keep the Colour Set Small

Every status colour added to a system is a cognitive burden on the user. They must learn what each colour means, remember it, and interpret it correctly under stress — which is exactly when errors occur.

**The minimal set that covers almost everything:**

| Colour | Semantic meaning | Always means | |---|---|---| | **Red** | Error / failure / destructive | Something went wrong, or this action cannot be undone | | **Orange / Amber** | Warning | Something needs attention before proceeding | | **Green** | Success / positive | Action completed, state is healthy | | **Blue** | Info / neutral status | Informational, no action required |

**Rule: each colour maps to exactly one meaning across the entire product.** If orange means "warning" in one component and "pending" in another, the system breaks down.

**Every status tone must be visibly distinct from the others.** If two tokens render alike, keep one. A second name for the same visible colour is not a second status: authors pick either, users read one state, and the name becomes a lie. Draft and pending states take neutral, not the warning tone.

When in doubt, cut the colour — neutral grey communicates status without semantic weight, and neutral is better than a misused semantic colour.

Orange Is Always a Warning

Orange (amber) carries a specific signal: pay attention, something may go wrong. Do not use it for:

• Neutral states (use grey)
• Progress or pending (use blue or a spinner)
• Informational content (use blue)
• Branding or decorative purposes inside status indicators

If orange appears in the UI, the user should immediately know it requires their attention.

Errors Should Be Recoverable

**The worst error is one the user cannot recover from.** Design every error state with a path forward.

Error message anatomy

Every error should answer three questions: 1. **What went wrong?** — plain language, no error codes 2. **Why did it happen?** — if useful and known 3. **What should the user do next?** — specific, actionable

❌ "Error 500"
❌ "Something went wrong"
✓  "We couldn't save your changes. Check your connection and try again."
✓  "This email is already in use. Sign in instead, or use a different email."

Recovery actions

• Always provide a retry button for transient failures (network errors, timeouts)
• For validation errors, point directly to the problematic field
• For destructive actions that failed, reassure the user nothing was lost
• For session expiry, redirect to login and return the user to where they were

Prevent Large Errors Before They Happen

The most damaging errors — data loss, irreversible actions, broken state — should be prevented at the design level, not handled after the fact.

• **Confirm before irreversible actions:** "Delete this project and all 47 tasks? This cannot be undone."
• **Disable unavailable actions** rather than letting users trigger them and hit an error
• **Autosave** where possible so a browser crash or accidental close does not destroy work
• **Optimistic UI** with rollback: show the success state immediately, silently retry on failure, surface an error only if the retry also fails

**State the consequences *before* the user acts, not after.** Fear comes from not knowing what a control will do. Make the outcome legible ahead of the action so the user commits with confidence:

• **Plain-language consequence text** next to or inside the control: "This will email all 240 subscribers", "Publishing makes this visible to everyone".
• **Staged guidance** for anything multi-step or heavy: break it into steps and tell the user what each one will do before they proceed, so the whole operation is predictable rather than a leap.
• Reserve the strong interruptions (confirm dialogs, typed confirmation) for the genuinely dangerous cases above; for everyday actions, a quiet line of helper text is enough. The goal is the same — no surprises, so nothing feels scary.

Levels of Severity — Use Sparingly

Not every problem is equal. Match the visual weight of the feedback to the severity.

| Severity | Pattern | When to use | |---|---|---| | **Blocking error** | Full-page error state or modal | App cannot continue, user must act | | **Inline error** | Red text below a field | Form field validation failure | | **Toast / snackbar** | Temporary notification, bottom of screen | Transient failure the user should know about but can dismiss | | **Alert banner** | Persistent bar at top of section | Ongoing issue affecting the current context | | **Empty state** | Illustrated or descriptive empty screen | No data yet — use as an opportunity for guidance, not just a blank |

Avoid showing multiple simultaneous error types at once — one clear message is more useful than three overlapping alerts.

Degree of Likeness Is One Hue, Never Red to Green