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
Types of errors and warnings
Anatomy of hint, error, and description text
Form fields should provide helpful information to the user for how they should fill out the field. To understand the anatomy of these elements, read the documentation for Field Message.Page-level messages
This error type is used when an error applies to the entire page. They are represented as Alerts that are placed below 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
Errors and Tabs
When Tabs are present, Alerts can be placed either below the Tab or above the Tab depending on how critical it is a user should know about the status. As a rule, place it below the Tabs. Don’t represent status directly in the Tabs.Copy Elements
- Bolded Headline
- Sentence explanation & next step
- 1-2 CTAs can be buttons or links (optional)
Copy Rules
- Headline should be title case if two words or less, otherwise sentence case
- Sentence(s) should be action focused, active voice, and include next steps for user to take. No links in body
- CTAs should be title case for two words or less, sentence case for more
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 an Alert 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 Alerts and individual form field errors.
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 a Textfield has known formatting requirements. If the requirement is ambiguous to a user (e.g., password requirements), add a hint
- 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
Copy Elements
- Short fragment or sentence
Copy Rules
- Sentence case no punctuation
Alert Summary of Error(s)
It is recommended to add an Alert 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 Alert should only appear after a validating on submit. Validations before submission do not need an Alert
- 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
Copy Elements
- Bolded Headline
- Sentence explanation & next step
Copy Rules
- Headline should be title case if two words or less, otherwise sentence case, no punctuation
- Sentence(s) should be action focused, active voice, and include next steps for user to take
- No links or buttons
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 Alert 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
Copy Elements
- Bolded Headline
- Sentence explanation (optional)
- Button CTA
Copy Rules
- Headline should be title case if two words or less, otherwise sentence case
- Sentence(s) should be action focused, active voice, and include next steps for user to take.
- CTAs should be title case for two words or less, sentence case for more
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.
Copy Elements
- Sentences
- Button CTA
Copy Rules
- Full sentences with punctuation should be used
- CTA should be title case for two words or less, sentence case for more
Empty state errors and warnings
Many different contexts for an empty state can exist, some of which can be tied to errors and warnings.
Copy Elements
- Bolded Headline (optional)
- Sentence(s) explanation
- Button CTA (optional)
Copy Rules
- Headline should be title case if two words or less, otherwise sentence case
- Full sentences with punctuation should be used for body copy
- CTA should be title case for two words or less, sentence case for more
Errors vs Warnings
Anvil provides the option of warning and error statuses across many of its components. Warnings, usually represented in yellow or orange, are a way of providing a less severe notification to users. They are useful when users should be informed of something, but aren’t necessarily required to take action on something.Examples where warnings are preferred
- If a user can correct the issue at a later point
- The system detects something might be wrong from a user input
- To signal that significant change may/will happen in the future
- To prevent future errors from occurring.
Examples where errors are preferred
- If a user cannot proceed in a task without resolving the issue
- When server or network issues arise
- For form validation
Preventive Measures
While we can’t prevent all errors, we can design interfaces that help minimize user mistakesDisabling submission
For simple layouts, the primary action can be disabled until all required fields are filled out, and paired with a Tooltip to give the a user a hint. In complex layouts however, a submit-type button can help a user figure out what to do to proceed.
Confirmation Dialog
Adding confirmations can be useful to avoiding mistakes. See the Confirmation pattern for specific uses.
Copy Elements
- Bolded Headline
- Sentence explanation
- Button CTA
Copy Rules
- Headline should be sentence case
- Sentence(s) should be action focused, active voice, and include next steps for user to take. No links in body
- CTAs should be title case for two words or less, sentence case for more
Required labeling
When form field elements are required, the * can help users identify what they need to fill out.
Anti-patterns
Some components could theoretically be used to display errors, but should be avoided.- Don’t use Dialogs or browser alerts to display errors or warnings. Unless the content already existed in these overlays, these components should not be used to display errors. These components interrupt, adding an extra step to resolve errors
Don’t
- Avoid overlay components to display error messages when an inline variation exists. Tooltips and Popovers can prevent an end user from scanning the content of a page
- Don’t validate form elements while a user is still interacting with it. Many form elements do not start off validated correctly (e.g., typing out an email at the start will be missing the @)
- Avoid Red Buttons to indicate an error. Red buttons signify that an act is destructive (such as deleting a document or an action that cannot be undone). Other components should be used to signify the presence of an error
Copy Guidelines
- Content should be clear and easy to understand. It should be encouraging without being overly apologetic or humorous
- Avoid development jargon. Users are unlikely to be familiar with the inner workings of the app or web development. Frame copy toward user actions and goals, not the underlying software cause of the problem
- If it’s known how to resolve the issue, the copy should explain it. For example, “Enter a maximum price higher than the minimum price.” is more helpful than “Enter a valid maximum price”
- When user action caused the error, avoid outright blame on them
- When the error is caused by the app, accept responsibility and apologize
Additional resources
- The product content team has additional internal documentation on writing for Error and other message types.
- NN Group, How to Report Errors in Forms: 10 Design Guidelines