Alert
Alerts are persistent inline banners that communicate page-level status, warnings, or information. Unlike toasts, they do not auto-dismiss and are embedded in the page layout.
Overview
Use alerts when the information is important enough to remain visible while the user interacts with the page. Alerts appear below the page header, above the main content area. They use the same semantic color system as badges and toasts but with border-radius:12px and a bordered style.
Alert vs Toast: Use an Alert when the message must remain visible for the user to act on. Use a Toast for transient feedback after a user action (save, delete, etc.).
Variants
Attention: 3 team members have not checked in today. Location data may be outdated.
Note: Temporary password will be auto-generated. User must change it on first login.
Showing data for the last 6 months. Use the date range filter in the topbar to adjust.
All systems operational. Last backup completed 2 hours ago.
Token Reference
| Variant | Background | Border | Text Color | Icon Stroke |
|---|---|---|---|---|
| warning | linear-gradient(135deg,#FEF3C7,#FFFBEB) | #FCD34D | #92400E | #E3A008 |
| danger | #FDE2E2 | #FCA5A5 | #9B1C1C | #F05252 |
| info | #E1EFFE | #BFDBFE | #1E429F | #3B5BDB |
| success | #DEF7EC | #6EE7B7 | #03543F | #0E9F6E |
AI Implementation Notes
For AI coding assistants: Alerts are
<div> elements with class .alert .alert-{type}. They always contain: an SVG icon with stroke color matching the type, a .alert-content div with the message, and an optional action button. The icon stroke color is ALWAYS the same as the warning/danger/info/success solid color token — not the text color. Place alerts immediately after the page header, before the main content grid.
When to Use
Use Alert when
- Page-level status that must remain visible while user works
- System warnings that affect the current page
- Persistent errors that require user action
- Important notes in forms (e.g. password policy)
Don't use Alert when
- Transient feedback — use Toast instead
- Field-level validation — use form-error-msg
- Modal-level warnings — use callout inside modal
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| type | string | required | — | Semantic type. 'warning' | 'danger' | 'info' | 'success' |
| children | ReactNode | required | — | Alert message content. Can include strong tags for emphasis. |
| action | ReactNode | optional | undefined | Optional action button rendered on the right. Use .btn-sm with variant matching alert type. |
Behavior
Alerts are static — they have no entrance animation, no auto-dismiss, and no interactive behavior unless an action button is explicitly added. They render when the condition is true and unmount when false. Place immediately after the page header, before the main content grid.
Design Decisions
Why gradient background for warning alerts?
Warning alerts use
linear-gradient(135deg,#FEF3C7,#FFFBEB) instead of flat color. The subtle gradient adds warmth and visual interest that signals "this needs attention" more effectively than a flat background. It makes warnings feel more urgent than success/info alerts while remaining softer than danger.Changelog
v1.0.0July 2026Added
- 4 semantic types: warning, danger, info, success
- Optional action button slot
- SVG icon replaces emoji for consistency
States
Alert banners are static. They render when the condition is true and unmount when false. No hover, focus, or interactive states unless an action button is included.
Accessibility
| Requirement | Implementation |
|---|---|
| role="alert" | Add to danger alerts. Triggers immediate screen reader announcement. |
| role="status" | Use for info/success alerts. Polite announcement, less urgent. |
| Color alone | Never rely on color only. Always include icon + text label together. |
Composition
Allowed
Top of page content, below page header
Inside modal body as a warning/note
With optional action button on right
Forbidden
Inside table cells or list rows
More than 2 stacked on one page
As replacement for toast notifications
Best Practices
Do
Place alert immediately after page header, before main content.
Users see the alert before engaging with page content.
Don't
Place alerts buried inside card content or after tables.
Users may miss the alert entirely.
Related Components
Anatomy
1
Container
div.alert.alert-{type}. border-radius:12px, padding:14px 18px, display:flex, border:1px, semantic background color.
2
Icon
Inline SVG, 18px, stroke matches semantic color (not text color). flex-shrink:0, margin-top:1px for alignment.
3
Content
div.alert-content. flex:1, font-size:13px, line-height:1.6. Can contain strong tags for emphasis.
4
Action (optional)
Optional .btn-sm on the right. flex-shrink:0. Use variant matching the alert type.
Content Rules
Good
3 sales reps have not checked in today.
Specific, actionable, present tense.
Bad
There is an error in the system.
Vague — users cannot act on this.
Good Action Label
View Details
Describes exactly what clicking does.
Bad Action Label
Click Here
Describes the interaction not the outcome.