An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-090): record exit motion as current, with layer exits in every supported browser (#8547)
Kenton Quatman32b916d75dd4
diff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.mdindex 0fc309ed77..cdda259f2d 100644--- a/docs/specs/AST-090-exit-motion/spec.md+++ b/docs/specs/AST-090-exit-motion/spec.md@@ -3,12 +3,12 @@ schema_version: 4template_version: 2kind: system-specid: spec:AST-090-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null-phase: proposed+approved_by: cixzhang+approved_at: 2026-10-28+phase: acceptedowners: [ernestt, cixzhang]affects_architecture: [architecture:theme-tokens, architecture:layer-runtime]affects_families: [family:overlay-dismissal]@@ -73,7 +73,8 @@ components read through two shared primitives is a system fact.- Exits of touch presentations, which each component's record gives under`spec:AST-094` FR7 and FR8 (FR14). The exit tokens here do not reach touch- motion, whose roles stay internal (`spec:AST-094` FR4, DEC-11).+ motion: its roles stay internal, and a theme reaches it only through+ `spec:AST-108`'s knobs (`spec:AST-094` FR4, DEC-15).- Surfaces that already animate out (`Drawer`, `BottomSheet`, `MobileNav`,`Toast`, and the `TopNavMegaMenu` panel) keep their exits, durations, andcurves. `BottomSheet`'s close in a pointer presentation reads `--ease-exit`@@ -91,8 +92,8 @@ components read through two shared primitives is a system fact.follow the `--ease-<job>` and `--duration-<job>` pattern so that vocabularycan join them without a rename.- Equivalent internal implementations remain valid when they satisfy this- contract. How a dialog stays open while it leaves, how a layer stays in the- top layer while it leaves, and how the end of an exit is detected are+ contract. How a dialog stays open while it leaves, how a leaving layer stays+ drawn where it was, and how the end of an exit is detected areimplementation.## Requirements@@ -117,7 +118,9 @@ governs them in a touch presentation.duration. A dialog shrinks back toward the element that opened it, ordownward when none did; a fullscreen dialog only fades; a layer shrinks backtoward its anchor, mirrored in right-to-left layouts as its entrance is. A- dialog's backdrop fades out over the same duration.+ dialog's backdrop fades out over the same duration. `--ease-exit` applies to+ CSS-timed exits; a spring-driven exit plays its own exit role, and a CSS part+ beside it takes the spring's settle time (`spec:AST-108` FR3, FR4a).- **FR4 — A leaving surface takes no input.** From the moment its close begins,no pointer press or key activates anything in a leaving surface's own content.Toasts that a leaving dialog hosts are not its content (FR13).@@ -129,7 +132,9 @@ governs them in a touch presentation.leaving passive dependent, such as `Tooltip`, stays passive and shieldsnothing (`spec:AST-003` FR4).- **FR6 — Focus leaves with the close.** A layer surface hands focus back when- its close begins, as it does with the exit off. A dialog surface returns focus+ its close begins, as it does with the exit off, and from then on its exit is+ hidden from assistive technology: a screen reader neither reads nor announces+ it. A dialog surface returns focusto the element that opened it when the dialog is hidden; until then the pagebehind the modal dialog cannot take focus.- **FR7 — Callbacks report the request.** `onOpenChange(false)`, `onHide`, and@@ -147,11 +152,10 @@ governs them in a touch presentation.`prefers-reduced-motion: reduce`, a dialog or layer surface in a pointerpresentation closes at once, whatever its kind's exit duration(`design:reduced-motion` DR3, DR4).-- **FR11 — Content stays while it leaves.** A surface keeps rendering the- content it showed when its close began until it is hidden. A component does- not unmount or reset its own content before its exit ends: a hover card's- lazily mounted content, a menu's open sub-menu path, and a selector's search- query keep their state until the surface is hidden.+- **FR11 — Content stays while it leaves.** A leaving surface keeps showing the+ content it showed when its close began until it is hidden: a hover card's+ content, a menu's open sub-menu, and a selector's search query stay on screen+ until the surface is hidden.- **FR12 — The exit vocabulary.** `--ease-exit` defaults to`cubic-bezier(0.3, 0, 0.6, 0.6)`, a curve that moves off slowly and leavesfast. Dialog and layer exits use it, and so does `BottomSheet`'s close in a@@ -177,14 +181,13 @@ governs them in a touch presentation.consumer doc.- This section covers pointer presentations; a touch exit follows`spec:AST-094`.-- Dialog exits play in every Tier 1 and Tier 2 browser.-- Layer exits play only in browsers that can keep a closing layer in the top- layer until its exit ends, which takes a transition of `overlay` with- `transition-behavior: allow-discrete`. In other browsers, and where the- Popover API is missing, a layer closes at once whatever its exit duration:- the same result as the exit off.-- Browser evidence: real-browser sampling of frames during an exit, in a browser- that plays layer exits and in one that does not.+- Dialog and layer exits play in every Tier 1 and Tier 2 browser.+- A layer whose exit cannot be drawn in the top layer, such as where the+ Popover API is missing, closes at once whatever its exit duration: the same+ result as the exit off.+- Browser evidence: real-browser sampling of frames during a dialog exit and a+ layer exit, in Chromium and WebKit, and a layer close where the Popover API+ is missing.## Current-state impact@@ -192,11 +195,16 @@ governs them in a touch presentation.`--duration-exit-dialog`, and `--duration-exit-layer` join the canonicalvocabulary, with their theme template and generated token documentationprojections (INV1, INV7).-- `architecture:layer-runtime`: a layer's close gains a leaving phase between- `hide()` and the moment the layer is hidden. Native close reconciliation stays- single-fired (INV6), and lazily mounted content unmounts when the exit ends.- A leaving Dialog keeps supplying its modal outlet until it is hidden (FR13);+- `architecture:layer-runtime`: a layer closes when its close is requested, as+ it does with the exit off, and its exit plays after that on the runtime's+ shared exit copy (INV14), drawn in the top layer where the layer was. Native+ close reconciliation stays single-fired (INV6). A leaving active or blocking+ owner keeps its place on the dismissal stack until its exit ends (FR5). A+ leaving Dialog keeps supplying its modal outlet until it is hidden (FR13);BottomSheet's outlet behavior does not change.+- `architecture:component-style-authoring`: no claim changes. A layer's exit+ is the one transient exit copy INV7 allows, made by the shared mechanism and+ removed when the exit ends (FR9).- `family:overlay-dismissal`: no claim changes. A leaving member stays presentfor FR2 until it is hidden, and animation stays member-owned (AV6).- `spec:AST-003`: no claim changes. A leaving surface keeps its interaction role@@ -204,9 +212,13 @@ governs them in a touch presentation.an owner (FR4, DEC-1). A leaving dialog is still the current native modal, soit keeps its outlet and toasts stay operable above it (FR16, FR18).- `spec:AST-094`: no claim changes. A touch presentation keeps the exit FR7 and- FR8 give it (FR14), and its motion roles stay internal (FR4, DEC-11). The exit+ FR8 give it (FR14), and its motion roles stay internal (FR4, DEC-15). The exittokens here time pointer presentations, which its non-goals leave to thetheme's duration and easing tokens.+- `spec:AST-108`: no claim changes. Its FR2 admits `--ease-exit` at the same+ curve at every `character`; a spring-driven exit plays its own exit role and+ a CSS part beside it takes the spring's settle time (FR3, FR4a); and an exit+ duration set as a reference to a tempo-scaled token follows `tempo` (FR5).- `design:reduced-motion`: no claim changes. Under reduced motion a pointerpresentation's exit completes at once (DR3, FR10), and a touch presentation'sexit cross-fades through `spec:AST-094` FR8 (DR2).@@ -219,8 +231,9 @@ governs them in a touch presentation.states when the return happens.- `component:Popover`: AR4 keeps its focus-return claim; FR6 states when thereturn happens for a layer.-- `component:BottomSheet`: its closing curve in a pointer presentation reads- `--ease-exit`.+- `component:BottomSheet`: its close in a pointer presentation reads+ `--ease-exit`. Its touch close keeps its own motion, which the exit tokens do+ not reach (`spec:AST-094` FR7, DEC-15).- Consumer docs: `motion` describes both curves, that exits are off by defaultin a pointer presentation, how a theme turns each kind on, that touchpresentations keep their native exits, and that callers keep content rendered@@ -229,30 +242,30 @@ governs them in a touch presentation.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |-| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |-| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |-| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |-| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving Tooltip over a Dialog | The owner beneath a leaving owner closes, or a leaving Tooltip absorbs the press |-| FR6 | Unit and real-browser focus tests | Dialog and layer closes, by keyboard and by pointer | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for exit |-| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |-| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |-| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |-| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |-| FR11 | Unit tests | Hover card content, an open sub-menu path, a selector query | Content unmounts or resets before the surface is hidden |-| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |-| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |-| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |-| Platform | Real-browser tests | A browser that plays layer exits and one that does not | A layer paints outside the top layer, or a browser without support delays the close |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |+| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |+| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |+| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |+| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving Tooltip over a Dialog | The owner beneath a leaving owner closes, or a leaving Tooltip absorbs the press |+| FR6 | Unit and real-browser focus and accessibility-tree tests | Dialog and layer closes, by keyboard and by pointer; the accessibility tree during a layer exit | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for the exit; a leaving layer's exit is in the accessibility tree |+| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |+| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |+| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |+| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |+| FR11 | Real-browser frame sampling during an exit | A hover card, a menu with an open sub-menu, a selector with a search query | The leaving surface shows other content, or none, before it is hidden |+| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |+| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |+| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |+| Platform | Real-browser tests in Chromium and WebKit | A dialog exit and a layer exit with each kind on; a layer close where the Popover API is missing | A layer exit paints outside the top layer or does not play, or a close without the Popover API is delayed |## Decision log### DEC-1 — Exits ship off, and a theme turns them on**Reference:** `spec:AST-090/DEC-1`-**Decider:** pending owner review+**Decider:** `cixzhang`, `2026-10-28`Turning exits on changes how every pointer-presented dialog and layer closes inevery product at once, so the capability ships switched off and a theme opts@@ -266,7 +279,7 @@ Rejected: an exit prop on each component, which restates timing at every call si### DEC-2 — One switch per kind of surface**Reference:** `spec:AST-090/DEC-2`-**Decider:** pending owner review+**Decider:** `cixzhang`, `2026-10-28`A person closes a dialog deliberately, and its exit shows what it uncovered. Alayer is dismissed as attention moves on, often many times a minute@@ -278,7 +291,7 @@ Rejected: one switch for every surface.### DEC-3 — An exit retraces its entrance on an accelerating curve**Reference:** `spec:AST-090/DEC-3`-**Decider:** pending owner review+**Decider:** `cixzhang`, `2026-10-28`An animated exit follows its entrance's path back, as the motion docs ask. Itruns on its own curve: a decelerating curve spends its travel in the first@@ -288,22 +301,27 @@ moves off from rest and leaves fast. `BottomSheet` closes on this curve, andRejected: the entrance played backwards on `--ease-standard`.-### DEC-4 — Layer exits play only where the browser holds a closing layer+### DEC-4 — A layer's exit plays where the layer was drawn**Reference:** `spec:AST-090/DEC-4`-**Decider:** pending owner review+**Decider:** `cixzhang`, `2026-10-28`-The browser hides a light-dismissed layer before Core hears of it, so only CSS-can animate that close. A layer that keeps painting after it leaves the top-layer paints in the wrong place. Where the browser cannot keep a closing layer-in the top layer, the layer closes at once, which is also the default.+The browser hides a light-dismissed layer before Core hears of it, so a layer's+exit cannot hold the live layer open. The exit plays on what the layer showed+when its close began, drawn in the top layer where the layer was, because a+layer that keeps painting outside the top layer paints in the wrong place.+The layer runtime's one shared exit copy draws it there+(`architecture:layer-runtime` INV14, `architecture:component-style-authoring`+INV7) in every browser with the Popover API, so layer exits play in every Tier+1 and Tier 2 browser; where it cannot be drawn, the layer closes at once, which+is also the default.-Rejected: replacing native light dismissal with Core-owned outside-press handling so every browser plays layer exits.+Rejected: holding the live layer in the top layer with an `overlay` transition, which plays only in browsers that support that transition.### DEC-5 — Touch presentations keep their native exit**Reference:** `spec:AST-090/DEC-5`-**Decider:** pending owner review+**Decider:** `cixzhang`, `2026-10-28`On a touch device a surface moves the way its native counterpart does, bydefault and with no opt-in (`spec:AST-094`), and that record leaves pointer