Returnless UI

Error messages ​

Error messages can be scary. Make errors visible to users, easy to understand, and helpful.

Error message should:

  • Tell users what happened. If there's a solution, explain it. If possible, offer a one-click fix with a button. If there's no solution, give troubleshooting instructions.
  • Be placed close to the source of the problem.
  • Communicate severity using the appropriate color and tone of voice.
  • Use plain language.
  • Be specific. For example, use precise numbers and dates.
  • Be brief.

Good design can reduce the need for error messages by preventing them in the first place.

Error message types ​

Think about the scope of the error when selecting a message type. Is something wrong with the entire application, with the entire current screen, or with a specific element of the screen?

If the cause of the error is visible and the error just happened, show the error message immediately and as close to the source of the problem as possible.

Text field validation error ​

Use when:

  • An error applies to a text field and feedback can be provided while users are using the input.

Settings warning ​

Use when:

  • The form input is valid, but you want to warn users of a consequence they might not expect.

Page-level banner ​

Use when:

  • An error applies to the entire page
  • The error is far down the page and it's critical users see the message
  • Multiple validation errors on the page need to be summarized
  • The error was delayed and it's okay to inform users of the problem when they return to the page

Use when:

  • An error applies to a single card within the page, a single selection within the card, or a modal
  • You need to direct users to a page with multiple sections and you want to visually call out the section with the error

Home notification ​

Note: Home notifications should rarely be used for errors. Always attempt to display an error lose to the source of the problem.

Use when:

  • A high-priority task must be completed immediately to continue using Returnless or avoid losing money
  • A feature doesn't have a dedicated details page

Admin unavailable ​

Use when:

  • A server error is preventing an entire page from being displayed, like with 400 or 500-series server errors
  • Account permissions are preventing someone from accessing Returnless

Error colors ​

Red is the scariest error color. Only use red for critical messages that users need to deal with immediately to avoid hard to their business. For example, if users don't act on the message right away, they might lose money or their account might be suspended.

Yellow error messages still demand attention, but are more appropriate for messages that are part of the daily workflow.

Critical red ​

Use critical messages to:

  • Bring attention to urgent tasks. If not dealt with immediately, users' business will be noticeably impacted, like an account being suspended or money being lost.

Examples of critical messages types:

  • Update a payment method expiry date
  • Unsuspend an account
  • Fix a problem that's preventing data from being processed

Warning yellow ​

Use warning messages to:

  • Help users fix issues, so they can complete a common workflow or continue to the next step
  • Notify users about upcoming expirations or pending requests that, if not dealt with soon, could lead to problems in the future

Examples of warning message types:

  • Fix a problem before proceeding to the next step
  • Fix a problem at some point in a common workflow
  • There's an upcoming expiration
  • Changing a setting might have unintended consequences

Anti-patterns ​

Avoid using toasts for error messages ​

Although error toast is still available, it's discouraged to use. Toast messages are too short to adequately explain what went wrong and how to fix the problem. Because the toast component appears at the top of the screen and disappears after a few seconds, or is not directly in the users' line of sight, it can easily be missed. Reserve toast for errors not caused by users, like a connection issue. Always try to use a banner to inform users about persistent errors.

Don't use modals for errors ​

Modal dialogs are a good way to ask users to confirm a destructive action, but not to tell them an error has occurred. Modals block users until a decision is mode, which is likely to make users feel pressured. Most errors don't need to block access to the rest of the feature.

Avoid using home notifications for errors ​

Home notification errors are for high-priority tasks that users must complete immediately to continue using Returnless or prevent a negative impact to their business. One exception is errors for features that don't have a dedicated page.

Form validation ​

Text field validation ​

Use when:

  • A text field has formatting requirements.

Don't use when:

  • It takes more than a full second to validate input and display a message. If there's a lag before a validation message appears, users might shift their attention and miss the error. Either find a way to improve the validation speed, or rely on the validation after form submission.
  • The field is empty. Users might tab through a form before filling it out, and errors on empty fields can cause confusion and frustration.

Content ​

  • Use two or three words to explain what's wrong or what's needed to fix the problem.
  • Since the message is directly below the text field, the copy only needs to explain why the error happened. Optionally, the message can clarify what to do next or offer a one-click fix.

Validate on submit ​

Validate on submit is triggered when users press the form's submit button. The submit button is often [Save], but can be another call to action.

Use when:

  • Not all fields can be validated while users are typing. When a form is used for saving data, always validate on submit and validate text fields while typing. For example, if users never interact with a required text field, there's no change to mark it as not valid until they press the submit button. The same applies to form controls other than text fields, such as radio-buttons and selects.

Don't use when:

  • A form doesn't have specific validation requirements, or the form doesn't save data. For example, a search form that returns no results should display an empty state, rather than a validation error.

Settings warning ​

Use:

  • To help users prevent potential mistakes
  • When form input is valid, but you want to warn users of a consequence they might not be expecting

Don't use:

  • For actual error states

Tip: explore ways to prevent the warning message from showing at all. Look for opportunities to add help text or other contextual information to surface or highlight potential risks or consequences of taking, or not taking, the action.

Content ​

  • Since the warning message is in close context to the action that triggered the warning. It should be short
  • Explain the risks or consequences of an action that's just been taken
  • If available, link to a resource where users can learn more

Banners ​

Page-level banners ​

Use when:

  • An error applies to the entire screen
  • The error is far down the page, and it's critical that they see the message
  • A form was submitted with fields that are not valid
  • If the error was delayed, for example, an action was taken and the error doesn't immediately appear in context

Don't use when:

  • It's possible to place the banner [in context] because the source of the error is in view and the event that triggered the action just happened

Page-level banner errors should explain:

  • Where the error happened
  • What happened
  • Why it happened
  • What to do next

Banners in cards and modals ​

Use when:

  • Users are engaged in a task or flow, and you want to warn them about potential issues with the task at hand, or inform them something has gone wrong
  • Directing users to a page with multiple sections and you want to visibly call out the section with the error

Don't use when:

  • An error applies to the entire screen
  • The error is far down the page, and it's critical that users see the message

Errors without solutions ​

When a service issue occurs in Returnless or is caused by a third party, we don't always have a solution to offer to users. In these cases always explain what went wrong so they can attempt to troubleshoot. If available, provide them with a troubleshooting step, like refreshing the page or returning at a later time.

Use when:

  • Users are being denied access to a page or the entire panel
  • A third party issue is causing a disruption to users' workflows

Don't use when:

  • There's literally any solution we can offer to users

Voice and tone ​

These content guidelines are based on common copy mistakes. Avoid sounding overly apologetic, too technical, or hyperbolic. Keep Returnless out of the conversation unless Returnless was the cause of the error. Don't downplay the error by telling users not to worry or by adding humor to a negative situation.

Avoid the word "please" so it's not overused throughout the interface. Don't downplay serious problems.