Error and success messages
Messages are how the system talks to people. They should be clear, specific, and kind. The goal is always to help someone move forward, not to make them feel like they've done something wrong.
Error messages
The structure
Every error message should include 3 things:
- What happened. Describe the problem in plain language.
- Why it happened. If it's useful and you know the cause, share it.
- What to do next. Give them a clear action.
| Do | Don't |
|---|---|
| We couldn't save your changes. Check your connection and try again. | Error 500 |
| Enter an email address, like name@example.com | Invalid input |
| This password needs at least 8 characters | Password requirements not met |
| That email is already registered. Try signing in instead. | Duplicate entry |
Core rules
- Blame the system, not the person. "We couldn't find that page" not "You entered an invalid URL." The system failed, not the user.
- Be specific. "Enter a date after today" is useful. "Invalid date" is not.
- Tell them what to do. Every error should include a next step or a way forward.
- Don't use error codes alone. "Error 404" means nothing to most people. If you include a code, pair it with a human explanation.
- Don't use technical language. "Request timed out" is fine for logs. For people, say "This is taking longer than expected. Try again in a few minutes."
- Don't use the word "please" in every error. One "please" per interaction is fine. More than that starts to feel like the system is grovelling.
Tone by severity
The tone should match the situation. A missing field is different from a deleted account.
| Severity | Tone | Example |
|---|---|---|
| Validation error | Helpful, specific | Enter a date in DD/MM/YYYY format |
| Connectivity issue | Reassuring | You seem to be offline. We'll save your changes and sync when you're back. |
| System error | Honest, calm | Something went wrong on our end. We're looking into it. |
| Destructive confirmation | Clear, direct | This will permanently delete 12 files. You can't undo this. |
| Permission error | Explanatory | You don't have access to this page. Contact your team admin to request access. |
| Rate limiting | Matter-of-fact | You've made too many requests. Wait a few minutes and try again. |
Success messages
Success messages confirm that something worked. Keep them brief and specific about what happened. Don't over-celebrate.
| Do | Don't |
|---|---|
| Changes saved | Congratulations! Your changes have been successfully saved! |
| Message sent to 3 people | Success! |
| Account created. Check your email to verify. | You did it! Welcome aboard! |
| Project deleted | Your project has been successfully and permanently deleted from our systems |
| Password updated | Great news! Your password has been changed! |
Success message rules
- Say what happened, not just "Success"
- Include relevant details. "Message sent to 3 people" is better than "Message sent."
- If there's a next step, mention it. "Account created. Check your email to verify."
- Don't use exclamation marks to manufacture excitement
- Keep them short. One sentence is usually enough.
- Make them dismissible. Success messages shouldn't block the interface.
Loading and progress states
What to show while the system is working depends on how long the wait is.
| Duration | Pattern | Example |
|---|---|---|
| Brief (under 3 seconds) | Spinner or skeleton, no text | (none) |
| Moderate (3 to 10 seconds) | Spinner with context | Loading your projects... |
| Long (over 10 seconds) | Progress indicator with details | Uploading 3 of 12 files... |
| Background process | Toast or notification | Your report is generating. We'll email you when it's ready. |
Loading text rules
- Describe what's happening, not just "Loading..."
- Use present continuous. "Saving your changes..." not "Save in progress."
- End with an ellipsis (3 dots) to indicate ongoing activity
- If it might fail, prepare them. "This might take a minute. We'll let you know if something goes wrong."
- For background processes, set expectations. "This usually takes 2 to 5 minutes."
Empty states
Empty states appear when there's nothing to show. They're an opportunity to guide people, not a dead end.
| Context | Example |
|---|---|
| First-time empty | No projects yet. Create your first one to get started. |
| Search with no results | No results for "xyz." Try a different search term or check your spelling. |
| Filtered with no results | No items match your filters. Clear filters to see everything. |
| Empty after deletion | All items removed. You can add new ones anytime. |
| Feature not set up | Analytics aren't set up yet. Connect your data source to start tracking. |
Empty state rules
- Don't just say "no data." Explain what would normally be here and how to get started.
- Include a call to action when there's something the user can do about it
- Keep the tone warm. "Nothing here yet. That's fine. Every good system starts empty."
- Don't make people feel like they've done something wrong for having an empty state
- Use the space well. A good empty state can teach people how the feature works.
Confirmation dialogs
When someone is about to do something irreversible, confirm it. But do it well.
| Do | Don't |
|---|---|
| Delete this project? This will permanently remove "Marketing site" and all its files. You can't undo this. | Are you sure? |
| Leave without saving? You have unsaved changes that will be lost. | Warning! |
| Remove Alex from this team? They'll lose access to all team projects. | Confirm action |
Confirmation dialog rules
- Name the specific thing being affected. "Delete Marketing site" not "Delete this item."
- Describe the consequences. Explain what will happen if they proceed.
- Make the buttons specific. "Delete project" and "Keep project," not "OK" and "Cancel."
- Don't ask "Are you sure?" on its own. It gives no information about what's about to happen.
Accessibility requirements
Messages aren't just visual. They need to work for everyone.
- Error identification (WCAG SC 3.3.1): Errors must be described in text, not just indicated by colour or an icon. A red border alone isn't enough.
- Error suggestion (WCAG SC 3.3.3): If you can detect the error, suggest a correction. "Did you mean name@gmail.com?" is better than "Invalid email."
- Status messages (WCAG SC 4.1.3): Success messages, loading states, and non-interactive updates must be announced to screen readers. Use
role="status"oraria-live="polite"for non-urgent updates. Userole="alert"oraria-live="assertive"for errors. - Don't rely on colour alone. Pair colour with icons, text labels, or patterns so the message is clear to everyone.
- Don't auto-dismiss error messages. People need time to read and act on them. Success messages can auto-dismiss after a reasonable delay (5 to 8 seconds).
For the full accessibility specification, see accessibility standards.