An open source design system that's fully customizable and agent ready
TypeScript
Improve Dialog docs page and block examples (#1570)
rubyycheung553efd3b5062
diff --git a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjsindex 93dcec5af5..14a81417b3 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs+++ b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs@@ -1,10 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Dialog — Confirmation Dialog',+ name: 'Dialog — Confirmation',description:- 'Destructive action confirmation with cancel and delete buttons.',+ 'Asks the user to confirm a destructive action before it happens. Use before deleting projects, removing team members, revoking API keys, or any irreversible operation.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Dialog', 'Layout', 'Button', 'Text'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Dialog', 'Layout', 'Button', 'Text', 'Card'],};diff --git a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.tsx b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.tsxindex 0c55c97344..b8812b4753 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.tsx+++ b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.tsx@@ -7,48 +7,51 @@ import {XDSLayoutContent,XDSLayoutFooter,XDSHStack,+ XDSVStack,} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText} from '@xds/core/Text';+import {XDSCard} from '@xds/core/Card';export default function DialogConfirmationDialog() {const [isOpen, setIsOpen] = useState(false);- const [deleted, setDeleted] = useState(false);const handleDelete = () => {- setDeleted(true);setIsOpen(false);};return (- <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>- <XDSButton- label="Delete Item"- variant="destructive"- onClick={() => setIsOpen(true)}- />- {deleted && (- <XDSText type="body" color="primary">- Item deleted (demo)- </XDSText>- )}+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSVStack gap={1}>+ <XDSText type="body" weight="bold">Marketing Dashboard</XDSText>+ <XDSText type="supporting" color="secondary">+ Created Jan 12, 2026 · 14 pages · 3 collaborators+ </XDSText>+ </XDSVStack>+ <XDSHStack gap={2}>+ <XDSButton label="Edit" variant="secondary" onClick={() => {}} />+ <XDSButton+ label="Delete project"+ variant="destructive"+ onClick={() => setIsOpen(true)}+ />+ </XDSHStack>+ </XDSVStack><XDSDialogisOpen={isOpen}onOpenChange={setIsOpen}- width={350}+ width={400}purpose="form"><XDSLayoutheader={- <XDSDialogHeader- title="Confirm Delete"- onOpenChange={setIsOpen}- />+ <XDSDialogHeader title="Delete project?" onOpenChange={setIsOpen} />}content={<XDSLayoutContent><XDSText type="body">- Are you sure you want to delete this item? This action cannot be- undone.+ This will permanently delete "Marketing Dashboard" and+ all of its data. This action cannot be undone.</XDSText></XDSLayoutContent>}@@ -70,6 +73,6 @@ export default function DialogConfirmationDialog() {}/></XDSDialog>- </div>+ </XDSCard>);}diff --git a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjsindex b36f544dbb..ba45855c00 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs+++ b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs@@ -1,10 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Dialog — Form Dialog',+ name: 'Dialog — Form',description:- 'Form-purpose dialog that prevents backdrop dismissal to protect unsaved data.',+ 'Collects user input without navigating away from the page. Uses purpose="form" so clicking the backdrop won\'t close it. Use for editing profiles, creating items, or updating settings inline.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Dialog', 'Layout', 'Button', 'Text'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Dialog', 'Layout', 'Button', 'Text', 'TextInput', 'TextArea', 'Card'],};diff --git a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.tsx b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.tsxindex 48706e8ea2..5ec81dace3 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.tsx+++ b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.tsx@@ -7,39 +7,63 @@ import {XDSLayoutContent,XDSLayoutFooter,XDSHStack,+ XDSVStack,} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText} from '@xds/core/Text';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSTextArea} from '@xds/core/TextArea';+import {XDSCard} from '@xds/core/Card';export default function DialogFormDialog() {const [isOpen, setIsOpen] = useState(false);+ const [name, setName] = useState('Ruby Cheung');+ const [bio, setBio] = useState('Design systems engineer');return (- <>- <XDSButton- label="Open Form Modal"- variant="secondary"- onClick={() => setIsOpen(true)}- />+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSVStack gap={1}>+ <XDSText type="body" weight="bold">Profile Settings</XDSText>+ <XDSText type="supporting" color="secondary">+ Display name, bio, and avatar+ </XDSText>+ </XDSVStack>+ <XDSButton+ label="Edit profile"+ variant="secondary"+ onClick={() => setIsOpen(true)}+ />+ </XDSVStack><XDSDialogisOpen={isOpen}onOpenChange={setIsOpen}purpose="form"- width={500}>+ width={480}><XDSLayoutheader={<XDSDialogHeader- title="Edit Profile"+ title="Edit profile"+ subtitle="Update your display name and bio"onOpenChange={setIsOpen}/>}content={<XDSLayoutContent>- <XDSText type="body">- This modal uses purpose="form". Clicking outside- won't close it to prevent accidental data loss, but you can- still press Escape.- </XDSText>+ <XDSVStack gap={4}>+ <XDSTextInput+ label="Display name"+ value={name}+ onChange={setName}+ placeholder="Enter your name"+ />+ <XDSTextArea+ label="Bio"+ value={bio}+ onChange={setBio}+ placeholder="Tell us about yourself"+ />+ </XDSVStack></XDSLayoutContent>}footer={@@ -60,6 +84,6 @@ export default function DialogFormDialog() {}/></XDSDialog>- </>+ </XDSCard>);}diff --git a/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.doc.mjsindex 2649d318bf..892440af18 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.doc.mjs+++ b/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.doc.mjs@@ -1,9 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Dialog — Fullscreen Dialog',- description: 'Full-viewport dialog variant with scrollable content.',+ name: 'Dialog — Fullscreen',+ description:+ 'Takes over the entire viewport for content that needs maximum space. Use for documentation viewers, rich text editors, multi-step wizards, or media previews where the standard dialog width is too narrow.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Dialog', 'Layout', 'Button', 'Text'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Dialog', 'Layout', 'Button', 'Text', 'Card'],};diff --git a/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.tsx b/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.tsxindex 95aba60ebe..30b70fd136 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.tsx+++ b/packages/cli/templates/blocks/components/Dialog/DialogFullscreenDialog.tsx@@ -7,44 +7,72 @@ import {XDSLayoutContent,XDSLayoutFooter,XDSHStack,+ XDSVStack,} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText} from '@xds/core/Text';+import {XDSCard} from '@xds/core/Card';++const SECTIONS = [+ {+ title: 'Getting started',+ body: 'Create your first project by clicking New Project in the sidebar. Choose a template or start from scratch.',+ },+ {+ title: 'Team members',+ body: 'Invite collaborators from Settings > Team. Each member can have Admin, Editor, or Viewer permissions.',+ },+ {+ title: 'Billing',+ body: 'Free plans include up to 3 projects. Upgrade to Pro for unlimited projects and priority support.',+ },+ {+ title: 'API access',+ body: 'Generate API keys from Settings > Developer. Rate limits are 1,000 requests per minute on free plans.',+ },+ {+ title: 'Data export',+ body: 'Export your data anytime from Settings > Data. Exports are available as CSV or JSON within 24 hours.',+ },+];export default function DialogFullscreenDialog() {const [isOpen, setIsOpen] = useState(false);return (- <>- <XDSButton- label="Open Fullscreen Modal"- variant="secondary"- onClick={() => setIsOpen(true)}- />+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSVStack gap={1}>+ <XDSText type="body" weight="bold">Help & Documentation</XDSText>+ <XDSText type="supporting" color="secondary">+ 5 articles · Last updated Apr 2026+ </XDSText>+ </XDSVStack>+ <XDSButton+ label="Open documentation"+ variant="secondary"+ onClick={() => setIsOpen(true)}+ />+ </XDSVStack><XDSDialog isOpen={isOpen} onOpenChange={setIsOpen} variant="fullscreen"><XDSLayoutheader={<XDSDialogHeader- title="Fullscreen Modal"+ title="Documentation"+ subtitle="Everything you need to get started"onOpenChange={setIsOpen}/>}content={<XDSLayoutContent>- <div- style={{display: 'flex', flexDirection: 'column', gap: 12}}>- <XDSText type="body">- This modal takes up the entire viewport. The width, maxHeight,- and position props are ignored in fullscreen mode.- </XDSText>- {Array.from({length: 10}, (_, i) => (- <XDSText type="body" key={i}>- {i + 1}. Lorem ipsum dolor sit amet, consectetur adipiscing- elit. Sed do eiusmod tempor incididunt ut labore et dolore- magna aliqua.- </XDSText>+ <XDSVStack gap={4}>+ {SECTIONS.map(({title, body}) => (+ <XDSVStack key={title} gap={1}>+ <XDSText type="body" weight="bold">{title}</XDSText>+ <XDSText type="body">{body}</XDSText>+ </XDSVStack>))}- </div>+ </XDSVStack></XDSLayoutContent>}footer={@@ -60,6 +88,6 @@ export default function DialogFullscreenDialog() {}/></XDSDialog>- </>+ </XDSCard>);}diff --git a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjsindex 0274ccfba2..051bed7d00 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs+++ b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs@@ -1,10 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Dialog — Scrolling Content',+ name: 'Dialog — Scrollable',description:- 'Dialog with constrained max height and scrollable body content.',+ 'Constrains the dialog height and scrolls the body when content overflows. Use for terms and conditions, license agreements, changelogs, or any long-form content the user needs to review before accepting.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Dialog', 'Layout', 'Button', 'Text'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Dialog', 'Layout', 'Button', 'Text', 'Card'],};diff --git a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.tsx b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.tsxindex b75801b402..98556942be 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.tsx+++ b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.tsx@@ -7,20 +7,41 @@ import {XDSLayoutContent,XDSLayoutFooter,XDSHStack,+ XDSVStack,} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText} from '@xds/core/Text';+import {XDSCard} from '@xds/core/Card';++const TERMS = [+ 'You agree to use the service only for lawful purposes and in compliance with all applicable laws.',+ 'Your account credentials are your responsibility. Notify us immediately if you suspect unauthorized access.',+ 'We reserve the right to suspend accounts that violate these terms or engage in abusive behavior.',+ 'Content you upload remains your property. You grant us a license to host and display it within the service.',+ 'We may update these terms at any time. Continued use after changes constitutes acceptance.',+ 'The service is provided as-is without warranties. We are not liable for data loss or service interruptions.',+ 'You may cancel your account at any time. Your data will be deleted within 30 days of cancellation.',+ 'Disputes will be resolved through binding arbitration in accordance with applicable regulations.',+];export default function DialogScrollingContent() {const [isOpen, setIsOpen] = useState(false);return (- <>- <XDSButton- label="Open Scrolling Modal"- variant="secondary"- onClick={() => setIsOpen(true)}- />+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSVStack gap={1}>+ <XDSText type="body" weight="bold">Terms and Conditions</XDSText>+ <XDSText type="supporting" color="secondary">+ Last updated March 2026 · 8 clauses+ </XDSText>+ </XDSVStack>+ <XDSButton+ label="Review terms"+ variant="secondary"+ onClick={() => setIsOpen(true)}+ />+ </XDSVStack><XDSDialog isOpen={isOpen} onOpenChange={setIsOpen} maxHeight="50vh"><XDSLayoutheader={@@ -31,18 +52,13 @@ export default function DialogScrollingContent() {}content={<XDSLayoutContent>- <div- style={{display: 'flex', flexDirection: 'column', gap: 12}}>- {Array.from({length: 20}, (_, i) => (+ <XDSVStack gap={3}>+ {TERMS.map((term, i) => (<XDSText type="body" key={i}>- {i + 1}. Lorem ipsum dolor sit amet, consectetur adipiscing- elit. Sed do eiusmod tempor incididunt ut labore et dolore- magna aliqua. Ut enim ad minim veniam, quis nostrud- exercitation ullamco laboris nisi ut aliquip ex ea commodo- consequat.+ {i + 1}. {term}</XDSText>))}- </div>+ </XDSVStack></XDSLayoutContent>}footer={@@ -63,6 +79,6 @@ export default function DialogScrollingContent() {}/></XDSDialog>- </>+ </XDSCard>);}diff --git a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjsindex a85cc0e06e..a092629894 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs+++ b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs@@ -1,9 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Dialog — With Subtitle',- description: 'Modal dialog with a title and subtitle in the header.',+ name: 'Dialog — Required',+ description:+ 'Cannot be dismissed by Escape or backdrop click — the user must explicitly choose an action. Uses purpose="required". Use for ownership transfers, legal acknowledgements, or critical decisions where skipping is not an option.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Dialog', 'Layout', 'Button', 'Text'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Dialog', 'Layout', 'Button', 'Text', 'Card'],};diff --git a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.tsx b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.tsxindex 278d375262..52f64dd29e 100644--- a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.tsx+++ b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.tsx@@ -7,34 +7,43 @@ import {XDSLayoutContent,XDSLayoutFooter,XDSHStack,+ XDSVStack,} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText} from '@xds/core/Text';+import {XDSCard} from '@xds/core/Card';export default function DialogWithSubtitle() {const [isOpen, setIsOpen] = useState(false);return (- <>- <XDSButton- label="Open Modal with Subtitle"- variant="secondary"- onClick={() => setIsOpen(true)}- />- <XDSDialog isOpen={isOpen} onOpenChange={setIsOpen}>+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSVStack gap={1}>+ <XDSText type="body" weight="bold">Project Ownership</XDSText>+ <XDSText type="supporting" color="secondary">+ Marketing Dashboard · Owner: You+ </XDSText>+ </XDSVStack>+ <XDSButton+ label="Transfer ownership"+ variant="secondary"+ onClick={() => setIsOpen(true)}+ />+ </XDSVStack>+ <XDSDialog isOpen={isOpen} onOpenChange={setIsOpen} purpose="required"><XDSLayoutheader={<XDSDialogHeader- title="Edit User Profile"- subtitle="Make changes to your account settings"- onOpenChange={setIsOpen}+ title="Transfer project ownership"+ subtitle="This action requires confirmation from the new owner"/>}content={<XDSLayoutContent><XDSText type="body">- The subtitle appears below the title in smaller, secondary text.- It provides additional context about the dialog's purpose.+ You are about to transfer "Marketing Dashboard" to+ Sarah Chen. Once accepted, you will lose admin access.</XDSText></XDSLayoutContent>}@@ -47,7 +56,7 @@ export default function DialogWithSubtitle() {onClick={() => setIsOpen(false)}/><XDSButton- label="Save Changes"+ label="Transfer"variant="primary"onClick={() => setIsOpen(false)}/>@@ -56,6 +65,6 @@ export default function DialogWithSubtitle() {}/></XDSDialog>- </>+ </XDSCard>);}diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex f7bc6c763f..90c1c25539 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -115,19 +115,21 @@ export const docs = {},],usage: {- description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',+ description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',bestPractices: [- { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },- { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },+ { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },+ { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },+ { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },+ { guidance: true, description: 'Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead.' },{ guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },{ guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms.' },],anatomy: [- {name: 'Body', required: true, description: 'The main content area of the dialog.'},- {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},- {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},- {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},- {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},+ {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},+ {name: 'Body', required: true, description: 'The main content area — text, forms, lists, or any layout.'},+ {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},+ {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},],},};@@ -248,40 +250,35 @@ export const docsZh = {},],usage: {- description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',+ description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',bestPractices: [- { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },- { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },+ { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },+ { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },+ { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },+ { guidance: true, description: 'Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead.' },{ guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },{ guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms.' },],anatomy: [- {name: 'Body', required: true, description: 'The main content area of the dialog.'},- {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},- {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},- {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},- {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},+ {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},+ {name: 'Body', required: true, description: 'The main content area — text, forms, lists, or any layout.'},+ {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},+ {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},],},};/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'modal dialog using native <dialog> w/ auto focus trapping, backdrop, purpose-based dismissal',+ description: 'modal overlay that blocks page interaction until the user responds',usage: {- description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',+ description: 'Dialog displays a modal overlay that blocks page interaction. Use for delete confirmations, edit forms, terms acceptance.',bestPractices: [- { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },- { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },- { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },- { guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },- ],- anatomy: [- {name: 'Body', required: true, description: 'The main content area of the dialog.'},- {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},- {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},- {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},- {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},+ { guidance: true, description: 'Pick the right purpose: info=dismissable, form=no backdrop dismiss, required=must respond.' },+ { guidance: true, description: 'Clear title in header. Use purpose="form" for dialogs with inputs.' },+ { guidance: false, description: 'Use for simple messages — use inline or toast instead. Don\'t nest dialogs.' },+ { guidance: false, description: 'Fullscreen for simple confirmations — it\'s for complex content like editors.' },],},components: [