Skip to content

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

TypeScript

Improve Banner docs page and block examples (#1552)

rubyycheung5a50e1f5c1a2
diff --git a/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs
index 4aad93e122..be842c3ff4 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Banner — Collapsible Content',
- description: 'Banner with an expandable content area, action button, and dismiss control.',
+ name: 'Banner — Collapsible',
+ description: 'Combine an action button, dismiss control, and expandable detail area in one banner. Use for complex notifications like config changes or deployment summaries.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner', 'Button'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Banner', 'Button', 'List', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.tsx b/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.tsx
index 4ceefec5bf..895a097769 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.tsx
+++ b/packages/cli/templates/blocks/components/Banner/BannerCollapsibleContent.tsx
@@ -2,6 +2,9 @@
import {XDSBanner} from '@xds/core/Banner';
import {XDSButton} from '@xds/core/Button';
+import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
export default function BannerCollapsibleContent() {
return (
@@ -12,13 +15,15 @@ export default function BannerCollapsibleContent() {
endContent={<XDSButton label="Review" variant="secondary" size="sm" />}
isDismissable
defaultIsExpanded>
- <div style={{fontSize: 13}}>
- <p style={{margin: '0 0 8px'}}>Changed settings:</p>
- <ul style={{margin: 0, paddingInlineStart: 20}}>
- <li>Authentication method updated</li>
- <li>Rate limits modified</li>
- </ul>
- </div>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Changed settings:
+ </XDSText>
+ <XDSList density="compact">
+ <XDSListItem label="Authentication method updated" />
+ <XDSListItem label="Rate limits modified" />
+ </XDSList>
+ </XDSStack>
</XDSBanner>
);
}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerDismissable.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerDismissable.doc.mjs
index 4191b4e729..0e8e553792 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerDismissable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Banner/BannerDismissable.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Banner — Dismissable Warning',
- description: 'Warning banner that can be dismissed by the user.',
+ name: 'Banner — Dismiss',
+ description: 'Let the user close a banner after reading it. Use for maintenance notices, feature tips, or any non-critical message the user can acknowledge.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Banner', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerDismissable.tsx b/packages/cli/templates/blocks/components/Banner/BannerDismissable.tsx
index 83ae282754..a75b2003ec 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerDismissable.tsx
+++ b/packages/cli/templates/blocks/components/Banner/BannerDismissable.tsx
@@ -1,14 +1,29 @@
'use client';
import {XDSBanner} from '@xds/core/Banner';
+import {XDSStack} from '@xds/core/Layout';
export default function BannerDismissable() {
return (
- <XDSBanner
- status="warning"
- title="Your session will expire soon."
- description="Please save your work to avoid losing changes."
- isDismissable
- />
+ <XDSStack direction="vertical" gap={3}>
+ <XDSBanner
+ status="success"
+ title="Deployment complete"
+ description="Version 3.2.0 is now live in production."
+ isDismissable
+ />
+ <XDSBanner
+ status="warning"
+ title="Scheduled maintenance tonight"
+ description="The system will be briefly unavailable from 2:00–3:00 AM."
+ isDismissable
+ />
+ <XDSBanner
+ status="info"
+ title="New feature available"
+ description="Try the new dashboard layout in Settings."
+ isDismissable
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerErrorList.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerErrorList.doc.mjs
deleted file mode 100644
index 5f09b08ad6..0000000000
--- a/packages/cli/templates/blocks/components/Banner/BannerErrorList.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Banner — Error List',
- description: 'Error banner with an expanded content area listing validation errors.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner'],
-};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerErrorList.tsx b/packages/cli/templates/blocks/components/Banner/BannerErrorList.tsx
deleted file mode 100644
index f8a45527cb..0000000000
--- a/packages/cli/templates/blocks/components/Banner/BannerErrorList.tsx
+++ /dev/null
@@ -1,19 +0,0 @@
-'use client';
-
-import {XDSBanner} from '@xds/core/Banner';
-
-export default function BannerErrorList() {
- return (
- <XDSBanner
- status="error"
- title="Multiple errors found"
- description="The following issues need to be resolved:"
- defaultIsExpanded>
- <ul style={{margin: 0, paddingInlineStart: 20, fontSize: 13}}>
- <li>Email address is invalid</li>
- <li>Password must be at least 8 characters</li>
- <li>Username is already taken</li>
- </ul>
- </XDSBanner>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.doc.mjs
index aed935e904..55d0092014 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.doc.mjs
+++ b/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Banner — Section Container',
- description: 'Full-width section banner with no border-radius for page-level notifications.',
+ name: 'Banner — Full Width',
+ description: 'A full-width banner with no border radius for page-level notifications. Use at the top of a page for site-wide announcements or maintenance alerts.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Banner', 'Button', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.tsx b/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.tsx
index 324d370452..b934c988eb 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.tsx
+++ b/packages/cli/templates/blocks/components/Banner/BannerSectionVariant.tsx
@@ -1,14 +1,28 @@
'use client';
import {XDSBanner} from '@xds/core/Banner';
+import {XDSButton} from '@xds/core/Button';
+import {XDSStack} from '@xds/core/Layout';
export default function BannerSectionVariant() {
return (
- <XDSBanner
- status="info"
- title="System maintenance scheduled"
- description="The system will be undergoing maintenance on Saturday from 2:00 AM to 6:00 AM UTC."
- container="section"
- />
+ <XDSStack direction="vertical" gap={3}>
+ <XDSBanner
+ status="warning"
+ title="Scheduled downtime"
+ description="All services will be unavailable on Sunday from 2:00–4:00 AM."
+ container="section"
+ isDismissable
+ />
+ <XDSBanner
+ status="info"
+ title="Welcome to the new dashboard"
+ description="We have redesigned the layout based on your feedback."
+ container="section"
+ endContent={
+ <XDSButton label="Take a tour" variant="secondary" size="sm" />
+ }
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerStatuses.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerStatuses.doc.mjs
new file mode 100644
index 0000000000..9b7598028f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Banner/BannerStatuses.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Banner — Statuses',
+ description: 'All 4 banner statuses: info, success, warning, and error. Use to show persistent messages like updates, confirmations, cautions, or problems at the top of a page or section.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Banner', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerStatuses.tsx b/packages/cli/templates/blocks/components/Banner/BannerStatuses.tsx
new file mode 100644
index 0000000000..3d41979e20
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Banner/BannerStatuses.tsx
@@ -0,0 +1,31 @@
+'use client';
+
+import {XDSBanner} from '@xds/core/Banner';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function BannerStatuses() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSBanner
+ status="info"
+ title="A new software update is available"
+ description="Version 2.4.1 includes performance improvements and bug fixes."
+ />
+ <XDSBanner
+ status="success"
+ title="Changes saved"
+ description="Your profile information has been updated successfully."
+ />
+ <XDSBanner
+ status="warning"
+ title="Storage almost full"
+ description="You have used 90% of your available storage."
+ />
+ <XDSBanner
+ status="error"
+ title="Build failed"
+ description="3 tests did not pass. Check the logs for details."
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.doc.mjs
index 3c54a1ba1e..1eea363628 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.doc.mjs
+++ b/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Banner — With Action Button',
- description: 'Banner with a call-to-action button in the end slot.',
+ name: 'Banner — Action',
+ description: 'Add a button to a banner so the user can act on the message. Use for trial expirations, payment failures, or anything that needs a response.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner', 'Button'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Banner', 'Button', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.tsx b/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.tsx
index 47de1df585..8844588452 100644
--- a/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.tsx
+++ b/packages/cli/templates/blocks/components/Banner/BannerWithActionButton.tsx
@@ -2,14 +2,31 @@
import {XDSBanner} from '@xds/core/Banner';
import {XDSButton} from '@xds/core/Button';
+import {XDSStack} from '@xds/core/Layout';
export default function BannerWithActionButton() {
return (
- <XDSBanner
- status="info"
- title="New update available"
- description="Version 2.0 is ready to install."
- endContent={<XDSButton label="Update now" variant="primary" size="sm" />}
- />
+ <XDSStack direction="vertical" gap={3}>
+ <XDSBanner
+ status="info"
+ title="Your trial expires in 3 days"
+ description="Upgrade now to keep access to all features."
+ endContent={<XDSButton label="Upgrade" variant="secondary" size="sm" />}
+ />
+ <XDSBanner
+ status="warning"
+ title="API key expires soon"
+ description="Generate a new key before December 1 to avoid service interruption."
+ endContent={
+ <XDSButton label="Renew key" variant="secondary" size="sm" />
+ }
+ />
+ <XDSBanner
+ status="error"
+ title="Payment failed"
+ description="We could not process your last payment."
+ endContent={<XDSButton label="Retry" variant="secondary" size="sm" />}
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Banner/BannerWithDescription.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerWithDescription.doc.mjs
deleted file mode 100644
index 0108bcd60a..0000000000
--- a/packages/cli/templates/blocks/components/Banner/BannerWithDescription.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Banner — With Description',
- description: 'Info banner with a title and extended description text.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Banner'],
-};
diff --git a/packages/cli/templates/blocks/components/Banner/BannerWithDescription.tsx b/packages/cli/templates/blocks/components/Banner/BannerWithDescription.tsx
deleted file mode 100644
index 76b96850c1..0000000000
--- a/packages/cli/templates/blocks/components/Banner/BannerWithDescription.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-'use client';
-
-import {XDSBanner} from '@xds/core/Banner';
-
-export default function BannerWithDescription() {
- return (
- <XDSBanner
- status="info"
- title="New update available"
- description="A new version of the application is available. Update now to get the latest features and improvements."
- />
- );
-}
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 3d8e7eb9ad..381ccb840f 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -5,21 +5,22 @@ export const docs = {
keywords: ["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],
usage: {
description:
- 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ 'Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.',
bestPractices: [
- {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
- {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
- {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
- {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
+ {guidance: true, description: 'Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations.'},
+ {guidance: true, description: 'Use the card container inside page content and the section container for full-width messages that span the entire page.'},
+ {guidance: true, description: 'Make info and success banners dismissable. Keep error banners visible until the user fixes the issue.'},
+ {guidance: true, description: 'Keep titles short and scannable — "Payment failed" not "There was a problem processing your most recent payment."'},
+ {guidance: false, description: 'Use Banner for short-lived messages that disappear on their own — use Toast instead.'},
+ {guidance: false, description: 'Stack multiple banners with the same status — combine related messages into one banner.'},
],
anatomy: [
- {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
- {name: 'Heading', required: false, description: 'Required if no description is provided.'},
- {name: 'Description', required: false, description: 'Required if no heading is provided.'},
- {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
- {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
- {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
- {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
+ {name: 'Icon', required: true, description: 'Automatically set based on the status (info, warning, error, success).'},
+ {name: 'Title', required: false, description: 'The main message. Required if no description is provided.'},
+ {name: 'Description', required: false, description: 'Additional detail below the title. Required if no title is provided.'},
+ {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
+ {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
+ {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
],
},
@@ -104,21 +105,22 @@ export const docsZh = {
name: 'Banner',
usage: {
description:
- 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ 'Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.',
bestPractices: [
- {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
- {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
- {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
- {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
+ {guidance: true, description: 'Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations.'},
+ {guidance: true, description: 'Use the card container inside page content and the section container for full-width messages that span the entire page.'},
+ {guidance: true, description: 'Make info and success banners dismissable. Keep error banners visible until the user fixes the issue.'},
+ {guidance: true, description: 'Keep titles short and scannable — "Payment failed" not "There was a problem processing your most recent payment."'},
+ {guidance: false, description: 'Use Banner for short-lived messages that disappear on their own — use Toast instead.'},
+ {guidance: false, description: 'Stack multiple banners with the same status — combine related messages into one banner.'},
],
anatomy: [
- {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
- {name: 'Heading', required: false, description: 'Required if no description is provided.'},
- {name: 'Description', required: false, description: 'Required if no heading is provided.'},
- {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
- {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
- {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
- {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
+ {name: 'Icon', required: true, description: 'Automatically set based on the status (info, warning, error, success).'},
+ {name: 'Title', required: false, description: 'The main message. Required if no description is provided.'},
+ {name: 'Description', required: false, description: 'Additional detail below the title. Required if no title is provided.'},
+ {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
+ {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
+ {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
],
},
props: [
@@ -165,24 +167,25 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'persistent status notification for info, warning, error, success messages',
+ description: 'persistent message for errors, updates, warnings, or confirmations',
usage: {
description:
- 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ 'Banner shows a persistent message at the top of a page or section. Use for form errors, system updates, maintenance notices, or success confirmations.',
bestPractices: [
- {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
- {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
- {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
- {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
+ {guidance: true, description: 'Match status to message: info for updates, warning for caution, error for problems, success for confirmations.'},
+ {guidance: true, description: 'Card container for inline content, section container for full-width page-level messages.'},
+ {guidance: true, description: 'Make info/success dismissable. Keep error banners until the issue is fixed.'},
+ {guidance: true, description: 'Keep titles short — "Payment failed" not "There was a problem processing your payment."'},
+ {guidance: false, description: 'Use for auto-dismissing messages — use Toast instead.'},
+ {guidance: false, description: 'Stack multiple banners of the same status — combine into one.'},
],
anatomy: [
- {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
- {name: 'Heading', required: false, description: 'Required if no description is provided.'},
- {name: 'Description', required: false, description: 'Required if no heading is provided.'},
- {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
- {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
- {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
- {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
+ {name: 'Icon', required: true, description: 'Set automatically from status.'},
+ {name: 'Title', required: false, description: 'Main message text.'},
+ {name: 'Description', required: false, description: 'Detail below title.'},
+ {name: 'Action button', required: false, description: 'CTA like Review or Retry.'},
+ {name: 'Dismiss button', required: false, description: 'Close button via isDismissable.'},
+ {name: 'Collapsible content', required: false, description: 'Expandable detail area.'},
],
},
propDescriptions: {