Accessibility
The alert follows the WAI-ARIA Alert pattern — a live region that announces an important message the moment it appears — and meets WCAG 2.1 AA. Match the live-region politeness to the urgency: an assertive live region interrupts the screen reader for errors and warnings, while a polite one waits for a pause for informational and success messages. An accessible alert makes its severity clear without relying on colour, announces itself to assistive technology as soon as it renders, and — when it can be dismissed — exposes a keyboard-operable close control with an accessible name.
For designers
Section titled “For designers”- Alert text, icons, and every variant must keep accessible contrast on each supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
- Severity must never ride on colour alone — the difference between error, warning, info, and success has to be carried by the icon and the wording too, not just the tint. Source: WCAG 1.4.1 Use of Color.
- The dismiss button’s focus style must stay visible, meet contrast on every supported surface, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
- Use semantic colour tokens (e.g.
foreground/neutral/default) rather than fixed values, so the alert adapts correctly across themes and surfaces.
For developers
Section titled “For developers”Render the alert as a live region so assistive technology announces it as soon as it appears — assertive for errors and warnings that must interrupt, polite for informational and success messages that can wait; the Labelling elements section gives the exact roles. Make sure the region is in the DOM before the message lands (or render the whole alert on demand) so the new content is announced rather than missed. Because the variant icon is decorative, let the title and body text carry the severity so it still reaches screen-reader users. When the variant is dismissible, the header holds a single icon-only close button — an ordinary tab stop that needs no custom focus scripting; after the user dismisses an alert, move focus to somewhere sensible, such as the control that opened it or the next piece of content, so focus is never stranded on a removed element. The per-element roles, names, and states are in the Labelling elements section below.
Keyboard interaction
Section titled “Keyboard interaction”| Key | Action |
|---|---|
| Tab / Shift + Tab | Move focus to / away from the close button |
| Enter / Space | Dismiss the alert |
The close button must present a large enough target for touch — meeting at least the 24 px WCAG AA minimum, with comfortable spacing from the alert’s edges. Source: WCAG 2.5.8 Target Size (Minimum).
Labelling elements
Section titled “Labelling elements”Give every element the role, name, and state assistive technology needs.
Alert region
role="alert" (assertive, implies aria-live="assertive") for errors and warnings, or role="status" (polite, implies aria-live="polite") for informational and success messages. The region takes its accessible name from the message it wraps — the title and body text — so keep that text self-describing; add aria-label only when there is no visible text to name it. The decorative variant icon is aria-hidden="true" so it isn’t announced.
Close button
An icon-only <button> with no visible text, so give it aria-label="Close" (or "Dismiss") for its accessible name. The icon-close glyph inside is aria-hidden="true", so the button announces as its label alone.
Source: WCAG 4.1.2 Name, Role, Value.