Alerts
Alerts communicate persistent, inline feedback within the content flow. They use a soft surface background with a colored left indicator and title rather than a solid-fill background, which keeps the body copy readable on lower-contrast surfaces and avoids the visual alarm of a fully saturated block. Four semantic variants cover the feedback spectrum: success, warning, error, and info.
Token source: tokens/component/alert.json
Base Specifications
Section titled “Base Specifications”All alert variants share these structural properties:
| Property | Token | Resolved value |
|---|---|---|
| Border radius | primitive.radius.md | 8px |
| Padding | primitive.spacing.16 | 16px |
| Border width | 1px (hardcoded) | 1px |
| Indicator width | primitive.spacing.4 | 4px |
| Background | semantic.color.surface.primary | #FBFAF1 (warm white) |
| Title font weight | primitive.font-weight.semibold | 600 |
| Body font size | primitive.font-size.14 | 14px |
| Body color | semantic.color.text.secondary | #8C7570 (muted brown) |
Variant Specifications
Section titled “Variant Specifications”Each variant defines three properties: the left indicator bar color, the title text color, and the outer border color.
| Variant | Token | Resolved value |
|---|---|---|
| Success indicator + title | semantic.color.feedback.success-text-strong | #1A3D1A |
| Success border | semantic.color.feedback.success | #98D398 |
| Warning indicator + title + border | semantic.color.feedback.warning | #D97706 |
| Error indicator + title + border | semantic.color.feedback.error | #DC2626 |
| Info indicator + title + border | semantic.color.feedback.info | #0284C7 |
Note that success uses success-text-strong for the indicator and title rather than the lighter success green. The success green (#98D398) works as a background fill in badges but at 14–16px text sizes it does not meet WCAG AA against #FBFAF1. success-text-strong (#1A3D1A) achieves 7:1 contrast on the warm white surface.
All variants
Tinnitus session saved successfully
Background noise detected
Session data could not be synced
New research article available
Dismissible
Background noise detected
Usage Guidelines
Section titled “Usage Guidelines”Alert vs Toast. An Alert is persistent and sits inline within the page or view — it stays visible until the condition it describes resolves or the user dismisses it. A Toast (a future component) is ephemeral: it overlays content briefly, then disappears automatically. Use Alert when the message needs to remain visible while the user reads or acts; use Toast for transient confirmation feedback like “Saved.”
Choosing the right variant. Success confirms a completed action or positive state — saved sessions, completed exercises. Warning flags a condition that needs attention but is not blocking — elevated background noise, an upcoming session reminder. Error signals a failure the user needs to address — sync failure, validation error. Info surfaces neutral contextual information — a new article, a system note. Do not use error for warnings or vice versa; the color semantics carry meaning for users who rely on them.
Keep body copy concise. The soft-surface style works because the body text recedes. If the body runs longer than two or three sentences, consider whether a dedicated content section or a card is a better container.
Accessibility. Add role="alert" to the alert element so screen readers announce it. For non-urgent information (info variant) consider role="status" instead, which announces politely rather than interrupting. The dismiss button must have an accessible label (aria-label="Dismiss alert") — the × glyph alone is not sufficient for assistive technology.
Contrast notes. The success variant uses success-text-strong (#1A3D1A, 7:1 ratio on #FBFAF1) — WCAG AAA. Warning (#D97706), error (#DC2626), and info (#0284C7) are applied only to the 4px indicator bar and the title text at 14px semibold weight. Verify contrast is sufficient if you change the background behind an alert or render alerts in dark mode contexts.