Designer view

Alert

An inline non-blocking message that surfaces important information to the user — system status, validation errors, success confirmation, contextual warnings — and announces itself to assistive tech via an `aria-live` region. Distinct from Modal (blocking, demands response), Toast (auto-dismissed, transient), and Tooltip (on-demand description). Alert sits in the document flow, persists until dismissed or the underlying state changes, and may carry optional inline actions.

When to use

Use

When the user must be informed of a system state, validation result, or contextual situation that does not require immediate response — form submission errors, save confirmations, network warnings, system maintenance notices. Alert sits in the document flow, persists until dismissed or the underlying state changes, and announces via aria-live.

Avoid

For decisions or destructive confirmations that block the user — that is `Modal[variant=alertdialog]`. For transient auto-dismissed feedback — that is `Toast`. For on-demand descriptive text — that is `Tooltip`. For permanent informational content (page descriptions, instructions) — that is body prose, not Alert.

Versus related

modal
`Modal[variant=alertdialog]` is a blocking confirmation that demands user response (focus trap + inert siblings). `Alert` is non-blocking and inline; the user may continue working while the alert is visible. Do not confuse the terminology — "alert" the inline message vs "alert dialog" the blocking modal.
toast
`Toast` auto-dismisses after a short visible duration (3–7 seconds canonical); `Alert` persists until the user dismisses or the underlying state changes. Toast is for transient confirmations ("Saved"); Alert is for situations the user may need to revisit or act on.
tooltip
`Tooltip` is on-demand description revealed by hover or focus; `Alert` is system-pushed announcement. Tooltip is pulled by the user; Alert is pushed by the system.
banner
`Banner` is a region-wide persistent informational surface (e.g. a maintenance notice at the top of every page); `Alert` is contextual and tied to a specific situation (a form error, a recent action confirmation). Banner often spans the viewport width; Alert sits within a region.

Highlight Required only Floating Repeats Tokens

Fig 1.1 · Alert · Designer view

Designer

Figma anatomy

Slot	Figma type	Hint
`container`	frame	Auto-layout horizontal frame; severity drives accent treatment via a Variant property
`icon`	instance	Icon component instance; glyph swap bound to severity Variant
`title`	text	Heading text style; bound to a component property for content
`body`	text	Body text style; bound to a component property for content
`actions`	frame	Auto-layout horizontal frame containing button instances
`dismiss-button`	instance	Icon button instance; visibility bound to dismissible property

Designer

Token usage per slot

container

spacing: paddingspacing.compact
gapspacing.compact
radius: cornerradius.md
color: backgroundcolor.surface.bg
bordercolor.border.subtle

icon

color: foregroundcolor.text.accent

title

color: foregroundcolor.text.primary
typography: sizetext.md
weightweight.semibold

body

color: foregroundcolor.text.primary
typography: sizetext.sm
lineHeightleading.normal

actions

spacing: gapspacing.tight
paddingspacing.tight

dismiss-button

spacing: paddingspacing.tight
radius: cornerradius.sm
color: foregroundcolor.text.muted
ringcolor.border.focus

Both

Figma ↔ Code property map

Figma	Type	Code	Notes
`Severity`	Variant	`severity`	Maps info / success / warning / error. Drives role (alert vs status) plus visual treatment plus icon glyph.
`Density`	Variant	`density`	comfortable / compact.
`Dismissible`	Boolean	`dismissible`	Toggles the dismiss-button slot visibility plus the dismiss event wiring.
`Has Icon`	Boolean	`hasIcon`	Toggles the icon slot. Canonical default is true for severity reinforcement.
`Has Title`	Boolean	`hasTitle`	Toggles the title slot. Single-sentence alerts often skip the title.
`Title`	Text	`title`	—
`Body`	Text	`body`	—
`Has Actions`	Boolean	`actions`	—
`Actions`	Instance Swap	`actions`	Swap the actions slot — typically a Button or two.
`Icon`	Instance Swap	`icon`	The severity icon. Designers may swap the auto-derived glyph for a custom icon (e.g. a domain-specific warning); code respects the swap when provided, otherwise renders the severity-default icon.

Designer

Motion

Transition	Duration token
`open`	`motion.duration.fast`
`close`	`motion.duration.fast`

Easing: motion.easing.standard
Reduced motion: Instant (jump cut)

Designer

Responsive behaviour

Breakpoint	Change
`breakpoint.sm`	At and below, alert containers stack vertically when multiple alerts share a region; actions wrap below the body rather than aligning inline-end. Compact density becomes the default for narrow viewports to preserve screen real estate. Title and body inherit the document's line-height; severity icon size remains constant for recognition.
`breakpoint.md`	Above this width, alerts render as authored. Comfortable density with actions inline-end; dismiss button at the inline-end corner of the container.

Both

Internationalisation

RTL · mirroring

Severity icon position moves from inline-start to inline-end visually (logical positioning via `inset-inline-start`). Dismiss button moves to the visual left in RTL (still inline-end logically). Actions group reverses order logically: primary action stays on inline-end (visual right in LTR, visual left in RTL). Icon glyphs themselves do not mirror — checkmarks, exclamation marks, and crosses are direction-neutral. Severity colour treatment is direction-neutral.

Text expansion

