Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(Dialog): define modal focus lifecycle (#6144)

Cindy Zhang87a0f717e0bc
diff --git a/packages/core/src/Dialog/Dialog.spec.md b/packages/core/src/Dialog/Dialog.spec.md
new file mode 100644
index 0000000000..dfcbe98828
--- /dev/null
+++ b/packages/core/src/Dialog/Dialog.spec.md
@@ -0,0 +1,163 @@
+---
+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,
+ ]
+modules: []
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+ [
+ architecture:layer-runtime,
+ architecture:public-component-api,
+ architecture:react-component-runtime,
+ ]
+contributing: []
+system_specs: []
+---
+
+# 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-dismissal` and `architecture: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 |
+
+### 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 |
+| 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, backdrop appearance, or visual hierarchy. Those remain with Dialog's
+component design and theming owners.
+
+## Family and system relationships
+
+- `family:overlay-dismissal` owns which close request is accepted and ensures one
+ Escape press affects only the topmost relevant layer.
+- `architecture:layer-runtime` owns modal layer ordering and shared lifecycle.
+- `architecture:react-component-runtime` owns node/resource replacement safety.
+- 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 | Dialog and DialogHeader focus tests plus native-dialog browser evidence | header default, explicit descendant, no request | focusing before modal visibility or removing descendant focus leaves focus outside visible modal content | audit:Dialog/accessibility |
+| FR4, AR2 | trigger capture/return regression tests | external trigger, descendant mount focus, removed trigger | descendant focus replaces the return owner or close fails to restore a connected trigger | 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 | composed descendant focus fixtures | heading, input, action | focus depends on a private React child type or strips semantics from the target | audit:Dialog/public-api |
+
+## 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.
+
+## Open questions
+
+None.
+
+## 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.