# Dialog
A controlled alert dialog for explicit decisions, with slotted title and supporting-copy parts, a required primary action, an optional safe secondary action, and an optional transient error region.
Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/overlays/Dialog/Dialog.tsx
## Guidance
{
"summary": "A controlled alert dialog for explicit decisions, with slotted title and supporting-copy parts, a required primary action, an optional safe secondary action, and an optional transient error region.",
"guidance": [
{
"heading": "Overview",
"body": "A controlled confirmation surface for decisions that require an explicit action.\nA title slot, a body slot, and a primary action are required. Add a secondary\nsafe action when the context needs one."
},
{
"heading": "Composition",
"body": "Copy is slotted, not passed as props. `Dialog.Title` and each `Dialog.Description`\ntake plain strings, so a dialog can carry several paragraphs without the surface\naccepting arbitrary markup.\n\n```tsx\n\n```\n\nHierarchy comes from color and order, not weight: `color='secondary'` drops the\nsupporting paragraphs back so the one consequence the reader must not skim past\nkeeps primary text and sits last, directly above the actions. There is no bold\nparagraph to reach for — a `` tag would inherit the user-agent 700 and a\nshared emphasis variant would be reachable from anywhere.\n\nThe actions stay props on purpose. Their order, focus, and tone are the alert\ngrammar this component exists to enforce, so they are not open to composition.\n`Dialog.Body` owns the `aria-describedby` target, which keeps the accessible\ndescription to the copy and excludes the title."
},
{
"heading": "Behavior",
"body": "`Dialog` does not dismiss from the backdrop or Escape. The caller owns `isOpen`\nand closes it from an action callback. Focus moves to an enabled secondary\naction, or to the dialog itself when no safe action is available, and returns to\nthe launcher after the close animation.\n\nPass `error` when the last action attempt failed. It renders in a `role=\"alert\"`\nregion below the copy and stays out of `aria-describedby`, so a retryable message\nis announced once rather than joining the dialog's standing description."
}
],
"usage": [
{
"variant": "Two actions",
"use": "The user can safely cancel or confirm. The enabled secondary action receives initial focus.",
"axis": "Configuration"
},
{
"variant": "Primary only",
"use": "The user only needs to acknowledge a completed or informational state.",
"avoid": "High-risk actions where the user needs a clear way to cancel.",
"axis": "Configuration"
}
],
"examples": [],
"source": "packages/design-system/src/components/overlays/Dialog/Dialog.mdx",
"status": "local-preview",
"note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}
## Contract and public API
```json
{
"props": [
{
"name": "isOpen",
"type": "boolean",
"declared_type": "boolean",
"required": true,
"description": "Presents the surface when true; closing remains mounted until the exit animation completes.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 45
},
"values": [
false,
true
],
"values_complete": true
},
{
"name": "children",
"type": "[React.ReactElement>, React.ReactElement>]",
"declared_type": "[React.ReactElement, React.ReactElement]",
"required": true,
"description": "The title and body slots, in that order.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 47
}
},
{
"name": "primaryAction",
"type": "DialogPrimaryAction",
"declared_type": "DialogPrimaryAction",
"required": true,
"description": "Required confirming or acknowledging action; it never receives initial focus.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 49
}
},
{
"name": "secondaryAction",
"type": "DialogSecondaryAction | undefined",
"declared_type": "DialogSecondaryAction",
"required": false,
"description": "Optional safe action; when enabled, it receives initial focus.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 51
}
},
{
"name": "error",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Transient failure from the last action attempt. Kept out of `aria-describedby`.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 53
}
},
{
"name": "testId",
"type": "string",
"declared_type": "string",
"required": true,
"description": "Root selector used to derive slot, action, and overlay test ids.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 55
}
},
{
"name": "portalTarget",
"type": "HTMLElement | null | undefined",
"declared_type": "HTMLElement | null",
"required": false,
"description": "Portal mount node. Defaults to `document.body`.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 57
}
}
],
"prop_shapes": {},
"api": {
"method": "typescript-type-checker",
"typescript_version": "5.9.3",
"public_export": "Dialog",
"public_path": "Dialog",
"import_path": "@cloakedinc/design-system",
"root_kind": "component",
"entrypoints": [
{
"name": "Dialog",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 64
},
"props_type": "DialogProps",
"props": [
{
"name": "isOpen",
"type": "boolean",
"declared_type": "boolean",
"required": true,
"description": "Presents the surface when true; closing remains mounted until the exit animation completes.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 45
},
"values": [
false,
true
],
"values_complete": true
},
{
"name": "children",
"type": "[React.ReactElement>, React.ReactElement>]",
"declared_type": "[React.ReactElement, React.ReactElement]",
"required": true,
"description": "The title and body slots, in that order.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 47
}
},
{
"name": "primaryAction",
"type": "DialogPrimaryAction",
"declared_type": "DialogPrimaryAction",
"required": true,
"description": "Required confirming or acknowledging action; it never receives initial focus.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 49
}
},
{
"name": "secondaryAction",
"type": "DialogSecondaryAction | undefined",
"declared_type": "DialogSecondaryAction",
"required": false,
"description": "Optional safe action; when enabled, it receives initial focus.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 51
}
},
{
"name": "error",
"type": "string | undefined",
"declared_type": "string",
"required": false,
"description": "Transient failure from the last action attempt. Kept out of `aria-describedby`.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 53
}
},
{
"name": "testId",
"type": "string",
"declared_type": "string",
"required": true,
"description": "Root selector used to derive slot, action, and overlay test ids.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 55
}
},
{
"name": "portalTarget",
"type": "HTMLElement | null | undefined",
"declared_type": "HTMLElement | null",
"required": false,
"description": "Portal mount node. Defaults to `document.body`.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 57
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
},
{
"name": "Dialog.Title",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogTitle.tsx",
"line": 16
},
"props_type": "DialogTitleProps",
"props": [
{
"name": "children",
"type": "string",
"declared_type": "string",
"required": true,
"description": "Doubles as the alertdialog's accessible name.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogTitle.tsx",
"line": 10
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
},
{
"name": "Dialog.Body",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogBody.tsx",
"line": 20
},
"props_type": "DialogBodyProps",
"props": [
{
"name": "children",
"type": "React.ReactElement> | React.ReactElement>[]",
"declared_type": "React.ReactElement | Array>",
"required": true,
"description": "One description per paragraph; the body owns the spacing between them.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogBody.tsx",
"line": 13
}
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
},
{
"name": "Dialog.Description",
"signature": 1,
"visibility": "public",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogDescription.tsx",
"line": 20
},
"props_type": "DialogDescriptionProps",
"props": [
{
"name": "children",
"type": "string",
"declared_type": "string",
"required": true,
"description": "Plain copy for one paragraph. Multi-paragraph content is sibling descriptions, not markup.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogDescription.tsx",
"line": 9
}
},
{
"name": "color",
"type": "\"primary\" | \"secondary\" | undefined",
"declared_type": "'primary' | 'secondary'",
"required": false,
"description": "Drops a paragraph to secondary text. Hierarchy in a dialog comes from color and order, so\nthe paragraph the reader must not skim past stays primary and sits last, next to the actions.",
"source": {
"path": "packages/design-system/src/components/overlays/Dialog/DialogDescription.tsx",
"line": 14
},
"values": [
"primary",
"secondary"
],
"values_complete": true,
"default": "'primary'",
"default_kind": "source-expression"
}
],
"branches": [],
"constraints": [],
"extraction_status": "extracted"
}
],
"type_sources": [
{
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 22,
"name": "DialogPrimaryAction",
"code": "export interface DialogPrimaryAction {\n label: string;\n onPress: () => void;\n /** Use `danger` for irreversible actions. */\n tone?: 'default' | 'danger';\n loading?: boolean;\n disabled?: boolean;\n}"
},
{
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 34,
"name": "DialogSecondaryAction",
"code": "export interface DialogSecondaryAction {\n label: string;\n onPress: () => void;\n disabled?: boolean;\n}"
},
{
"path": "packages/design-system/src/components/overlays/Dialog/Dialog.tsx",
"line": 43,
"name": "DialogProps",
"code": "export interface DialogProps {\n /** Presents the surface when true; closing remains mounted until the exit animation completes. */\n isOpen: boolean;\n /** The title and body slots, in that order. */\n children: [React.ReactElement, React.ReactElement];\n /** Required confirming or acknowledging action; it never receives initial focus. */\n primaryAction: DialogPrimaryAction;\n /** Optional safe action; when enabled, it receives initial focus. */\n secondaryAction?: DialogSecondaryAction;\n /** Transient failure from the last action attempt. Kept out of `aria-describedby`. */\n error?: string;\n /** Root selector used to derive slot, action, and overlay test ids. */\n testId: string;\n /** Portal mount node. Defaults to `document.body`. */\n portalTarget?: HTMLElement | null;\n}"
},
{
"path": "packages/design-system/src/components/overlays/Dialog/DialogBody.tsx",
"line": 11,
"name": "DialogBodyProps",
"code": "export interface DialogBodyProps {\n /** One description per paragraph; the body owns the spacing between them. */\n children: React.ReactElement | Array>;\n}"
},
{
"path": "packages/design-system/src/components/overlays/Dialog/DialogDescription.tsx",
"line": 7,
"name": "DialogDescriptionProps",
"code": "export interface DialogDescriptionProps {\n /** Plain copy for one paragraph. Multi-paragraph content is sibling descriptions, not markup. */\n children: string;\n /**\n * Drops a paragraph to secondary text. Hierarchy in a dialog comes from color and order, so\n * the paragraph the reader must not skim past stays primary and sits last, next to the actions.\n */\n color?: 'primary' | 'secondary';\n}"
},
{
"path": "packages/design-system/src/components/overlays/Dialog/DialogTitle.tsx",
"line": 8,
"name": "DialogTitleProps",
"code": "export interface DialogTitleProps {\n /** Doubles as the alertdialog's accessible name. */\n children: string;\n}"
}
],
"defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
},
"spec": {
"$schema": "../../../specs/component-spec.schema.json",
"identity": {
"name": "Dialog",
"status": "preview",
"version": "1.1.1",
"summary": "A controlled alert dialog for explicit decisions, with slotted title and supporting-copy parts, a required primary action, an optional safe secondary action, and an optional transient error region."
},
"parts": [
{
"id": "root",
"label": "Root",
"description": "Centered alert-dialog surface containing the decision content and actions.",
"required": true
},
{
"id": "overlay",
"label": "Overlay",
"description": "Modal backdrop behind the dialog."
},
{
"id": "title",
"label": "Title",
"description": "Required heading slot that names the decision and supplies the accessible name.",
"required": true
},
{
"id": "body",
"label": "Body",
"description": "Required supporting-copy slot. It stacks one or more description paragraphs and is the target of the dialog's accessible description.",
"required": true
},
{
"id": "description",
"label": "Description",
"description": "One paragraph of plain supporting copy. Multi-paragraph content is sibling descriptions. A paragraph may drop to secondary text so the paragraph that must not be skimmed past reads first.",
"required": true
},
{
"id": "primary-action",
"label": "Primary action",
"description": "Required confirming or acknowledging action.",
"required": true
},
{
"id": "secondary-action",
"label": "Secondary action",
"description": "Optional safe or cancelling action."
},
{
"id": "error",
"label": "Error",
"description": "Optional transient failure from the last action attempt, announced on appearance."
}
],
"allowedDesignChoices": {
"variants": {
"default": {
"label": "Default",
"description": "Centered explicit-action dialog with default or danger primary-action tone."
}
},
"sizes": {}
},
"variants": [
{
"id": "default",
"label": "Default",
"description": "Centered modal decision surface.",
"platforms": [
"ios",
"android",
"web"
]
}
],
"sizes": [],
"measurements": [
{
"id": "overlay-inset",
"label": "Overlay inset",
"kind": "exact",
"token": "--cds-space-24",
"value": 24,
"unit": "px",
"appliesTo": [
"overlay"
]
},
{
"id": "dialog-maximum-width",
"label": "Dialog maximum width",
"kind": "at-most",
"token": "--cds-size-320",
"value": 320,
"unit": "px",
"appliesTo": [
"root"
]
},
{
"id": "dialog-padding",
"label": "Dialog padding",
"kind": "exact",
"token": "--cds-space-24",
"value": 24,
"unit": "px",
"appliesTo": [
"root"
]
},
{
"id": "content-action-gap",
"label": "Content-to-action gap",
"kind": "exact",
"token": "--cds-space-16",
"value": 16,
"unit": "px",
"appliesTo": [
"root"
]
},
{
"id": "title-description-gap",
"label": "Title-to-description gap",
"kind": "exact",
"token": "--cds-space-8",
"value": 8,
"unit": "px",
"appliesTo": [
"title",
"body"
]
},
{
"id": "action-gap",
"label": "Action gap",
"kind": "exact",
"token": "--cds-space-8",
"value": 8,
"unit": "px",
"appliesTo": [
"primary-action",
"secondary-action"
]
},
{
"id": "corner-radius",
"label": "Corner radius",
"kind": "exact",
"token": "--cds-radius-2xl",
"value": 32,
"unit": "px",
"appliesTo": [
"root"
]
},
{
"id": "description-gap",
"label": "Paragraph gap",
"kind": "exact",
"token": "--cds-space-8",
"value": 8,
"unit": "px",
"appliesTo": [
"body",
"description"
]
}
],
"layout": {
"alignment": "The overlay centers the dialog in the available viewport while allowing vertical scrolling when content is taller than the viewport.",
"flow": "The title and the stacked description paragraphs sit above an optional error region and then either one full-width primary action or a wrapping row containing the safe secondary action followed by the primary action.",
"notes": [
"Two actions remain side by side while their labels fit and wrap into a stack with the primary action first when space is constrained."
]
},
"typographyAndColor": {
"typography": [
{
"label": "Title",
"description": "The dialog title uses the h4 ramp.",
"token": "--cds-type-h4-size"
},
{
"label": "Description",
"description": "Each description paragraph uses the body-small ramp.",
"token": "--cds-type-body-small-size"
}
],
"colors": [
{
"label": "Surface",
"description": "The dialog uses the raised surface background.",
"token": "--cds-bg-surface"
},
{
"label": "Primary text",
"description": "The title and default supporting content use primary text.",
"token": "--cds-text-primary"
},
{
"label": "Secondary text",
"description": "A description paragraph subordinate to the consequence uses secondary text.",
"token": "--cds-text-secondary"
},
{
"label": "Overlay",
"description": "The modal backdrop uses the shared overlay token.",
"token": "--cds-overlay-backdrop"
},
{
"label": "Error text",
"description": "The transient error region uses danger text.",
"token": "--cds-status-danger-solid"
}
]
},
"states": [
{
"id": "closed",
"label": "Closed",
"description": "Not mounted after the exit animation completes."
},
{
"id": "open",
"label": "Open",
"description": "Mounted as a modal alert dialog with actions available."
},
{
"id": "primary-loading",
"label": "Primary loading",
"description": "The primary action communicates pending work and blocks repeated activation."
},
{
"id": "action-disabled",
"label": "Action disabled",
"description": "Either action may be disabled while its operation is unavailable."
},
{
"id": "error",
"label": "Error",
"description": "The last action attempt failed and the dialog shows a retryable message."
}
],
"behavior": [
{
"label": "Controlled visibility",
"description": "The caller owns isOpen and closes the dialog from an action callback."
},
{
"label": "Explicit decision",
"description": "Backdrop interaction does not dismiss the dialog; the user chooses an action."
},
{
"label": "Slotted content",
"description": "Copy is composed from a title slot and one description slot per paragraph, each taking plain text. The surface accepts no arbitrary markup, so multi-paragraph dialogs stay on the type ramp; a description sets its rank through primary or secondary text color instead of inline markup."
},
{
"label": "Action priority",
"description": "Use the danger primary-action tone for irreversible actions and provide a safe secondary action when cancellation is meaningful."
},
{
"label": "Transient error",
"description": "An error from the last action attempt is announced through an alert region and is kept out of the dialog's standing accessible description."
}
],
"accessibility": [
{
"label": "Alert dialog semantics",
"description": "The root uses alertdialog and aria-modal, is named by the title slot, and is described by the body slot, which contains only the supporting paragraphs."
},
{
"label": "Focus placement",
"description": "An enabled safe secondary action receives initial focus when present; otherwise the dialog surface receives focus. Closing restores focus to the launcher. The surface suppresses the focus outline: the runtime is touch-only, so a ring around the whole card signals nothing."
},
{
"label": "Action labels",
"description": "Both actions expose their visible labels through the shared Button primitive."
}
],
"contentAdaptation": [
{
"label": "Multi-paragraph copy",
"description": "Split supporting copy into one description per paragraph when separate points communicate consequences more clearly."
},
{
"label": "Long action labels",
"description": "The two-action row wraps into a vertical stack instead of clipping or shrinking labels."
},
{
"label": "Viewport constraints",
"description": "The overlay scrolls vertically when the dialog cannot fit within the available viewport."
},
{
"label": "Ranked paragraphs",
"description": "When a dialog carries several paragraphs, drop the supporting ones to secondary text and keep the irreversible consequence in primary text as the last paragraph before the actions."
}
],
"motionHaptics": {
"motion": [
{
"label": "Presentation",
"description": "The overlay fades in while the dialog fades and scales to its resting size; scaling is removed under reduced motion."
}
],
"haptics": [
{
"label": "Actions",
"description": "Dialog actions inherit the shared Button haptic behavior."
}
]
},
"platformDifferences": []
},
"platforms": {
"implemented": [
"web"
],
"native": "Imported design guidance only; no native implementation or parity verification in this preview.",
"react": {
"implementation": "local",
"status": "preview",
"parity": "web-reference"
},
"vue": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
},
"swift": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
},
"kotlin": {
"implementation": "absent",
"parity": "not-verified",
"status": "reference-only"
}
},
"tokens": [
{
"name": "--cds-space-24",
"light": "24px",
"dark": "24px"
},
{
"name": "--cds-size-320",
"light": "320px",
"dark": "320px"
},
{
"name": "--cds-space-16",
"light": "16px",
"dark": "16px"
},
{
"name": "--cds-space-8",
"light": "8px",
"dark": "8px"
},
{
"name": "--cds-radius-2xl",
"light": "32px",
"dark": "32px"
},
{
"name": "--cds-type-h4-size",
"light": "1.25rem",
"dark": "1.25rem"
},
{
"name": "--cds-type-body-small-size",
"light": "0.875rem",
"dark": "0.875rem"
},
{
"name": "--cds-bg-surface",
"light": "#ffffff",
"dark": "#1b1b18"
},
{
"name": "--cds-text-primary",
"light": "#141410",
"dark": "#f3f1ed"
},
{
"name": "--cds-text-secondary",
"light": "#646260",
"dark": "#ffffff99"
},
{
"name": "--cds-overlay-backdrop",
"light": "rgb(0 0 0 / 40%)",
"dark": "rgb(0 0 0 / 40%)"
},
{
"name": "--cds-status-danger-solid",
"light": "#b83100",
"dark": "#b83100"
}
],
"review": {
"local_status": "not-reviewed",
"source_approval": null,
"imported_spec_status": "approved",
"spec_origin": "imported-adapted",
"local_spec_source_status": "approved",
"imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
"note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
},
"missing_facts": [
{
"code": "human-review-pending",
"detail": "This local preview has no recorded human design or engineering sign-off."
},
{
"code": "platform-parity-unverified",
"detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
},
{
"code": "figma-mapping-unverified",
"detail": "No current component-level Figma node and immutable revision have been verified for this contract."
}
]
}
```
## Visual states
- [Destructive](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--destructive&viewMode=story) | export: Destructive | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [Multiple Paragraphs](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--multiple-paragraphs&viewMode=story) | export: MultipleParagraphs | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [With Error](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--with-error&viewMode=story) | export: WithError | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [Two Actions](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--two-actions&viewMode=story) | export: TwoActions | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [Primary Only](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--primary-only&viewMode=story) | export: PrimaryOnly | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [Loading Disabled](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--loading-disabled&viewMode=story) | export: LoadingDisabled | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-overlays-dialog--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/overlays/Dialog/Dialog.stories.tsx
Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.