patterns / null

Errors & Warnings

Getting Started

When writing an error or warning message, consider these questions:

  • What is the issue?
    • Knowing what the issue is (or knowing that we don't know) can help frame what to communicate to the user.
  • What is the cause of the issue?
    • Common reasons could be user action, server/network issues, or not being able to find a resource.
  • What can the user do to resolve the issue?
    • If it's the app fault, explain that. If it's user error, can you identify the most likely cause?
  • Is there a path a user can take to resolve the issue?
    • Whenever it is possible for a user to take action on the issue, a path should be given. For example, if using a Banner or Toast, provide a call to action in them.

Quick Use Cases

Each of these is explained in more detail. For needing a component quickly, consider these common scenarios.

Use Case
Component(s) to use
Page level error or warning has occurred
Form validation errors
Inline Error Text inside a Form, a Banner as a summary
Background process problem
No results
Server/Network error
Application wide error or warning

Types of Errors and Warnings

Page-level Messages

This error type is used when an error applies to the entire page. They are represented as Banners, placed at the bottom of the Page Header.

They can be used to:

  • Summarize individual errors found on the rest of the page.
  • Inform the user of important, but non-critical information about the page.

Form Errors and Validation

Form errors are among the most common type of errors. Each individual component page provides specific styling and text location. It is recommended to also use a Banner as a summary when multiple errors exist.

Validating on submit

This validation occurs after a user has hit a save or submit button. These errors are paired with Banners and individual form field errors.

to

Maximum hours must be greater than the minimum.
$

to

$
Value cannot be negative

Validating before submission

When format requirements exist for a field (such as the @ in an email input), validating the form element after a user has left focus can help resolve errors.

When to use validation before submission:

  • When an Input has known formatting requirements. If the requirement is ambiguous to a user (e.g. password requirements), add a field description.

  • In the initial user interaction, validate only after a user has left focus on the field and if the user entered anything.

  • When a user interacts with an errored field, validate after each keystroke. This helps the user identify when the user has met the field requirements.

When to avoid validation before submission:

  • While the user is still interacting with the field.
  • When a field was left empty by the user.
  • When it takes at least a second for the codebase to validate the field.

It is recommended to add a Banner at the top of a form that has errors. If the form is the main content of the page, it follows the Page-level guidelines. Otherwise, it appears wherever the top of the form is.

  • The Banner should only appear after a validating on submit. Validations before submission do not need a Banner.

  • The summary should list out each of the errors encountered on the page.

  • In general, the summary should not be used alone. Inline help should be added when possible.

A job must be selected.
Arrived time cannot be before 7:00 AM.
Done date cannot be before arrived date.

System and Network Errors

System errors can typically be described as 400 or 500 type errors. If there is a place for it on the page, it is preferred to integrate an Empty State into the section. Otherwise, using a Toast is preferred over components such as the Banner or Announcement.

  • When a system error is the apps fault, take responsibility.

  • If there is an HTTP response, place it at the end of the body content.

  • When using the Toast to present an error, it should persist on the page.

  • When it is possible to determine the solution, provide it to the user. For example, a 401 error resulting from not being logged in.

Application Errors and Warnings

App-level messages are used to convey a status relevant to the entire experience, represented with an Announcement. These are not used in specific products within the platform. Some examples might include a sandbox environment message and a scheduled downtime notice.

You have no credit card specified. Please add it before your service is suspended in 3 days.

Empty State Errors and Warnings