Alert
Usage
Use an inline alert for a message about the content it sits next to that should stay visible until resolved: an overdue vehicle on its detail page, a failed import above the table, a confirmation after saving a form.
- Info — neutral context ("Telematics sync runs every 15 minutes").
- Success — an action finished and the result is on this page.
- Warning — something needs attention soon ("Vehicle KX-24 is overdue for service").
- Danger — something failed or is blocked; say how to fix it.
For brief confirmations that don't need to stay, use a toast. Content: title states what happened in ≤ 8 words; description says why and what to do; actions are verb + object ("Schedule service"). Don't make every alert dismissible: danger alerts stay until the problem is fixed.
Anatomy
- Container —
.alert.alert--{tone}, tinted fill and a 4px inline-start bar - Icon —
svg.alert__icon, different shape per tone,aria-hidden - Title —
.alert__title - Description —
.alert__description - Actions (optional) —
.alert__actions - Dismiss (optional) —
.alert__dismissicon button
Examples
Alert
Telematics sync every 15 minutes
Odometer readings on this page can be up to 15 minutes old.
Service plan saved
KX-24 is next due for a brake inspection at 104,000 km.
Vehicle KX-24 is overdue for service
Brake inspection was due at 84,000 km. It's now at 85,200 km.
We couldn't import 3 vehicles
Rows 4, 9 and 17 have no VIN. Add the VINs to the file and import it again.
Fuel report moved
Monthly fuel reports are now under Reports › Costs.
Vehicle KX-24 is overdue for service
Brake inspection is 1,200 km overdue. Book it before the next dispatch.
<!-- Present at page load: no role -->
<div class="alert alert--warning">
<svg class="alert__icon" aria-hidden="true" focusable="false"><use href="#icon-triangle-alert"></use></svg>
<div class="alert__content">
<p class="alert__title">Vehicle KX-24 is overdue for service</p>
<p class="alert__description">Brake inspection is 1,200 km overdue.</p>
<div class="alert__actions"><button type="button" class="btn btn--secondary btn--sm">Schedule service</button></div>
</div>
</div>
<!-- Inserted after an action: role="status" (polite) or role="alert" (urgent errors) -->
<div class="alert alert--danger" role="alert">…</div>
<!-- Dismissible (js/alert.js) -->
<button type="button" class="btn btn--ghost btn--sm alert__dismiss" aria-label="Dismiss: Fuel report moved">…</button>API
| Hook | Values | Purpose |
|---|---|---|
.alert | block | Container (info tone by default) |
.alert--info | --success | --warning | --danger | modifier | Tone |
.alert__icon | __content | __title | __description | __actions | __dismiss | parts | See anatomy |
role="status" | "alert" | attribute | Only when inserted dynamically: polite / assertive announcement |
data-alert-return="id" | attribute on dismiss | Where focus goes after dismissing (default: next focusable element) |
alert:dismiss | event | Fired on the alert so apps can remember the choice |
Do and don't
We couldn't save WO-1042
The connection dropped. Your changes are kept — try again.
Error 500
Accessibility
| Key | Behavior |
|---|---|
| Tab | Reaches actions and the dismiss button in reading order |
| Enter / Space on dismiss | Hides the alert and moves focus to the next element, so focus isn't lost |
- Static alerts have no role — they're read in order. Add
role="status"orrole="alert"only when inserting the alert after page load, and insert into an element that's already in the DOM. - Tone is never color alone: each tone has its own icon shape and the title says what happened.
- The dismiss button's name includes the alert title ("Dismiss: Fuel report moved"), so it's clear out of context.
- Contrast:
color.feedback.*.fgoncolor.feedback.*.bgpairs are checked at 4.5:1 in every theme. - Forced colors: border and icon switch to
CanvasText.
Tokens
| Custom property | Purpose |
|---|---|
--color-feedback-{info|success|warning|danger}-bg | Fill |
--color-feedback-{tone}-fg | Text |
--color-feedback-{tone}-border | Border and inline-start bar |
--color-feedback-{tone}-icon | Icon |
--radius-md, --space-1 | -3 | -4 | Shape, bar width, padding |