Skip to content

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

TypeScript

spec(Dialog): every modal presentation is a focus region through one module (DEC-2) (#8882)

Cindy Zhang248380ebd2fb
diff --git a/packages/core/src/AlertDialog/AlertDialog.spec.md b/packages/core/src/AlertDialog/AlertDialog.spec.md
index 61304aab15..28cb26d010 100644
--- a/packages/core/src/AlertDialog/AlertDialog.spec.md
+++ b/packages/core/src/AlertDialog/AlertDialog.spec.md
@@ -155,8 +155,8 @@ intentional decision. A `current` contract contains no unresolved rows.
the modal surface is `role="alertdialog"`, named by its title through
`aria-labelledby` and described by its description through `aria-describedby`;
it is modal through Dialog (focus enters it and returns to the opener on close
- per `component:Dialog/AR1–AR2`; Tab containment follows Dialog, whose record
- leaves it open); initial
+ per `component:Dialog/AR1–AR2`, and Tab wraps inside it per
+ `component:Dialog/FR7`); initial
focus lands on Cancel, the least destructive action; Escape cancels; no click
outside dismisses it. The inline preview is not an alert dialog and carries
`role="group"`.
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index 382c1a90c7..0a52aa06a3 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -162,6 +162,7 @@ remain documented in `BottomSheet.doc.mjs`.
| FR13 | Every open scrim sheet supplies its dialog as a passive global outlet for app-global surfaces such as toasts (`spec:AST-003` FR18: each active native modal, a covered sheet included), and a modal `BottomSheetSwitcher` flow supplies its active step's dialog — the one its host dialog resolves to, following each handoff; the retained step's dialog, inert and fading, never hosts. Among sheets, the latest outlet — the one a global host renders into — follows the stack's order, not the order the sheets were supplied in: the top sheet is the latest, so a toast lands in the top sheet and never in a covered, inert one, and when the top sheet closes the sheet it reveals is the latest again and takes the host back. A sheet is raised only among sheet outlets: an outlet supplied later by another modal (a `Dialog` opened from a sheet) stays above every sheet until it closes. A sheet, or a flow, stops supplying as soon as it starts closing, and a native `close` event that fires while its dialog is open again (the stack re-showing it, or a reopen during its exit) does not take its outlet away. | DEC-2; `spec:AST-003/FR16`, `/FR18`; `architecture:layer-runtime`; `component:BottomSheetSwitcher/FR10` |
| FR14 | When a non-modal sheet enters the top layer, a top-layer toast viewport shown before it leaves and re-enters the top layer in place, keeping focus inside it, so toasts paint above the sheet. | DEC-2; `architecture:layer-runtime` |
| FR15 | Under `prefers-reduced-motion: reduce` the recede, the return from receded, a push's entrance, a pop's exit and the replace handoff — and a `BottomSheetSwitcher` step's, which shares the sheet panel's motion — follow `design:reduced-motion`, keyed on its queries (`prefers-reduced-motion: reduce`, with `pointer: coarse` for the cross-fade): no transform motion runs (DR1) — a covered sheet appears in its receded place and size the frame the push lands and returns the same way, the entering sheet appears in its final place, the retained sheet does not align down; on a coarse pointer the entering sheet fades in and the leaving or retained sheet fades out where it is, opacity only, in 200 ms or less (DR2); a dismissal the release of a touch drag started (a swipe past the dismiss line) fades out in place the same way on every pointer (DR2's drag-release clause); on any other pointer every other change is immediate (DR3); the handoff's steps run in the released order, so the retained sheet is hidden and its dialog closed once its fade ends. The constant page dim through a push, a pop and a handoff (FR6) holds as it does with motion. | DEC-2; `design:reduced-motion` |
+| FR16 | An open modal sheet is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): in the top sheet, Tab from the last tabbable control moves focus to the first and Shift+Tab from the first moves focus to the last, so focus never leaves the sheet for the browser's own interface. A covered or closing sheet does not answer Tab, and a non-modal sheet contains nothing (FR11). | `component:Dialog/DEC-2` |
### Allowed variation
@@ -379,6 +380,7 @@ a decision that they must remain unthemeable.
| FR5–FR9, FR12–FR15, AR3–AR5 | Stacking unit suite (jsdom, native dialog methods stubbed); real-browser per-frame sampling of transforms, backdrop opacity, hit-testing, and focus on the stacking stories in Chromium, WebKit, and real Safari; a real-browser accessibility-tree check (`spec:AST-020`, `spec:AST-009` FR3) that a lone sheet, a stack of two and three, and a replace handoff expose exactly one `dialog`, the top or entering sheet, with its name, while covered and replaced sheets are hidden, that the stack renders no live region of its own, and that focus enters the entering step's `data-autofocus` field or panel on a replace; a real-browser run with reduced motion emulated on a fine and on a coarse pointer, sampling per frame that no transform animates, that the covered sheet is in its receded place from the frame the push lands, that on a coarse pointer the entering and leaving sheets change opacity only within 200 ms and on a fine pointer at once, that a swipe dismissal fades out in place on a fine pointer, that the dim is constant and that the handoff still completes | siblings, separate components, nested in content, inside a switcher step, a switcher flow as a level, out-of-tree-order opens, same-update deep link, depth 1–3, Escape/scrim/swipe/platform close, covered close, close of the whole stack, focus after each pop, two package copies, a second document | A covered or replaced sheet is exposed in the accessibility tree, the top sheet is exposed without role `dialog` or its name, a covered sheet stays interactive, a second backdrop paints, the dim dips or doubles on a handoff, a dismissal reaches a covered sheet, a nested sheet's state is written or it stays open invisibly, or focus lands on `body` after a pop or a close of the whole stack. | `audit:BottomSheet/behavior` |
| FR10–FR11 | Replace unit suite (jsdom); real-browser parity of the standalone flow against the switcher's handoff — per-frame transforms, opacity, page dim, focus, settled pixels — in Chromium and WebKit, and real Safari for hosting, dim, toast order, and focus; a per-engine lone-open focus probe in Chromium, Firefox and WebKit comparing the sheet's focus on open against that engine's bare `show()` and `showModal()` on the same markup, and recording the focus and blur events the sheet's first control receives on open (none) | push, pop, different updates, covered close, nested, a replace above a covered sheet (the bottom sheet keeps the scrim, the retained sheet only fades), switcher flow, a lone sheet; handoff in both completion orders; reversal mid-handoff in both directions and both tree orders; unrelated owners from a page control; non-modal replace, reversal, `show()` fallback; a non-modal sheet opened from a modal sheet or a `Dialog` and rendered outside it (while the modal is open, and once it has closed, with positioned page content), one opened in the update that closes a modal sheet, and one rendered inside the modal's content | A replace is recognized for unrelated owners or missed for a real step flow, the retained sheet is exposed or dismissable, the scrim dips, the replaced step stays on screen after a reversal, focus does not enter the step or return to the flow's opener, a non-modal sheet carries a page-level `z-index`, a toast paints under a non-modal sheet, or a lone sheet's focus on open, modal or not, differs from where that engine's released native host (`showModal()`, or `show()` for a non-modal sheet) puts it — in Chromium the panel, with a ring only after keyboard input and a `data-autofocus` field left unfocused; in Firefox the first focusable control — a control inside the sheet receives a focus or a blur on a lone open that `show()` would not have given it, or a replacement entry fails to focus its `data-autofocus` field. A non-modal sheet rendered outside an open modal paints above it while a press lands on the modal, or stays beneath page content once that modal has gone. | `audit:BottomSheet/behavior` |
| FR13–FR14 | Toast viewport hosting suite (jsdom, native dialog methods and popover state stubbed); real-browser hit-testing of a toast raised from the top sheet, from a Dialog opened from a sheet after an inner sheet closed, from a sheet re-shown by a reversal, and over a non-modal sheet | a lone sheet; a stack of two; sheet → Dialog → sheet → close the inner sheet; a reversal and a reopen during exit, with the stale native `close`; a non-modal sheet shown after the viewport; a modal switcher flow alone, through a handoff and its close; a flow stacked over a standalone sheet and a standalone sheet over a flow; a non-modal flow | A toast renders in a covered or inert sheet, a Dialog opened from a sheet loses the toast to the sheet beneath it, a re-shown sheet loses its outlet to the stale `close`, a toast raised from a switcher step lands behind the flow or in its retained step, or a toast paints beneath a non-modal sheet. | `audit:BottomSheet/behavior` |
+| FR16 | `BottomSheet.test.tsx` focus-region suite | Modal and non-modal sheets; Tab and Shift+Tab at the sheet's edge | Tab from the last control leaves a modal sheet, or a non-modal sheet captures Tab | `audit:BottomSheet/accessibility` |
Existing tests directly assert the Sheet panel target, Content area placement,
Handle structure, and scrim behavior. Source and public target metadata confirm
diff --git a/packages/core/src/Dialog/Dialog.spec.md b/packages/core/src/Dialog/Dialog.spec.md
index 22cea528cc..12e82e4519 100644
--- a/packages/core/src/Dialog/Dialog.spec.md
+++ b/packages/core/src/Dialog/Dialog.spec.md
@@ -89,6 +89,7 @@ current family and architecture owners.
| 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 |
### Allowed variation
@@ -110,6 +111,7 @@ current family and architecture owners.
| 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
@@ -147,6 +149,7 @@ component design and theming owners.
| 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 |
| 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 |
## Decision log
@@ -159,12 +162,25 @@ Dialog waits until native modal presentation before applying the selected reques
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.
+
+Rejected: leaving Tab to native `showModal()`, which sends focus to the browser's own interface from inside a modal.
+
## Open questions
-- **Dialog focus containment.** Should native modal Dialog adopt APG forward and
- reverse Tab wrapping as a required public behavior? Current authority owns focus
- entry and return but does not settle this containment mechanic, so the shared
- contract does not gate it.
+None. DEC-2 settles focus containment.
## Content boundary
diff --git a/packages/core/src/Lightbox/Lightbox.spec.md b/packages/core/src/Lightbox/Lightbox.spec.md
index 4be20e55ec..0ccf9e0065 100644
--- a/packages/core/src/Lightbox/Lightbox.spec.md
+++ b/packages/core/src/Lightbox/Lightbox.spec.md
@@ -72,11 +72,12 @@ in `Lightbox.doc.mjs`.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | Verified current reachability; no target change |
-| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets. | Current source and target docs | Verified current delegation; no ownership change |
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | Verified current reachability; no target change |
+| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets. | Current source and target docs | Verified current delegation; no ownership change |
+| FR4 | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. | `component:Dialog/DEC-2` | Owner decision; tests land with the implementation |
### Allowed variation
@@ -106,9 +107,9 @@ in `Lightbox.doc.mjs`.
## Accessibility contract
-This draft does not change or extend Lightbox's existing dialog naming, focus,
-media alternatives, announcements, button labels, keyboard behavior, or
-dismissal behavior.
+Apart from Tab containment (FR4), this draft does not change or extend
+Lightbox's existing dialog naming, focus, media alternatives, announcements,
+button labels, keyboard behavior, or dismissal behavior.
## Design relationships