{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "toast", "name": "Toast", "category": "Overlays", "summary": "A transient feedback banner with variant color, viewport position, optional icon, action, and dismiss control.", "documentation": { "summary": "A transient feedback banner with variant color, viewport position, optional icon, action, and dismiss control.", "guidance": [ { "heading": "Overview", "body": "A compact, top-anchored feedback pill. Toast renders only the visual — a toast host owns the\nshow/hide timer. `tone` colors the leading icon disc and sets the ARIA urgency. `glyph` and\n`title` are required; `subtitle` is optional." }, { "heading": "Use when", "body": "App toasts today are share/copy confirmations whose `tone` is set at runtime." }, { "heading": "Icon", "body": "`glyph` is required and is not derived from `tone` — any DS glyph pairs with any tone." } ], "usage": [ { "variant": "neutral", "use": "A plain notice with no status color — a bold disc.", "axis": "Tone" }, { "variant": "info", "use": "A heads-up or neutral confirmation — copied to clipboard.", "axis": "Tone" }, { "variant": "success", "use": "A completed action — scan complete, saved.", "axis": "Tone" }, { "variant": "warning", "use": "Something needs attention.", "axis": "Tone" }, { "variant": "danger", "use": "A failure — could not save. Announced as role=\"alert\" so screen readers interrupt; the other tones use role=\"status\".", "avoid": "A routine confirmation — the alert role is disruptive when nothing is wrong.", "axis": "Tone" } ], "examples": [], "source": "packages/design-system/src/components/overlays/Toast/Toast.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." }, "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "code": "import React, { useEffect } from 'react';\nimport { cn } from '../../../utilities';\nimport { useHaptic } from '../../../hooks/useHaptic';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport type { StatusTone } from '../../../styles/statusTone';\nimport type { GlyphName } from '../../primitives/Glyph/Glyph';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { Text } from '../../primitives/Text/Text';\nimport styles from './Toast.module.scss';\n\n/**\n * Status tone driving the icon disc color and ARIA urgency.\n */\nexport type ToastTone = StatusTone;\n\n/**\n * Props for `Toast`. There is no placement prop — the pill lays out inline, so the host positions\n * it through `className` or `style`.\n */\nexport interface ToastProps {\n /** Semantic tone; colors the icon disc and sets `role=\"alert\"` for `danger`. */\n tone: ToastTone;\n /** Glyph inside the tone disc. The disc is `aria-hidden`, so it cannot carry what the title omits. */\n glyph: GlyphName;\n /** Primary line. Clipped to one line with an ellipsis, so keep it short. */\n title: string;\n /** Optional second line, clipped the same way. */\n subtitle?: string;\n /** Haptic fired once when the toast appears. Defaults to off. */\n haptic?: HapticFeedback;\n className?: string;\n style?: React.CSSProperties;\n /** Test selector for the root; the disc and the text nodes carry none. */\n testId?: string;\n}\n\n/**\n * A transient feedback pill. Toast renders only the visual — a host owns the show/hide timer.\n * `danger` announces as `role=\"alert\"`; every other tone as `role=\"status\"`.\n */\nexport function Toast({ tone, glyph, title, subtitle, haptic = false, className, style, testId }: ToastProps) {\n const fireHaptic = useHaptic('light');\n\n useEffect(() => {\n fireHaptic(haptic);\n // eslint-disable-next-line react-hooks/exhaustive-deps -- fire once when the toast appears\n }, []);\n\n return (\n \n \n \n \n {title}\n \n {subtitle && (\n \n {subtitle}\n \n )}\n \n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Toast", "status": "preview", "version": "1.0.0", "summary": "A transient feedback banner with variant color, viewport position, optional icon, action, and dismiss control." }, "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." } ], "allowedDesignChoices": { "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": [], "measurements": [ { "id": "content-gap", "label": "Content gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "root" ] }, { "id": "container-inset", "label": "Container inset", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "root" ] }, { "id": "max-width", "label": "Maximum width", "kind": "exact", "token": "--cds-size-320", "value": 320, "unit": "px", "appliesTo": [ "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", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [] }, "spec_source": "packages/design-system/src/components/overlays/Toast/Toast.spec.json", "guidance_source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec, UsageTable } from '../../../../.storybook/blocks';\nimport * as Stories from './Toast.stories';\nimport toastSpec from './Toast.spec.json';\n\n\n\n# Toast\n\nA compact, top-anchored feedback pill. Toast renders only the visual — a toast host owns the\nshow/hide timer. `tone` colors the leading icon disc and sets the ARIA urgency. `glyph` and\n`title` are required; `subtitle` is optional.\n\n\n\n## Use when\n\nApp toasts today are share/copy confirmations whose `tone` is set at runtime.\n\n\n\n## Tones\n\n\n\n## Title only\n\n\n\n## Icon\n\n`glyph` is required and is not derived from `tone` — any DS glyph pairs with any tone.\n\n\n\n## Dark theme\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "tone", "type": "\"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\"", "declared_type": "ToastTone", "required": true, "description": "Semantic tone; colors the icon disc and sets `role=\"alert\"` for `danger`.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 22 }, "values": [ "danger", "info", "neutral", "success", "warning" ], "values_complete": true }, { "name": "glyph", "type": "\"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\"", "declared_type": "GlyphName", "required": true, "description": "Glyph inside the tone disc. The disc is `aria-hidden`, so it cannot carry what the title omits.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 24 }, "values": [ "account", "add", "arrow-down", "arrow-left", "arrow-right", "arrow-up", "bell", "block", "call-guard", "call", "card", "caret-down", "caret-up", "cart", "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle-outline", "clear", "cloaked-ai", "cloaked-pay", "clock", "close", "collapse", "copy", "dark-web-monitoring", "data-removal", "dot", "dropdown-collapse", "dropdown-expand", "email-guard", "email", "expand", "family", "filter", "guard", "home", "info", "lock", "log", "mail", "menu", "message", "missed", "number", "password", "phone", "scan", "search", "send", "settings", "share", "sim", "sms-guard", "sms", "timer", "trash", "trend-down", "trend-up", "upload", "user", "voicemail", "vpn", "wifi" ], "values_complete": true }, { "name": "title", "type": "string", "declared_type": "string", "required": true, "description": "Primary line. Clipped to one line with an ellipsis, so keep it short.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 26 } }, { "name": "subtitle", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional second line, clipped the same way.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 28 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic fired once when the toast appears. Defaults to off.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 30 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "false", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 31 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 32 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Test selector for the root; the disc and the text nodes carry none.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 34 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-size-320", "light": "320px", "dark": "320px" }, { "name": "--cds-radius-2xl", "light": "32px", "dark": "32px" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" }, { "name": "--cds-status-success-subtle", "light": "#0089241a", "dark": "#0089241a" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-overlays-toast--playground", "name": "Playground", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Playground", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--playground&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--title-only", "name": "Title Only", "title": "Cloaked Design System/Overlays/Toast", "exportName": "TitleOnly", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--title-only&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--info", "name": "Info", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Info", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--info&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--danger", "name": "Danger", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Danger", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--danger&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--custom-icon", "name": "Custom Icon", "title": "Cloaked Design System/Overlays/Toast", "exportName": "CustomIcon", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--custom-icon&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--tone-matrix", "name": "Tone Matrix", "title": "Cloaked Design System/Overlays/Toast", "exportName": "ToneMatrix", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--tone-matrix&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Overlays/Toast", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--dark-theme&viewMode=story" } ], "name": "Toast", "id": "toast", "category": "Overlays" }, "stories": [ { "id": "cloaked-design-system-overlays-toast--playground", "name": "Playground", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Playground", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--playground&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--title-only", "name": "Title Only", "title": "Cloaked Design System/Overlays/Toast", "exportName": "TitleOnly", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--title-only&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--info", "name": "Info", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Info", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--info&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--danger", "name": "Danger", "title": "Cloaked Design System/Overlays/Toast", "exportName": "Danger", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--danger&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--custom-icon", "name": "Custom Icon", "title": "Cloaked Design System/Overlays/Toast", "exportName": "CustomIcon", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--custom-icon&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--tone-matrix", "name": "Tone Matrix", "title": "Cloaked Design System/Overlays/Toast", "exportName": "ToneMatrix", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--tone-matrix&viewMode=story" }, { "id": "cloaked-design-system-overlays-toast--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Overlays/Toast", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "source_digest": "6e6a983755849a9808a0e851fe04772c8ffac914e9b4eb7717f21672c3dcdf8d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-overlays-toast--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { STATUS_TONES } from '../../../styles/statusTone';\nimport { hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport { Toast } from './Toast';\n\nconst TONE_GLYPH = {\n neutral: 'bell',\n info: 'info',\n success: 'check',\n warning: 'info',\n danger: 'block',\n} as const;\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Overlays/Toast',\n component: Toast,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A compact, top-anchored feedback pill. Toast renders only the visual — a host owns the ' +\n 'show/hide timer. `tone` colors the leading icon disc and sets the ARIA urgency: `danger` uses ' +\n '`role=\"alert\"`, every other tone `role=\"status\"`. `glyph` and `title` are required; `subtitle` ' +\n 'is optional.',\n },\n },\n },\n args: {\n tone: 'success',\n glyph: 'check',\n title: 'Done',\n subtitle: 'Confirmed',\n },\n argTypes: {\n tone: {\n ...selectArgType(STATUS_TONES),\n description: 'Colors the icon disc and sets ARIA urgency. `danger` announces as `role=\"alert\"`.',\n },\n glyph: { control: 'text', description: 'Registered glyph shown in the tone disc.' },\n title: { control: 'text', description: 'Primary message.' },\n subtitle: { control: 'text', description: 'Optional secondary line under the title.' },\n haptic: hapticArgType,\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const TitleOnly: Story = {\n args: { tone: 'success', glyph: 'check', title: 'Link copied', subtitle: undefined },\n parameters: { docs: { description: { story: 'Without a `subtitle` the pill is a single centered line.' } } },\n};\n\nexport const Info: Story = {\n args: { tone: 'info', glyph: 'info', title: 'Heads up', subtitle: 'Review one item to continue.' },\n};\n\nexport const Danger: Story = {\n args: { tone: 'danger', glyph: 'block', title: 'Could not save', subtitle: 'Check your connection.' },\n};\n\nexport const CustomIcon: Story = {\n args: { tone: 'success', glyph: 'lock', title: 'File unlocked', subtitle: undefined },\n parameters: {\n docs: { description: { story: 'The glyph is not derived from tone — any DS glyph works with any tone.' } },\n },\n};\n\nexport const ToneMatrix: Story = {\n parameters: { docs: { description: { story: 'Every tone treatment side by side.' } } },\n render: () => (\n \n {STATUS_TONES.map(tone => (\n \n ))}\n \n ),\n};\n\nexport const DarkTheme: Story = {\n args: { tone: 'success', glyph: 'check', title: 'Done', subtitle: 'Confirmed' },\n globals: { theme: 'dark' },\n};\n" }, "links": { "human": "/component-toast", "json": "/data/components/toast.json", "markdown": "/data/components/toast.md", "storybook": "/storybook/?path=/story/cloaked-design-system-overlays-toast--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Toast", "public_path": "Toast", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Toast", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 41 }, "props_type": "ToastProps", "props": [ { "name": "tone", "type": "\"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\"", "declared_type": "ToastTone", "required": true, "description": "Semantic tone; colors the icon disc and sets `role=\"alert\"` for `danger`.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 22 }, "values": [ "danger", "info", "neutral", "success", "warning" ], "values_complete": true }, { "name": "glyph", "type": "\"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\"", "declared_type": "GlyphName", "required": true, "description": "Glyph inside the tone disc. The disc is `aria-hidden`, so it cannot carry what the title omits.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 24 }, "values": [ "account", "add", "arrow-down", "arrow-left", "arrow-right", "arrow-up", "bell", "block", "call-guard", "call", "card", "caret-down", "caret-up", "cart", "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle-outline", "clear", "cloaked-ai", "cloaked-pay", "clock", "close", "collapse", "copy", "dark-web-monitoring", "data-removal", "dot", "dropdown-collapse", "dropdown-expand", "email-guard", "email", "expand", "family", "filter", "guard", "home", "info", "lock", "log", "mail", "menu", "message", "missed", "number", "password", "phone", "scan", "search", "send", "settings", "share", "sim", "sms-guard", "sms", "timer", "trash", "trend-down", "trend-up", "upload", "user", "voicemail", "vpn", "wifi" ], "values_complete": true }, { "name": "title", "type": "string", "declared_type": "string", "required": true, "description": "Primary line. Clipped to one line with an ellipsis, so keep it short.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 26 } }, { "name": "subtitle", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional second line, clipped the same way.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 28 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic fired once when the toast appears. Defaults to off.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 30 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "false", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 31 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 32 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Test selector for the root; the disc and the text nodes carry none.", "source": { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 34 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 14, "name": "ToastTone", "code": "export type ToastTone = StatusTone;" }, { "path": "packages/design-system/src/components/overlays/Toast/Toast.tsx", "line": 20, "name": "ToastProps", "code": "export interface ToastProps {\n /** Semantic tone; colors the icon disc and sets `role=\"alert\"` for `danger`. */\n tone: ToastTone;\n /** Glyph inside the tone disc. The disc is `aria-hidden`, so it cannot carry what the title omits. */\n glyph: GlyphName;\n /** Primary line. Clipped to one line with an ellipsis, so keep it short. */\n title: string;\n /** Optional second line, clipped the same way. */\n subtitle?: string;\n /** Haptic fired once when the toast appears. Defaults to off. */\n haptic?: HapticFeedback;\n className?: string;\n style?: React.CSSProperties;\n /** Test selector for the root; the disc and the text nodes carry none. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/styles/statusTone.ts", "line": 7, "name": "STATUS_TONES", "code": "STATUS_TONES = ['neutral', 'info', 'success', 'warning', 'danger'] as const" }, { "path": "packages/design-system/src/styles/statusTone.ts", "line": 9, "name": "StatusTone", "code": "export type StatusTone = (typeof STATUS_TONES)[number];" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" }, { "path": "packages/design-system/src/types/GlyphName.ts", "line": 10, "name": "GLYPH_NAMES", "code": "GLYPH_NAMES = [\n // Action\n 'arrow-left',\n 'arrow-right',\n 'arrow-up',\n 'arrow-down',\n 'chevron-down',\n 'chevron-up',\n 'chevron-left',\n 'chevron-right',\n 'caret-down',\n 'caret-up',\n // Trend lines, for a change in a figure over time. Distinct from the arrows and carets above,\n // which point at a direction without implying a measurement moved.\n 'trend-up',\n 'trend-down',\n 'collapse',\n 'expand',\n 'dropdown-collapse',\n 'dropdown-expand',\n 'close',\n 'clear',\n 'menu',\n 'copy',\n 'search',\n 'add',\n // Renders the `send` drawing; a separate name for share-sheet actions.\n 'share',\n // System\n 'phone',\n 'sim',\n 'account',\n 'family',\n 'home',\n 'wifi',\n 'cart',\n 'vpn',\n 'lock',\n 'block',\n 'timer',\n 'check',\n 'send',\n 'info',\n 'number',\n 'filter',\n 'scan',\n 'log',\n 'trash',\n // Inbox\n 'missed',\n 'call',\n 'voicemail',\n 'sms',\n 'email',\n // Feature\n 'data-removal',\n 'dark-web-monitoring',\n 'cloaked-pay',\n 'cloaked-ai',\n 'sms-guard',\n 'email-guard',\n 'call-guard',\n 'card',\n 'password',\n 'guard',\n // Legacy aliases (kept for back-compat; render the Figma glyph)\n 'bell',\n 'circle-outline',\n 'dot',\n 'settings',\n 'clock',\n 'mail',\n 'message',\n 'user',\n 'upload',\n] as const" }, { "path": "packages/design-system/src/types/GlyphName.ts", "line": 87, "name": "GlyphName", "code": "export type GlyphName = (typeof GLYPH_NAMES)[number];" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." } }