A persistent inline message about the state of the thing it sits beside — a page, a form, a section. It stays until the condition it reports changes. The boundary against Toast is placement and lifetime: an alert sits in the flow next to its subject and persists, a toast floats above the page and leaves. The emphasis tiers follow that split — the subtle tint belongs to the alert, the solid fill to the toast — so the two never share a surface.
Against Dialog the test is simpler still: an alert reports, a dialog demands. If the reader cannot continue without answering, it is not an alert.
Neutral is the unmarked base — the only variant with a visible border, since it sits on a page surface with no tint to define its edge, and the only one without an icon: the canonical glyphs map 1:1 to the status variants, and a neutral alert wearing i-info would be the info variant in all but tint. The four status variants are shaped by their own fill and set the border transparent. Each arrives as a bg + text pair from the status roles and is consumed whole.
| Example | Modifier | Roles | Usage |
|---|---|---|---|
Draft saved locally. | — | surface.pageborder.subtle | Ambient state with no status meaning — no icon, no claim |
Domain verified. | --success | status.success.bgstatus.success.text | A condition that resolved and still holds |
Your plan expires in three days. | --warning | status.warning.bgstatus.warning.text | Reversible caution — still working, not for long |
Billing failed. Update the card to keep the service running. | --error | status.error.bgstatus.error.text | A failure the reader has to act on |
Two-factor sign-in is available. | --info | status.info.bgstatus.info.text | Neutral information worth stating in place |
Placement is most of what an alert is. It belongs directly above the thing it describes, inside the same column, so the reader meets the condition before the controls it affects — a form alert above the fields, a section alert at the top of the content. An alert parked away from its subject is furniture.
Payment method
We could not save your billing details
The card was declined by your bank. Try a different card, or contact them and retry.
A settings panel: the alert sits under the panel's heading, at the head of the form it concerns and at the panel's own width, and stays until the save succeeds. It reports the failure and names the next step — a message that only said “something went wrong” would leave the reader with nowhere to go. The title earns its place here because the body runs past a sentence; a one-line alert is a body alone, as in the variants above.
An alert describes a condition, so it lives and dies with it.
| Verdict | Rule |
|---|---|
| Do | Use an alert for a condition that persists, a toast for something that passes, and a dialog for something the user must answer. |
| Do | Place it next to what it describes — a form alert above the fields it concerns, a page alert at the top of the content column. An alert floating away from its subject is furniture. |
| Do | Give error alerts role="alert" so they are announced immediately; everything else takes role="status", which waits for a pause. |
| Do | Say what to do, not only what happened. An error alert that names no next step leaves the reader stuck. |
| Don’t | Add a dismiss control. If the condition has cleared, remove the alert; if it has not, hiding it hides a state that is still true. |
| Don’t | Stack alerts. Two at once means neither is read — combine them, or fix the ordering so only the live condition shows. |