Skip to content

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.md
index 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: 4
template_version: 2
kind: system-spec
id: spec:AST-090
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
-phase: proposed
+approved_by: cixzhang
+approved_at: 2026-10-28
+phase: accepted
owners: [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, and
curves. `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 vocabulary
can 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 are
implementation.
## Requirements
@@ -117,7 +118,9 @@ governs them in a touch presentation.
duration. A dialog shrinks back toward the element that opened it, or
downward when none did; a fullscreen dialog only fades; a layer shrinks back
toward 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 shields
nothing (`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 focus
to the element that opened it when the dialog is hidden; until then the page
behind 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 pointer
presentation 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 leaves
fast. 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 canonical
vocabulary, with their theme template and generated token documentation
projections (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 present
for 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, so
it 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 exit
tokens here time pointer presentations, which its non-goals leave to the
theme'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 pointer
presentation's exit completes at once (DR3, FR10), and a touch presentation's
exit 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 the
return 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 default
in a pointer presentation, how a theme turns each kind on, that touch
presentations 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 in
every 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. A
layer 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. It
runs 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, and
Rejected: 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, by
default and with no opt-in (`spec:AST-094`), and that record leaves pointer