Skip to content

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.mjs
index 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.tsx
index 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>
<XDSDialog
isOpen={isOpen}
onOpenChange={setIsOpen}
- width={350}
+ width={400}
purpose="form">
<XDSLayout
header={
- <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 &quot;Marketing Dashboard&quot; 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.mjs
index 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.tsx
index 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>
<XDSDialog
isOpen={isOpen}
onOpenChange={setIsOpen}
purpose="form"
- width={500}>
+ width={480}>
<XDSLayout
header={
<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=&quot;form&quot;. Clicking outside
- won&apos;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.mjs
index 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.tsx
index 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 &amp; 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">
<XDSLayout
header={
<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.mjs
index 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.tsx
index 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">
<XDSLayout
header={
@@ -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.mjs
index 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.tsx
index 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">
<XDSLayout
header={
<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&apos;s purpose.
+ You are about to transfer &quot;Marketing Dashboard&quot; 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.mjs
index 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: [