Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Toast docs page and block examples (#1571)

Kenton Quatmanc06963f0be4a
diff --git a/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjs
new file mode 100644
index 0000000000..fcf7ae4ebe
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toast — Action',
+ description: 'Persistent toasts with a trailing button or link so the user can act on the notification, like undoing a delete or viewing a report.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toast', 'Button', 'Link', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastAction.tsx b/packages/cli/templates/blocks/components/Toast/ToastAction.tsx
new file mode 100644
index 0000000000..2bb456af44
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toast/ToastAction.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+import {useXDSToast} from '@xds/core/Toast';
+import {XDSButton} from '@xds/core/Button';
+import {XDSLink} from '@xds/core/Link';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ToastAction() {
+ const toast = useXDSToast();
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Trailing actions for undo or navigation
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSButton
+ label="Delete with undo"
+ variant="secondary"
+ onClick={() =>
+ toast({
+ body: 'Item deleted',
+ isAutoHide: false,
+ endContent: (
+ <XDSButton
+ label="Undo"
+ variant="secondary"
+ size="sm"
+ onClick={() => {}}
+ />
+ ),
+ })
+ }
+ />
+ <XDSButton
+ label="Report ready"
+ variant="secondary"
+ onClick={() =>
+ toast({
+ body: 'Your report is ready.',
+ isAutoHide: false,
+ endContent: (
+ <XDSLink href="#" label="View report" hasUnderline>
+ View report
+ </XDSLink>
+ ),
+ })
+ }
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs
index 905ab213d1..a58994bc2d 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Toast — Deduplication',
- description:
- 'Prevent duplicate toasts with uniqueID, using ignore or overwrite collision strategies.',
+ description: 'Prevent duplicate toasts with uniqueID. Use ignore to keep the first toast, or overwrite to replace it with updated content like a progress percentage.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toast', 'Button', 'Stack'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx
index a8c386c801..d6f4f0f13f 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx
+++ b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx
@@ -2,35 +2,43 @@
import {useXDSToast} from '@xds/core/Toast';
import {XDSButton} from '@xds/core/Button';
-import {XDSStack} from '@xds/core/Stack';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function ToastDeduplication() {
const toast = useXDSToast();
+
return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSButton
- label="Offline (ignore)"
- onClick={() =>
- toast({
- body: 'You are offline',
- uniqueID: 'offline',
- collisionBehavior: 'ignore',
- isAutoHide: false,
- })
- }
- />
- <XDSButton
- label="Progress (overwrite)"
- variant="secondary"
- onClick={() =>
- toast({
- body: `Uploading... ${Math.floor(Math.random() * 100)}%`,
- uniqueID: 'upload-progress',
- collisionBehavior: 'overwrite',
- isAutoHide: false,
- })
- }
- />
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Ignore keeps the first toast; overwrite replaces it
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSButton
+ label="Offline (ignore)"
+ variant="secondary"
+ onClick={() =>
+ toast({
+ body: 'You are offline',
+ uniqueID: 'offline',
+ collisionBehavior: 'ignore',
+ isAutoHide: false,
+ })
+ }
+ />
+ <XDSButton
+ label="Progress (overwrite)"
+ variant="secondary"
+ onClick={() =>
+ toast({
+ body: `Uploading\u2026 ${Math.floor(Math.random() * 100)}%`,
+ uniqueID: 'upload-progress',
+ collisionBehavior: 'overwrite',
+ isAutoHide: false,
+ })
+ }
+ />
+ </XDSStack>
</XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjs
new file mode 100644
index 0000000000..c938dd29a4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toast — Dismiss',
+ description: 'Show a persistent toast and dismiss it programmatically using the function returned by useXDSToast. Use for long-running operations that need manual cleanup.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsx b/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsx
new file mode 100644
index 0000000000..3859ff7f48
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import {useRef} from 'react';
+import {useXDSToast} from '@xds/core/Toast';
+import {XDSButton} from '@xds/core/Button';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ToastDismiss() {
+ const toast = useXDSToast();
+ const dismissRef = useRef<(() => void) | null>(null);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Show a persistent toast, then dismiss it from code
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSButton
+ label="Show persistent toast"
+ variant="secondary"
+ onClick={() => {
+ dismissRef.current = toast({
+ body: 'Uploading file\u2026',
+ isAutoHide: false,
+ });
+ }}
+ />
+ <XDSButton
+ label="Dismiss"
+ variant="ghost"
+ onClick={() => {
+ dismissRef.current?.();
+ dismissRef.current = null;
+ }}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjs
deleted file mode 100644
index 982d5cb08a..0000000000
--- a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toast — Programmatic Dismiss',
- description:
- 'Show a persistent toast and dismiss it programmatically using the returned dismiss function.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toast', 'Button', 'Stack'],
-};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsx b/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsx
deleted file mode 100644
index 9edf3b71e0..0000000000
--- a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-'use client';
-
-import {useRef} from 'react';
-import {useXDSToast} from '@xds/core/Toast';
-import {XDSButton} from '@xds/core/Button';
-import {XDSStack} from '@xds/core/Stack';
-
-export default function ToastProgrammaticDismiss() {
- const toast = useXDSToast();
- const dismissRef = useRef<(() => void) | null>(null);
-
- return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSButton
- label="Show persistent toast"
- onClick={() => {
- dismissRef.current = toast({
- body: 'Uploading...',
- isAutoHide: false,
- });
- }}
- />
- <XDSButton
- label="Dismiss"
- variant="secondary"
- onClick={() => {
- dismissRef.current?.();
- dismissRef.current = null;
- }}
- />
- </XDSStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
index 9b1644bae3..ff8b471aeb 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'Toast',
isReady: true,
- aspectRatio: 1,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs
index c16a993520..e6dfdacaad 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Toast — Stacking',
- description:
- 'Multiple toasts stacking vertically, alternating between info and error types.',
+ description: 'Multiple toasts stacking vertically with smooth enter and exit animations. Click repeatedly to see how toasts queue and dismiss.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toast', 'Button'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx b/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx
index ca46b432c8..b5e7abf934 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx
+++ b/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx
@@ -3,23 +3,33 @@
import {useRef} from 'react';
import {useXDSToast} from '@xds/core/Toast';
import {XDSButton} from '@xds/core/Button';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const MESSAGES = [
+ {body: 'Changes saved.', type: 'info' as const},
+ {body: 'Failed to upload file.', type: 'error' as const},
+ {body: 'Message sent to Sarah Chen.', type: 'info' as const},
+ {body: 'Connection lost.', type: 'error' as const},
+];
export default function ToastStacking() {
const toast = useXDSToast();
const countRef = useRef(0);
return (
- <XDSButton
- label="Add toast"
- onClick={() => {
- countRef.current++;
- const types = ['info', 'error'] as const;
- const type = types[countRef.current % types.length];
- toast({
- body: `Toast #${countRef.current} — ${type} notification.`,
- type,
- });
- }}
- />
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Click multiple times to see stacking behavior
+ </XDSText>
+ <XDSButton
+ label="Add toast"
+ onClick={() => {
+ const msg = MESSAGES[countRef.current % MESSAGES.length];
+ countRef.current++;
+ toast(msg);
+ }}
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs
index 31e62da0f6..71c3587ed0 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Toast — Types',
- description:
- 'Info and error toast variants. Error toasts persist until dismissed.',
+ description: 'Info and error toast variants side by side. Info toasts auto-dismiss after 5 seconds, error toasts persist until the user dismisses them.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toast', 'Button', 'Stack'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx b/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx
index 8f25471a35..eaf843262e 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx
+++ b/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx
@@ -2,26 +2,33 @@
import {useXDSToast} from '@xds/core/Toast';
import {XDSButton} from '@xds/core/Button';
-import {XDSStack} from '@xds/core/Stack';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function ToastTypes() {
const toast = useXDSToast();
+
return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSButton
- label="Info"
- variant="secondary"
- onClick={() =>
- toast({body: 'This is an info notification.', type: 'info'})
- }
- />
- <XDSButton
- label="Error"
- variant="destructive"
- onClick={() =>
- toast({body: 'This is an error notification.', type: 'error'})
- }
- />
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Click each button to see the toast variant
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSButton
+ label="Info toast"
+ variant="secondary"
+ onClick={() =>
+ toast({body: 'Changes saved successfully.', type: 'info'})
+ }
+ />
+ <XDSButton
+ label="Error toast"
+ variant="destructive"
+ onClick={() =>
+ toast({body: 'Failed to save changes.', type: 'error'})
+ }
+ />
+ </XDSStack>
</XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjs
deleted file mode 100644
index 266ff8b6aa..0000000000
--- a/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toast — With Action',
- description:
- 'Persistent toasts with trailing actions using a button or a link.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toast', 'Button', 'Link', 'Stack'],
-};
diff --git a/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsx b/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsx
deleted file mode 100644
index a357affd16..0000000000
--- a/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-'use client';
-
-import {useXDSToast} from '@xds/core/Toast';
-import {XDSButton} from '@xds/core/Button';
-import {XDSLink} from '@xds/core/Link';
-import {XDSStack} from '@xds/core/Stack';
-
-export default function ToastWithAction() {
- const toast = useXDSToast();
- return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSButton
- label="With button"
- onClick={() =>
- toast({
- body: 'Item deleted',
- isAutoHide: false,
- endContent: (
- <XDSButton
- label="Undo"
- variant="secondary"
- size="sm"
- onClick={() => {}}
- />
- ),
- })
- }
- />
- <XDSButton
- label="With link"
- variant="secondary"
- onClick={() =>
- toast({
- body: 'Your report is ready.',
- isAutoHide: false,
- endContent: (
- <XDSLink href="#" label="View report" hasUnderline>
- View report
- </XDSLink>
- ),
- })
- }
- />
- </XDSStack>
- );
-}
diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs
index a49c4b5c0b..f5896018a2 100644
--- a/packages/core/src/Toast/Toast.doc.mjs
+++ b/packages/core/src/Toast/Toast.doc.mjs
@@ -57,12 +57,20 @@ export const docs = {
usage: {
description:
- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ 'Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.',
bestPractices: [
- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
+ {guidance: true, description: 'Keep messages short - only a few words that tell the user what happened, like "Changes saved" or "Message sent".'},
+ {guidance: true, description: 'Add an undo action in the endContent slot for reversible operations like deleting an item, so the user can recover without navigating away.'},
+ {guidance: true, description: 'Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.'},
+ {guidance: true, description: 'Use error type for failures that need attention but not immediate action — it persists until dismissed so the user won\'t miss it.'},
+ {guidance: false, description: 'Don\'t use a toast for critical errors that block the user — use Banner for persistent, in-context messaging that requires acknowledgment.'},
+ {guidance: false, description: 'Don\'t put long or multi-line content in a toast — it disappears after 5 seconds and the user may not finish reading.'},
+ {guidance: false, description: 'Don\'t show form validation errors as toasts — use inline field validation so the user can see exactly which field needs fixing.'},
+ ],
+ anatomy: [
+ {name: 'Body', required: true, description: 'The primary message text describing what happened or what the user should know.'},
+ {name: 'End content', required: false, description: 'A trailing action like an Undo button or a link, placed after the body text.'},
+ {name: 'Dismiss button', required: true, description: 'A close button that lets the user manually dismiss the toast before auto-hide.'},
],
},
};
@@ -87,12 +95,20 @@ export const docsZh = {
},
usage: {
description:
- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ 'Toast 显示简短的非阻塞通知,用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景,如保存、删除或状态变更。',
bestPractices: [
- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
+ {guidance: true, description: '保持消息简短——只需几个词告诉用户发生了什么,如"更改已保存"或"消息已发送"。'},
+ {guidance: true, description: '在 endContent 插槽中添加撤销操作,用于可逆操作如删除项目,让用户无需导航即可恢复。'},
+ {guidance: true, description: '使用 uniqueID 去重重复操作触发的 toast,如多次点击保存按钮。'},
+ {guidance: true, description: '对需要关注但不需要立即操作的错误使用 error 类型——它会持续显示直到关闭。'},
+ {guidance: false, description: '不要对阻塞用户的严重错误使用 toast——使用 Banner 进行持久的上下文消息传递。'},
+ {guidance: false, description: '不要在 toast 中放置长内容或多行内容——它会在5秒后消失,用户可能来不及阅读。'},
+ {guidance: false, description: '不要将表单验证错误显示为 toast——使用内联字段验证让用户看到具体哪个字段需要修复。'},
+ ],
+ anatomy: [
+ {name: '正文', required: true, description: '描述发生了什么或用户应该知道什么的主要消息文本。'},
+ {name: '尾部内容', required: false, description: '正文后的尾随操作,如撤销按钮或链接。'},
+ {name: '关闭按钮', required: true, description: '让用户在自动隐藏前手动关闭 toast 的关闭按钮。'},
],
},
};
@@ -103,12 +119,15 @@ export const docsDense = {
'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; XDSMediaTheme inverted surface',
usage: {
description:
- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ 'Brief non-blocking notification for action confirmations and temporary info. Use where user needs feedback not decisions — saves, deletes, status changes.',
bestPractices: [
- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
+ {guidance: true, description: 'Short messages — a few words: "Changes saved", "Message sent".'},
+ {guidance: true, description: 'Undo action in endContent for reversible ops like deletes.'},
+ {guidance: true, description: 'uniqueID to dedup repeated action toasts.'},
+ {guidance: true, description: 'Error type for failures needing attention — persists until dismissed.'},
+ {guidance: false, description: 'Don\'t use for critical blocking errors — use Banner for persistent in-context messaging.'},
+ {guidance: false, description: 'Don\'t put long/multi-line content — disappears in 5s, user may not finish reading.'},
+ {guidance: false, description: 'Don\'t show form validation errors — use inline field validation instead.'},
],
},
propDescriptions: {