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.mjsindex 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.tsxindex 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" />}isDismissabledefaultIsExpanded>- <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.mjsindex 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.tsxindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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: {