An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 4 kind: component id: component:Dialog authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-07 owners: [cixzhang, imdreamrunner] review_triggers: [behavior, accessibility, public-api] verified_by: [ packages/core/src/Dialog/Dialog.test.tsx, packages/core/src/Dialog/DialogHeader.test.tsx, packages/core/src/Dialog/tests/Dialog.a11y.test.tsx, packages/core/src/Dialog/tests/Dialog.a11y.chromium.spec.ts, packages/core/src/Dialog/tests/Dialog.a11y.browser.spec.ts, packages/core/src/tests/modalBackdrop.test.tsx, packages/core/src/tests/ModalBackdrop.a11y.browser.spec.ts, ] modules: [module:Dialog/DialogHeader] families: [family:overlay-dismissal] design_specs: [] architecture: [ architecture:interaction-modality, architecture:layer-runtime, architecture:public-component-api, architecture:react-component-runtime, ] contributing: []
system_specs: [spec:AST-013, spec:AST-020, spec:AST-021, spec:AST-094/FR35]
Dialog component contract
Intent
Dialog presents one modal task above the current page. It owns the transition into and out of that modal focus context so keyboard and assistive-technology users start inside visible content and return to the invoking context when the task closes.
This record captures Dialog's component-local focus lifecycle. Shared dismissal, layer ordering, public API admission, and runtime resource ownership stay with their current family and architecture owners.
Compatibility and migration
- Released default preserved: yes.
- Compatibility class: records the shipped native-modal and inline-preview split.
- Controlled/uncontrolled behavior: Dialog visibility remains controlled.
- Migration decision: none; the current focus lifecycle is made explicit.
Ownership boundary
Owns
- initial focus after the native modal becomes visible;
- the default DialogHeader title focus target;
- focus return to the external invoking element when the modal closes; and
- suppression of modal focus behavior for inline documentation rendering.
Does not own / non-goals
- Escape, backdrop, nesting, and topmost-layer dismissal — owned by
family:overlay-dismissalandarchitecture:layer-runtime; - the public admission or naming of autofocus props on descendant components —
owned by those components and
architecture:public-component-api; - focus-ring appearance and modality detection — owned by accessibility and interaction authority; or
- a generic focus-management API for every overlay.
Public concepts
| Concept | Closed values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
| visibility | open, closed | whether the controlled modal is presented | caller-controlled | component:Dialog |
stable |
| presentation | native modal, inline preview | native dialog behavior versus non-modal documentation rendering | native modal | component:Dialog |
stable |
| initial-focus request | eligible descendant, default title, native fallback | where focus begins after modal presentation | DialogHeader title when present | component:Dialog plus descendant owner |
stable outcome |
| invoking focus | focusable external trigger, unavailable trigger | context restored after close when still reachable | restore when possible | component:Dialog |
stable outcome |
Behavioral and layout contract
| ID | Candidate invariant | Basis | Draft review state |
|---|---|---|---|
| FR1 | A native Dialog MUST become visibly modal before Dialog applies its component-owned initial-focus request. | shipped showModal() ordering and descendant-focus behavior |
settled |
| FR2 | Dialog MUST honor an eligible descendant initial-focus request. A request is eligible only when its rendered target is inside the active Dialog, is neither hidden nor inert, and can receive programmatic focus when selection runs. DialogHeader supplies its title as the default when no non-default eligible request is rendered. Ordering among multiple non-default requests is unspecified (AV3). | shipped DialogHeader and descendant autofocus behavior | settled |
| FR3 | When no eligible descendant request exists, Dialog MUST preserve the native dialog's valid initial-focus behavior rather than move focus outside the modal. | native modal semantics and shipped fallback | settled |
| FR4 | Closing a native Dialog MUST return focus to the still-connected external element that invoked the modal when that element can receive focus. Descendant mount focus MUST NOT replace that return owner. | shipped trigger-return intent and regression history | settled |
| FR5 | Inline rendering MUST NOT open a modal, apply modal initial focus, trap focus, or return focus as if a modal had closed. | documented isInline preview behavior |
settled |
| FR6 | Initial-focus selection MUST follow the rendered eligible descendants, not a private component type or source-only assumption. | composable descendant contract | settled |
| FR7 | A native modal Dialog MUST be a focus region through Core's shared focus-region module: Tab from its last tabbable control moves focus to its first, and Shift+Tab from its first moves focus to its last, so focus never leaves the modal for the browser's own interface. When a Dialog opens from a Dialog, the innermost one holding focus answers Tab. | owner decision DEC-2 | settled |
| FR8 | A modal Dialog open on the server renders closed until hydration (no open styles, no aria-modal, the markup of a closed Dialog) and opens in the render after hydration, the first that can make it modal; it never claims a modality it does not have (spec:AST-020 FR1, WCAG 2.2 SC 4.1.2). An inline Dialog is not modal and renders as it is. The server and hydrating renders produce the same markup (spec:AST-013 FR9), and the open after hydration is settled, with no entry motion; later opens and closes animate as usual (spec:AST-013 FR13). |
spec:AST-020 FR1 |
settled |
| FR9 | On every pointer, the modal backdrop is the theme's --color-overlay dim with no blur (no backdrop-filter); under forced colors the dialog keeps a visible edge (a system-colour border) so it stays apart from the page. A full-screen Dialog (variant="fullscreen") covers the page and draws none. |
Owner decision, 2026-10-25: the overlay stays theme-controlled and unblurred on every pointer. | settled |
Allowed variation
- AV1 — Initial target. A form control, action, heading, or other eligible descendant may be the initial target when its owner exposes the supported intent.
- AV2 — No request. Browser-native selection may vary where no eligible request exists, provided focus does not escape the active modal.
- AV3 — Multiple requests. Callers should identify one intended initial target. Conflict ordering among multiple simultaneous requests is not a public API promise.
- AV4 — Unavailable invoker. Dialog MUST still close without error when the invoker was removed or can no longer receive focus; in that state it need not restore focus.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| native modal with DialogHeader | modal is visible before focus; title receives default focus | another earlier supported request may win |
| native modal with explicit descendant request | requested eligible descendant receives focus | descendant type and location |
| native modal without request | focus remains within valid native modal behavior | browser-selected eligible descendant |
| modal close | connected invoking element regains focus | no restoration when invoker is unavailable |
| Tab or Shift+Tab at the modal's edge | focus wraps to the other end inside the modal | which controls are tabbable |
| inline preview | surrounding page focus remains unchanged | inline content and layout |
Accessibility contract
- AR1 — Focus enters visible modal content. Initial focus MUST NOT target hidden pre-modal content or remain behind the active modal.
- AR2 — Focus returns to context. Closing a native Dialog MUST restore focus to its still-connected external invoking context when that context can receive focus.
- AR3 — The initial target remains perceivable. A programmatically focusable heading or control MUST preserve its accessible role, name, and operability.
Design relationships
Dialog focus timing and destination do not prescribe title styling, modal size, motion, or visual hierarchy. Those remain with Dialog's component design and theming owners. FR9 sets the backdrop's appearance.
Family and system relationships
family:overlay-dismissalowns which close request is accepted and ensures one Escape press affects only the topmost relevant layer.architecture:layer-runtimeowns modal layer ordering and shared lifecycle.architecture:react-component-runtimeowns node/resource replacement safety.architecture:interaction-modalityINV1 decides whether initial focus and the focus returned on close show the shared focus indicator; Dialog'sDialog.a11y.browser.spec.tsverifies both after pointer and keyboard input.- This component owns the destination and return outcome for Dialog's modal focus lifecycle.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR3, AR1 | shared modal-dialog binding in Dialog.a11y.test.tsx and Dialog.a11y.chromium.spec.ts; local DialogHeader focus tests |
header default, explicit descendant, no request | the shared contract fails when focus is applied before native modality, misses the declared target, or leaves the visible modal on native fallback | audit:Dialog/accessibility |
| FR4, AR2 | shared modal-dialog browser binding plus the local unavailable-invoker close test | external trigger, descendant mount focus, removed trigger | the shared contract records an exact current failure when descendant focus replaces the return owner; the local test keeps close safe after invoker removal | audit:Dialog/behavior |
| AR2 | Dialog.test.tsx "unmounting while open" cases |
dialog rendered only while open and unmounted by its own action; removed with its view; focus moved elsewhere first; StrictMode | focus left on the page body after an open dialog unmounts, or focus pulled back from where the user moved it, fails | audit:Dialog/behavior |
| FR5 | inline Dialog tests | DialogHeader and focusable children | inline preview steals focus or invokes native modal methods | audit:Dialog/behavior |
| FR6, AR3 | shared modal-dialog binding plus the local composed-action focus fixture | DialogHeader heading, TextInput, action button | focus depends on a private React child type or strips semantics from the target | audit:Dialog/public-api |
| FR7 | Dialog.test.tsx, AlertDialog.test.tsx and CommandPalette.test.tsx focus-region suites |
last and first tabbable control, Dialog in Dialog, inline | Tab from the last control leaves the modal, or an outer Dialog answers an inner one's Tab | audit:Dialog/accessibility |
| FR8 | Dialog.ssr.test.tsx |
Open on the server; hydration; a closed Dialog's markup | An open server render with aria-modal, open styles, or markup unlike a closed one, a hydration error, no showModal() after hydration, an entry motion on the open right after hydration, or none on a later open fails. |
audit:Dialog/accessibility |
| FR9 | modalBackdrop.test.tsx; ModalBackdrop.a11y.browser.spec.ts in Chromium and WebKit |
A finger at phone width; a mouse at desktop width; forced colors under either pointer; a full-screen Dialog in forced colors | A backdrop-filter on the backdrop at either width, no visible edge in forced colors, or an edge on a full-screen Dialog, fails. |
audit:Dialog/accessibility |
Decision log
DEC-1 — Dialog owns focus timing; descendants own focus intent
Reference: component:Dialog/DEC-1
Decider: pending owner review
Dialog waits until native modal presentation before applying the selected request. Descendant components own their supported focus intent; the DOM marker used today is implementation evidence, not a permanent or newly admitted public API.
DEC-2 — Every modal presentation is a focus region through one module
Reference: component:Dialog/DEC-2
Decider: cixzhang, 2026-10-28
A modal surface contains Tab the way the APG modal dialog pattern describes:
Tab and Shift+Tab move through the modal's controls and wrap at either end.
Core's shared focus-region module provides that containment: the Tab
containment useFocusTrap applies for Drawer and Popover. Each modal
presentation applies the same module instead of
leaving Tab to the browser: Dialog, and AlertDialog and CommandPalette through
it, a modal BottomSheet, Lightbox, and a modal Drawer. A fault in the wrapping
is fixed in that module, not worked around in a component. The one exception
is a step of the deprecated BottomSheetSwitcher (DEP-0015): it keeps native
containment under component:BottomSheetSwitcher/DEC-1.
Rejected: leaving Tab to native showModal(), which sends focus to the browser's own interface from inside a modal.
Open questions
None. DEC-2 settles focus containment.
Content boundary
This file does not duplicate Dialog's prop table, dismissal rules, visual design,
private focus marker, audit results, or implementation plan. Consumer syntax remains
in Dialog.doc.mjs; implementation remediation is separate from this contract.