Alert accessibility

WCAG 2.1 AA requirements

Alert must satisfy these before shipping.

Semantics

• Renders with role="alert", which triggers an assertive live-region announcement. Screen readers will read the content as soon as the element mounts.
• Do not render alerts on initial page load for static content — the live-region announcement is intended for dynamic status changes.

Colour is never the only signal

• Every variant should be paired with an icon or explicit text indicating the severity. Red alone does not communicate "error" to colour-blind users or screen readers.
• The destructive variant uses both a red border and expects the word "error" or a warning icon.

Structure

• AlertTitle renders an <h5>. Ensure it fits the page heading hierarchy or override the element if needed.
• AlertDescription renders a <div>, so it can contain paragraphs, lists, or links.

Focus management

• Alerts are not focusable by default. If the alert requires user action (e.g., a retry button inside it), ensure that button is keyboard accessible.
• Do not auto-focus the alert — role="alert" handles announcement without moving focus.

Audit checklist

• role="alert" present on the container
• Icon + text label for every severity (not colour alone)
• 4.5:1 contrast on all variants in light and dark themes
• No auto-focus — screen reader announces via live region
• Interactive children (links, buttons) are keyboard accessible