Cloaked Design SystemOverlays

Toast

A transient feedback banner with variant color, viewport position, optional icon, action, and dismiss control.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

7 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/overlays/Toast/Toast.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

A transient feedback banner with variant color, viewport position, optional icon, action, and dismiss control.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Toast } from '@cloakedinc/design-system';

ToastToastProps

packages/design-system/src/components/overlays/Toast/Toast.tsx:41

Prop	Type	Presence	Notes
`tone`	`"neutral" \| "info" \| "success" \| "warning" \| "danger"`	Required	Semantic tone; colors the icon disc and sets `role="alert"` for `danger`.
`glyph`	"number" \| "info" \| "guard" \| "arrow-left" \| "arrow-right" \| "arrow-up" \| "arrow-down" \| "chevron-down" \| "chevron-up" \| "chevron-left" \| "chevron-right" \| "caret-down" \| "caret-up" \| "trend-up" \| "trend-down" \| "collapse" \| "expand" \| "dropdown-collapse" \| "dropdown-expand" \| "close" \| "clear" \| "menu" \| "copy" \| "search" \| "add" \| "share" \| "phone" \| "sim" \| "account" \| "family" \| "home" \| "wifi" \| "cart" \| "vpn" \| "lock" \| "block" \| "timer" \| "check" \| "send" \| "filter" \| "scan" \| "log" \| "trash" \| "missed" \| "call" \| "voicemail" \| "sms" \| "email" \| "data-removal" \| "dark-web-monitoring" \| "cloaked-pay" \| "cloaked-ai" \| "sms-guard" \| "email-guard" \| "call-guard" \| "card" \| "password" \| "bell" \| "circle-outline" \| "dot" \| "settings" \| "clock" \| "mail" \| "message" \| "user" \| "upload"	Required	Glyph inside the tone disc. The disc is `aria-hidden`, so it cannot carry what the title omits.
`title`	`string`	Required	Primary line. Clipped to one line with an ellipsis, so keep it short.
`subtitle`	`string \| undefined`	Optional	Optional second line, clipped the same way.
`haptic`	`HapticFeedback \| undefined`	Optional	Haptic fired once when the toast appears. Defaults to off.Source default: `false`
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Test selector for the root; the disc and the text nodes carry none.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A compact, top-anchored feedback pill. Toast renders only the visual — a toast host owns the show/hide timer. tone colors the leading icon disc and sets the ARIA urgency. glyph and title are required; subtitle is optional.

Use when

App toasts today are share/copy confirmations whose tone is set at runtime.

Icon

glyph is required and is not derived from tone — any DS glyph pairs with any tone.

Usage by variant

Choice	Use when	Avoid when
`Tone: neutral`	A plain notice with no status color — a bold disc.
`Tone: info`	A heads-up or neutral confirmation — copied to clipboard.
`Tone: success`	A completed action — scan complete, saved.
`Tone: warning`	Something needs attention.
`Tone: danger`	A failure — could not save. Announced as role="alert" so screen readers interrupt; the other tones use role="status".	A routine confirmation — the alert role is disruptive when nothing is wrong.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: Grid surface carrying the variant color and position animation.
Required: true

Id: icon
Label: Icon
Description: Optional leading marker.

Id: content
Label: Content
Description: Title, body, and optional action column.

Id: action
Label: Action
Description: Optional trailing control.

Id: dismiss
Label: Dismiss
Description: Optional close button.

Allowed Design Choices

Variants

Info

Label: Info
Description: Neutral status; announced as role=status.

Success

Label: Success
Description: Positive confirmation.

Warning

Label: Warning
Description: Cautionary feedback.

Danger

Label: Danger
Description: Error feedback; announced as role=alert.

Sizes

Positions

Top

Label: Top
Description: Anchored to the top edge with a top-entering animation.

Bottom

Label: Bottom
Description: Anchored to the bottom edge with a bottom-entering animation.

Variants

Id: info
Label: Info
Description: Neutral surface, role=status.
Platforms: ios
android
web

Id: success
Label: Success
Description: Success subtle surface.
Platforms: ios
android
web

Id: warning
Label: Warning
Description: Warning subtle surface.
Platforms: ios
android
web

Id: danger
Label: Danger
Description: Danger subtle surface, role=alert.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: content-gap
Label: Content gap
Kind: exact
Token: --cds-space-12
Value: 12
Unit: px
Applies To: root

Id: container-inset
Label: Container inset
Kind: exact
Token: --cds-space-16
Value: 16
Unit: px
Applies To: root

Id: max-width
Label: Maximum width
Kind: exact
Token: --cds-size-320
Value: 320
Unit: px
Applies To: root
Notes: The toast width is capped at this token, shrinking on narrow viewports.

Id: corner-radius
Label: Corner radius
Kind: exact
Token: --cds-radius-2xl
Value: 32
Unit: px
Applies To: root

Layout

Alignment: Leading icon, content column, and dismiss align to the top of the toast.
Flow: A three-column grid: optional icon, flexible content, optional dismiss.
Notes: Toast renders only the visual; a toast host owns the show and hide timer.

Typography And Color

Typography

Label: Title and body
Description: Title and body use the body-small ramp.
Token: --cds-type-body-small-size

Colors

Label: Info surface
Description: The info variant uses the raised surface.
Token: --cds-bg-surface

Label: Success surface
Description: The success variant uses the success subtle token.
Token: --cds-status-success-subtle

Label: Title text
Description: The title uses primary text.
Token: --cds-text-primary

Label: Body text
Description: The body uses secondary text.
Token: --cds-text-secondary

States

Id: info
Label: Info
Description: Neutral surface announced as status.

Id: success
Label: Success
Description: Success subtle surface.

Id: warning
Label: Warning
Description: Warning subtle surface.

Id: danger
Label: Danger
Description: Danger subtle surface announced as alert.

Id: dismissible
Label: Dismissible
Description: Shows the close button when onDismiss is provided.

Behavior

Label: Host-owned lifecycle
Description: Toast does not schedule its own dismissal; the host times it and passes onDismiss.

Label: Urgency
Description: danger uses role=alert; the other variants use role=status.

Accessibility

Label: Live region
Description: The variant maps to an appropriate status or alert live region.

Label: Dismiss label
Description: The close button carries an accessible label.

Content Adaptation

Label: Responsive width
Description: The toast caps at the max-width token and shrinks on narrow viewports.

Label: Optional slots
Description: Icon, action, and dismiss render only when supplied.

Motion Haptics

Motion

Label: Entrance
Description: The toast slides in from its anchored edge; disabled under reduced motion.

Haptics

Label: Dismiss haptic
Description: Dismissal requests a light haptic.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1