UI Component Spec — Design to Tailwind Handoff

Toast

Status: draft · Built on: Radix @radix-ui/react-toast · Owner: Design Systems

Purpose

A short, transient message confirming something happened or reporting that it didn't.

Use when: the result isn't already visible on screen — a background job finished, a save failed, an item was deleted with an undo available.
Don't use when: the user must act before continuing → use Dialog. The message belongs to one field → use inline error text. The state is permanent → use Banner.

Anatomy

┌─ Root ──────────────────────────────────────────┐
│ ┌Icon┐  ┌─ Title ──────────────┐  ┌─ Close ─┐  │
│ └────┘  │ Description          │  └─────────┘  │
│         └──────────────────────┘  ┌─ Action ─┐ │
└───────────────────────────────────└──────────┘─┘

Props

Controlled/uncontrolled: uncontrolled by default via the useToast() hook; open + onOpenChange for controlled use.

Variants

DECISION NEEDED: should error auto-dismiss? Recommend

no (duration: null) — an error the user didn't see is an error that gets reported as a bug. Overridable per call.

States

Close / Action focus: focus-visible:ring-2 ring-focus ring-offset-2 ring-offset-surface-raised

Sizing

Typography

Title 14px / 600 / 1.4 · Description 14px / 400 / 1.5, --color-text-muted · Action 14px / 600
Title truncates at 1 line; description clamps at 2 (line-clamp-2).

Stacking

• Max 3 visible; older ones collapse behind with translateY(-8px) scale(0.97) per level.
• New toasts enter at the front. Queue beyond 3 — don't drop.
• Hovering the stack expands it to full height.
• Toast.Viewport is the single source of stacking order — don't manage it per toast.

Accessibility

Element: Radix Toast.Root → renders <li> inside the viewport's <ol>.
Live region: the viewport is the live region and must be in the DOM before any toast is inserted. role="status" for success/info (polite), role="alert" for error/warning (assertive).

Focus: toasts never steal focus. Focus returns to where it was on dismiss.
Announcements: action.altText is what a screen reader hears — write it as an instruction ("Press F8 then Enter to undo"), not a repeat of the label.
Reduced motion: slide-in and swipe become a 120ms opacity fade; stacking offset applies instantly with no transition.

Behaviour

• Timer pauses on hover, focus-within, and when the tab is backgrounded.
• Identical consecutive toasts collapse into one with a count badge rather than stacking duplicates.
• Action click dismisses the toast unless onClick returns false.
• Swipe right dismisses on touch; 80px threshold.

Responsive

Implementation

const toast = cva(
  'pointer-events-auto relative flex w-full items-start gap-3 rounded-md border ' +
  'border-l-[3px] bg-surface-raised p-4 shadow-md ' +
  'data-[state=open]:animate-in data-[state=open]:slide-in-from-bottom-2 ' +
  'data-[state=closed]:animate-out data-[state=closed]:fade-out-80 ' +
  'data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] ' +
  'motion-reduce:animate-none motion-reduce:transition-none',
  {
    variants: {
      kind: {
        success: 'border-l-success',
        error:   'border-l-danger',
        warning: 'border-l-warning',
        info:    'border-l-info',
      },
    },
    defaultVariants: { kind: 'info' },
  }
)

const ICON = { success: CheckCircle, error: AlertCircle, warning: AlertTriangle, info: Info }
const POLITENESS = { success: 'status', error: 'alert', warning: 'alert', info: 'status' } as const

<Toast.Root className={cn(toast({ kind }), className)}
            duration={duration} role={POLITENESS[kind]} {...rest}>
  <Icon className="mt-0.5 size-5 shrink-0" aria-hidden="true" />
  <div className="min-w-0 flex-1">
    <Toast.Title className="truncate text-sm font-semibold">{title}</Toast.Title>
    {description && (
      <Toast.Description className="mt-0.5 line-clamp-2 text-sm text-muted">
        {description}
      </Toast.Description>
    )}
  </div>
  {action && (
    <Toast.Action altText={action.altText} asChild>
      <button className="shrink-0 text-sm font-semibold text-primary
                         focus-visible:outline-none focus-visible:ring-2
                         focus-visible:ring-focus focus-visible:ring-offset-2">
        {action.label}
      </button>
    </Toast.Action>
  )}
  <Toast.Close className="shrink-0 rounded p-0.5 text-muted hover:text-text
                          focus-visible:outline-none focus-visible:ring-2
                          focus-visible:ring-focus" aria-label="Dismiss">
    <X className="size-4" />
  </Toast.Close>
</Toast.Root>

Test cases

• Each kind renders the right icon, accent and role
• Error toast does not auto-dismiss
• Timer pauses on hover and on focus-within
• F8 → Tab → Enter fires the action
• Escape dismisses the focused toast only
• 4th toast queues rather than dropping
• 200-character description clamps to 2 lines, no overflow
• prefers-reduced-motion removes slide and swipe animation
• Contrast passes for all four accents in light and dark
• Close button target ≥ 24×24

Open decisions

• DECISION NEEDED: error auto-dismiss — recommend null (see Variants).
• DECISION NEEDED: do we need a loading toast for long jobs? Recommend no — use an inline progress indicator; a toast that lives for 40s isn't a toast.