UI Component

Alert

Inline, persistent message that communicates the status of a task or the state of the system.

Platform: bothTags: feedback, status, inline, message

Purpose

Draws attention to important contextual information without interrupting the flow the way a modal does. Unlike a toast, an alert is persistent and tied to a place in the layout.

Anatomy

Container: tinted background + 1px border matching the tone
Leading icon: 18px, communicates the tone (info, success, warning, error)
Title: 14px semibold (optional for single-line alerts)
Body: 14px, secondary color, supports links
Optional dismiss button: top-right, 15px close icon
Optional action: button or link below the body

States

Info: neutral/blue tint, informational icon
Success: green tint, check icon
Warning: amber tint, triangle icon
Error: red tint, x-circle icon (also role="alert")
Dismissed: removed from flow (only if dismissible)

Tokens

spacing

padding: 14pxiconGap: 12pxactionGap: 8px

sizing

iconSize: 18pxborderRadius: 8pxborderWidth: 1px

Reserve red/error tone for problems the user must resolve
Write the body as "what happened + what to do next"
Pair color with an icon and text - never signal tone by color alone
Place the alert next to the content it refers to

Don't

Use an alert for transient success - prefer a toast that auto-dismisses
Stack many alerts - consolidate or prioritize
Make a critical error dismissible without resolution
Use warning tone for routine information

Accessibility

Use role="alert" for errors so screen readers announce immediately
Use role="status" for non-urgent info/success
Do not rely on color alone - include an icon and clear text
If dismissible, the close control needs an aria-label ("Dismiss")

Code Example

<div role="alert" class="alert alert-error">
  <svg class="alert-icon">…</svg>
  <div>
    <p class="alert-title">Payment failed</p>
    <p>Your card was declined. Try another card.</p>
  </div>
</div>