Alert

​

What it is

An alert is a message about the state of what the reader is looking at, shown in place, alongside the content rather than instead of it. It has a severity — error, warning, info, or success — and that severity chooses its colour and its icon. It stays until something changes it. That is what separates it from a toast, which passes on its own, and from a dialog, which stops the reader until they answer.

​

Live example

​

Exports

​

Vocabulary

Severity is the whole vocabulary. There is no size axis and no prominence axis. The design library publishes exactly four alerts — one per severity — each in a single-line and a wrapped form, and each dismissible.

​

Choose Alert when

• The message is about the content on screen and the content is still there.
• It should persist — until the reader fixes it, dismisses it, or the state changes.
• The reader does not have to respond before continuing.

​

Choose something else when

​

Anatomy

​

Variants, sizes, and states

Four severities, and one treatment. The design library publishes a single visual treatment per severity: a pale tinted background, a filled severity icon, dark text of the same hue, and a dismiss control. That treatment is the standard variant, and it is the only one the theme colours completely. Two content forms: one line, or wrapped to several. The design publishes both; nothing else about the box changes. The severity icon is chosen for you, and every published example overrides it anyway. Take the default: it is the one that stays consistent across the product, and each app picking its own is how four icons come to mean “error”.

​

Edge and failure states

​

Tokens

Two component tokens — alert-padding-y and alert-message-padding-y. Everything else resolves through the -alt colour family: background-{severity}-alt, text-{severity}-alt, icon-{severity}-alt, and border-{severity}-alt. That family is the reason the standard variant passes contrast and the other two do not: it is designed as dark-text-on-pale-tint, and only the standard variant supplies the pale tint.

​

Composition

An alert sits with the thing it is about. A page-level problem goes at the top of Contents, above the body. A section-level problem goes inside that section. An alert at the top of a page describing a failure three screens down makes the reader hunt. Never inside a table row or a list item. Row-level state belongs in the row — a Tag or a cell — and an alert inside a repeating structure repeats with it. A load that failed keeps its content. Put the alert above the stale rows rather than replacing them with an EmptyState: the reader can still read what they had, and an empty region is indistinguishable from a successful query with no matches. One trailing action, and it resolves the alert — retry, undo, review. Not a second action, and not navigation away from the thing the alert is about.

​

Content

• Say what happened and what to do, in that order, in one or two sentences.
• Name the thing. “Campaign could not be saved”, not “An error occurred”.
• Sentence case, no exclamation marks — see Capitalization.
• No severity words in the copy. The alert already says “error” with its colour and icon; starting the sentence with “Error:” spends the reader’s attention on something they know.
• Never blame the reader. “That email address is already in use” rather than “You entered an invalid email” — see Error messages.
• Do not put a period on a single fragment, and do use one when the message is two sentences.

​

Accessibility

An alert that appears in response to something must be announced. A visually obvious alert that does not reach a screen reader has told half the audience. The framework does not add a live region for you: set role="alert" for a message the reader must know about now, and role="status" for one that can wait for a pause. Do not set role="alert" on an alert that is present at page load. A live region that already has content when the page loads announces nothing, and the role’s only effect is to make the message interrupt later. Colour is never the only carrier of severity. The icon differs per severity and the message says what happened, so the alert survives being read in greyscale — which is also the test for whether the copy is doing its job. The dismiss control needs a name that says what it dismisses when more than one alert can be on screen. “Close” repeated three times identifies nothing. Contrast is arithmetic here, and it has been computed. The standard variant clears AA on all four severities; the other two variants do not — see the table above.

​

Constraints

​

Known issues

​

Why it works this way

Severity is the only axis, deliberately. A size or prominence axis would let a team make an error alert quieter, and the reason an alert exists is that the reader needs to know something. The severity is the message’s importance; there is nothing left to adjust. Colour comes from the -alt family, which is what makes the contrast work. Dark text of a hue on a pale tint of the same hue keeps the severity readable and the alert quiet enough to sit above content without competing with it. The variants that fail are the ones that abandoned that pairing — which is why the fix is a decision about whether they are supported at all, not a colour tweak.

​

Status and changelog

​

Related

• Error handling · Form validation — the two patterns that place alerts
• Toast · Banner — persistence and scope, the two nearest neighbours
• Color — the -alt family and why it exists
• Error messages — how to write the sentence