# Errors

Places each failure where it happened and words it as what did not happen and what to do now, without blame and without losing the reader's input.

* Kind: pattern
* Page: https://design.werklist.com/patterns/errors
* Version: 2.1.2

## When to use it

* A field the form cannot accept: an error under the field
* An action that did not go through: an error toast with Try again
* A page or a list that did not load: the error in place of the content
* Part of a list that did not load: a warning band above the part that loaded
* A condition that stops the page: an error inline message at the top, with the fix
* A failure inside an open dialog: an inline message at the top of the dialog

## When not to use it

* An error sent as a notification
* An error behind the scrim of a dialog
* Try again when trying again cannot work
* A confirmation dialog for a loss that Undo can reverse

## Rules

* Say what did not happen, naming the thing, then what to do.
* Give the cause only in the reader's words, and only when it helps them act.
* Write about the thing, not the person.
* Keep the reader's input. A failed save leaves the form filled, and an offer that was not sent keeps what you wrote.
* Offer Try again only when trying again can work. Otherwise name what can.
* No apology, exclamation mark or code in the sentence. A support reference goes on its own line after it, where it can be copied.
* The error in place is laid out as an empty state: the sentence in --text and a secondary Try again button. The toolbar stays.
* The error ink --error-ink is for error toasts and error inline messages.
* A page that did not load says 'This page did not load.' at page size, with Try again and no icon.
* After a failed submit, focus moves to the message at the top of the form, which links to each field.

## Accessibility

* An error raised by the reader's action is an alert, heard once.
* An error present when the page loads is read in its place.
* Color is never the only signal: the sentence names the problem.

## Content

* 'The offer was not sent. Try again.'
* 'Could not reach the server. Nothing was sent.'
* 'The job board did not answer. Try again in a moment.'
* Not 'Something went wrong.', not 'Invalid input', not 'Oops'

## Tokens

* --text
* --error-ink
* --warning-ink
* --surface-control