v3.1.4
Notification

The transient toast: a pill that slides in from the top, delivers one short status message with an optional icon, and dismisses itself after 4 seconds — or earlier, on an upward swipe.

3.1.0 3.1.0 -- 3.1.4
Notification message

Overview

  • 1
    Neutral
  • 2
    Positive
  • 3
    Negative
Notification message
1
Success message
2
Critical error message
3

States

Notification is a status container with no interactive elements — Standard is its only rest state; there is no pressed, disabled, or loading form. Entering and Exiting, the two transit phases, are documented under Animation. Each tone below is the same structure with its own fill, content colour and default glyph.

Neutral

Notification message
1
2
3
  • 1
    Background --background-inverse-primary — the inverse surface: a dark pill on the light theme, a light pill on the dark.
  • 2
    Icon --text-and-icon-inverse-primary; the default glyph is warning-outline.
  • 3
    Description --text-and-icon-inverse-primary — the content colour.Body/Compact Body — the text style.

Positive

Success message
1
2
3
  • 1
    Background --accent-green2 — the success tone.
  • 2
    Icon --text-and-icon-always-light; the default glyph is done-outline.
  • 3
    Description --text-and-icon-always-light — the content colour.Body/Compact Body — the text style.

Negative

Critical error message
1
2
3
  • 1
    Background --accent-red2 — the failure tone.
  • 2
    Icon --text-and-icon-always-light; the default glyph is warning-tr-outline.
  • 3
    Description --text-and-icon-always-light — the content colour.Body/Compact Body — the text style.

Anatomy

Notification message
1
2
3
4
  • 1
    The component root var(--sp-s8) — the side margins, per side. The root spans the full screen width and brings them with it. Required.
  • 2
    ContentContainer var(--sp-s20) — roundness.var(--sp-s56) — height, fixed; a second text line centres within it, the pill does not grow.The visible pill carrying the tone fill. Required.
  • 3
    IconContainer var(--sp-s24) — the glyph, vertically centred in an invisible IconContainer box. Each Style brings its default glyph; the author may swap in another DS icon or hide the slot entirely (Show Icon off). Optional.
  • 4
    Description Body/Compact Body — the message's text style. One short message: up to 2 lines at 100 % scale, then ellipsis; unclamped in the 130 / 150 % accessibility modes. Required.

Layout

Vertical

Notification message
  • General var(--sp-s56) — height, fixed. A second text line centres within it, the visual air compressing from 16 to 12 — the pill never grows.var(--sp-s16) — padding above and below the content. With the var(--sp-s24) icon it is what makes the 56: 16 + 24 + 16.var(--sp-s20) — roundness, all four corners.

Horizontal

Notification message
  • General var(--sp-s8) — the root's own side margins, both sides. The component brings its screen inset with it; the host adds nothing.var(--sp-s16) — pill padding, both sides.var(--sp-s12) — gap between the icon and the text.var(--sp-s24) — the icon glyph. The text column fills the leftover width and truncates by the clamp (§ Overview).

RTL

مُلصَق
  • General The row mirrors from the document's dir — the flex order reverses on its own and the geometry is symmetric, so no class is needed.Nothing flips in place: warning-outline, done-outline and warning-tr-outline are not on the icon-container.md § 3.5 directional list. The mirrored composition is a variant of the Figma set (RTL: Off | On).

Animation

Motion follows the motion system: the toast enters and leaves off-screen past the top edge on Transforming/Enter/Default and Transforming/Exit/Default — the HeaderAlert timing. The demo toggles one state class — the timing comes from the component's own transition.

Lifecycle

Notification message
Live — enter, 4 s hold, exit, on a loop
  • General var(--transforming-enter-default) — enter, translateY(-100% → 0) from past the top edge.var(--transforming-exit-default) — exit, back up. Fires at the 4 s timeout, on an upward swipe, or when a new message replaces the current one.Only transform takes part, so the slide stays on the compositor — layout, colour and height never animate.
  • Behaviour One Notification on screen at a time: a new message plays the visible pill's exit and enters after it — the two never stack. The swipe dismisses immediately; the timeout is the platform default.
  • Reduced motion Handled at the token: motion.css zeroes every --transforming-* inside prefers-reduced-motion: reduce, so the pill appears and leaves instantly and this component carries no override of its own.

Usage

Use it for transient, self-resolving feedback: an action's outcome ("Order sent", "Address saved"), a recoverable failure ("No connection — retrying"), a background status change. The message does not depend on being seen — the pill leaves after 4 seconds regardless.

  • 1
    One short outcome A message that informs and leaves. Nothing on it is tappable and nothing waits for the user — if the user misses it, nothing is lost.
  • 2
    Not for persistent or actionable states A state the user must resolve stays on screen — that is HeaderAlert. A message carrying a button ("Undo", "Retry") is Snackbar. Copy that doesn't fit 2 lines at 100 % scale belongs in a different surface.
Address saved
✓ A short outcome that survives being missed — the toast's job
No internet connection. Check your settings and reconnect to continue using the app
✕ A persistent, blocking state — that is HeaderAlert, not a toast

Accessibility

Notification message
role="status" — Neutral / Positive announce politely
Critical error message
role="alert" — Negative may interrupt current speech
1
2
  • 1
    Announced Once, Focus Stays Put TalkBack: the root is a live region — polite for Neutral / Positive, assertive for Negative — firing once on appearance; the pill does not steal accessibility focus, and stays reachable by swipe navigation and touch exploration while visible. VoiceOver: DsNotificationAlert posts a UIAccessibility announcement; focus stays where the user is.
  • 2
    Dismiss Without the Gesture TalkBack exposes the standard ACTION_DISMISS in the pill's actions menu; VoiceOver implements accessibilityPerformEscape() (the two-finger Z scrub) — each the non-gesture equivalent of the upward swipe.
  • The Timeout Waits for the Reader While a screen reader is active the 4 s auto-dismiss extends until the announcement has finished — the message is never cut mid-sentence.
  • The Icon Is Silent Decorative on every platform — importantForAccessibility="no" / isAccessibilityElement = false / aria-hidden="true". The announcement is the description text, verbatim; hiding the icon changes nothing.
  • Web: Keep the Region Mounted The live-region container stays mounted (empty) for the lifetime of the screen and each message mutates only its text. Inserting a fully-populated live region in one DOM mutation is not reliably announced — Safari/VoiceOver and some NVDA builds skip it.
  • Contrast — Known Shortfall White 14 px text on the accent fills measures below the 4.5:1 body-text target in both themes (Positive 3.83 / 2.78, Negative 3.98 / 3.47). The pairing is the palette's own, shared with HeaderAlert; resolution is a token-level call recorded in the a11y spec.