Toast

Usage

A Toast is a self-announcing message card. It has no position, no stack, and no timer — mount it inside your own overlay layer and remove it when onDismiss(id) fires. id, variant, and title are required with no defaults — a bare <Toast /> crashes at render.

import { Toast } from '@epasslive/design-system'

<Toast
  id="evt-2026-saved"
  variant="success"
  title="Changes saved"
  description="Your event details were updated."
  onDismiss={removeToast}
/>

<Toast
  id="pay-retry"
  variant="error"
  title="Payment failed"
  description="Your card was declined."
  action={{ label: 'Retry', onClick: retryPayment }}
  onDismiss={removeToast}
/>

The barrel also exports ToastMolecule — a plain alias of Toast, both pointing at the same module. Use whichever name matches your import style; the alias never diverges.

Alert vs. Toast vs. Notification

Three feedback surfaces overlap; pick by persistence and who owns the announcement. Rule of thumb: in-flow status → Alert, transient overlay → Toast, durable per-user feed item → Notification.

If the message must persist in the layout (no overlay), it is an Alert or a Notification — not a Toast. If you only need the unread count on the bell trigger, that is a Badge.

Container contract (not yet shipped)

The molecule ships as a card only — there is no ToastContainer, no queue, and no auto-dismiss anywhere in the DS today. Your app owns the overlay: render toasts in a fixed viewport region and remove them on onDismiss(id). The card already applies pointer-events-auto, expecting a pointer-events-none viewport parent.

When a DS-side container lands, it must satisfy at minimum: layer z-ep-toast (70, above popovers — currently misused by Tooltip; fix scheduled); auto-dismiss default ~5s with pause on hover/focus (WCAG 2.2.1); Escape dismisses the focused toast; focus return to a sensible target after dismiss; and forwarding of the (today inert) duration prop.

Accessibility

Announcement is variant-driven, per the WAI-ARIA APG: variant="error" renders role="alert" + aria-live="assertive" so screen readers interrupt current output; every other variant renders role="status" + aria-live="polite" and waits. aria-atomic="true" is always set.

The variant icon is aria-hidden — the visible title and description carry the message. The dismiss button is a native <button> labeled via dismissLabel (English default "Dismiss notification" — pass an explicit label on localized pages) with a teal focus-visible ring. The root mirrors data-toast-id and data-toast-variant for end-to-end tests.

Known gap (scheduled fix): the dismiss (28×28px) and action buttons sit under the 44px --ep-tap-min canonical tap target.

Dark mode

The card uses bg-ep-surface-card, ring-ep-overlay-border-subtle, and shadow-ep-md — all flip automatically with the theme. Left-border accents and icons use semantic tokens (ep-semantic-success / ep-semantic-warning / ep-semantic-error; info uses ep-teal + ep-text-teal) with dark overrides, so contrast holds in both themes. Icons are Phosphor SSR glyphs colored per variant by token classes.

Props