Title can grow into a second line; body free-flow with natural wrap. Actions follow Button's expansion rules and may wrap to a second row under heavy expansion. Compact density is risky for long-text languages — `comfortable` is the safer canonical default for DE / RU / FI. Severity-prefix prose ("Error:", "Warnung:") differs in length per locale; allow auto-sized title containers, never fixed widths.

Both

Variants, properties, states

Variants

Structurally different versions of the component.

infosuccesswarningerror

Properties

The same component, parameterised.

Property	Type
`dismissible`	`boolean`
`hasIcon`	`boolean`
`hasTitle`	`boolean`
`density`	`comfortable \| compact`

States

Browser/user-driven (interactive) vs. app-driven (data).

Kind	States
`interactive`	`hoverfocus-visible`
`data`	`openbusydismissed`

Both

State transitions

From	To	Trigger
`open`	`busy`	User activates an action (e.g. Retry). The action handler is in flight; the alert's actions show a busy indicator and become non-activatable. The body and severity remain announced.
`busy`	`open`	The action settles (success or failure). On success the consumer typically updates the alert's variant or replaces the alert with a new one; on failure the alert stays in error state with the failure cause appended.
`open`	`dismissed`	User clicks the dismiss button (when `dismissible: true`). The alert is removed from the document and from the live region; focus moves to the next document focusable unless the alert was the only focusable in its container, in which case focus restores to the trigger that surfaced the alert (rare).

Both

Figma↔Code mismatches

01

Figma
An alert drawn with severity communicated by background colour alone

Code
Severity is reflected via `role` (alert vs status) plus the icon glyph plus the visible severity word in the body

Consequence
Designers may rely on Figma's coloured background as the severity differentiator and skip the icon and the explicit severity word. Implementations following the Figma file ship colour-only severity — fails WCAG 1.4.1 (Use of Color) for users with colour-vision deficiencies, and fails for SR users entirely (the role is not implicit in colour).

Correct
Severity is communicated through THREE layers: visual treatment (background, border, icon glyph), accessible role (alert vs status), and explicit prose (the body or title text names the severity for SR users).
02

Figma
A dismissible alert drawn with no clear undo affordance

Code
An alert with destructive dismissal (the underlying state is also lost)

Consequence
Designers draw an "×" close button without considering what dismissal means. Developers ship `onDismiss` that simply removes the alert from the DOM; the user dismisses an important warning by accident, the warning is lost, and the underlying problem persists silently.

Correct
Distinguish dismiss-the-alert from dismiss-the-issue. Dismissing the alert is a UI affordance; dismissing the issue requires user action (Retry, Undo). Document both in the actions slot. For warnings of system state, the alert should re-appear when the underlying state next requires attention.
03

Figma
Multiple alerts drawn stacked at the top of a region

Code
Multiple alerts stacked dynamically, all wired to live regions

Consequence
Designers draw a stack of alerts in mocks; developers ship with each alert in its own live region. SR users hear a torrent of announcements at page load (every alert fires simultaneously); pointer users see a wall of severity treatment competing for attention.

Correct
Limit canonical alert stacks to 1–3. Beyond that, replace with a "summary alert" (e.g. "3 errors prevent submission") that links to the full list rendered as a non-live region. Document the canonical maximum in the performance block.
04

Figma
Alert actions drawn as inline links inside the body prose

Code
Alert actions as separate button elements in the actions slot

Consequence
Designers compose body text with embedded links ("Click here to retry"); developers either ship the literal anchor (link semantics for an action — see Link mistakes) or invent buttons that look like links (visual confusion). Keyboard reachability and SR announcements suffer either way.

Correct
Alert actions live in the dedicated actions slot as Button elements (potentially with `variant: tertiary` for visual restraint). Body prose names what the actions do ("Save failed.") without itself being interactive.

Fix

Distinguish dismiss-the-alert from resolve-the-issue. For warnings of persistent system state, re-render the alert when the user next encounters the affected feature. For transient confirmations, dismissal is final by design. Document the contract per severity: error and warning alerts should not auto-disappear; info and success may.

Accessibility hints

	Slot	Accessibility hint
	`container`	Apply `role="alert"` for assertive severities (error, warning) where the user must attend immediately, or `role="status"` for polite severities (info, success) where the user should be informed but not interrupted. Both roles imply an implicit `aria-live` region; do not stack `aria-live` attributes on top.
	`icon`	Decorative — set `aria-hidden="true"` on the icon. Severity is communicated to SR via the `role` (alert vs status) and through the title or body text, never through the icon glyph alone (icon-only severity violates WCAG 1.4.1 Use of Color and 1.3.3 Sensory Characteristics).
	`title`	Use a real heading element of an appropriate level when the alert is a top-of-region announcement (e.g. a form error summary). For inline contextual alerts, a `<strong>` or styled `<p>` is sufficient — no heading is required.
	`body`	Plain prose. The first user-facing text the SR announces when the alert mounts (after the role is announced). Avoid embedding actions inline — separate actions into the actions slot for keyboard reachability.
	`actions`	Buttons keep native semantics. Order primary first (visually inline-end on LTR; SR announces in DOM order). Action buttons receive focus via Tab in document order; the alert does not auto-focus its actions on mount (that would interrupt the user's current task).
	`dismiss-button`	Provide an accessible name ("Dismiss alert" or "Dismiss <severity> message"). Activation removes the alert from the live region; SR users do not hear a secondary "alert dismissed" announcement (the silence confirms removal).