Skip to content

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

TypeScript

spec(AST-090): touch presentations keep their native exit (#8536)

Kenton Quatmanc4a9ae08dc02
diff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.md
index 2b2beab406..dcf138257c 100644
--- a/docs/specs/AST-090-exit-motion/spec.md
+++ b/docs/specs/AST-090-exit-motion/spec.md
@@ -39,13 +39,21 @@ review_triggers: [motion, tokens, layering, behavior, accessibility]
## Intent
A surface that animates in can animate out, so a person sees where it went and
-what it uncovered. Whether a kind of surface plays its exit is a theme decision:
-with no theme setting, every surface closes at once, as a surface without an
-exit does.
+what it uncovered. In a pointer presentation, whether a kind of surface plays
+its exit is a theme decision: with no theme setting, the surface closes at once,
+as a surface without an exit does. A touch presentation plays the exit of its
+native counterpart instead (`spec:AST-094` FR7), and the switches here do not
+reach it.
+
+A **touch presentation** is a presentation under a coarse primary pointer,
+after hydration, as `spec:AST-094` FR13 defines it. Every other presentation,
+including a server render and the hydrating render, is a **pointer
+presentation**.
This record owns the exit vocabulary, the switch that turns exits on for each
-kind of surface, how a surface behaves while it leaves, and the browsers in
-which layer exits play. Two kinds of surface gain an exit:
+kind of surface in a pointer presentation, how a pointer-presented surface
+behaves while it leaves, and the browsers in which its layer exits play. Two
+kinds of surface gain an exit:
- A **dialog surface** is a `Dialog`, including the dialogs that `AlertDialog`,
`CommandPalette`, `useImperativeDialog`, and `useImperativeAlertDialog`
@@ -63,11 +71,14 @@ components read through two shared primitives is a system fact.
## Non-goals
+- 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).
- Surfaces that already animate out (`Drawer`, `BottomSheet`, `MobileNav`,
`Toast`, and the `TopNavMegaMenu` panel) keep their exits, durations, and
- curves. `BottomSheet`'s close reads `--ease-exit` at the curve it uses
- (FR12); moving the others onto the exit vocabulary is a visual change for a
- separate decision.
+ curves. `BottomSheet`'s close in a pointer presentation reads `--ease-exit`
+ at the curve it uses (FR12); moving the others onto the exit vocabulary is a
+ visual change for a separate decision.
- Layers with no entrance (`Typeahead` suggestions, `MultiSelector`,
`Tokenizer`, the date and time pickers, the `TabList` overflow menu, the
`TopNav` and `SideNav` menus, and Chat trigger menus) gain no exit here.
@@ -86,6 +97,9 @@ components read through two shared primitives is a system fact.
## Requirements
+FR1–FR13 govern dialog and layer surfaces in a pointer presentation. FR14
+governs them in a touch presentation.
+
- **FR1 — Exits are off by default.** `--duration-exit-dialog` and
`--duration-exit-layer` default to `0ms`. A surface whose kind's exit
duration is zero closes at once: it is hidden in the update that closes it,
@@ -127,8 +141,9 @@ components read through two shared primitives is a system fact.
reports the end of its exit. That includes a page that disables animations and
transitions, and a surface that opens and closes in the same update.
- **FR10 — Reduced motion closes at once.** Under
- `prefers-reduced-motion: reduce`, every dialog and layer surface closes at
- once, whatever its kind's exit duration (`design:motion` DR5).
+ `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
@@ -136,7 +151,8 @@ components read through two shared primitives is a system fact.
query keep their state 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.
+ fast. Dialog and layer exits use it, and so does `BottomSheet`'s close in a
+ pointer presentation.
`--duration-exit` defaults to `var(--duration-fast)` and is the standard
dismissal duration. A theme turns a kind on by setting its exit duration to
`var(--duration-exit)` or to any other duration.
@@ -146,11 +162,18 @@ components read through two shared primitives is a system fact.
above it for the whole exit (`spec:AST-003` FR16). When it is hidden, they
move to the latest remaining outlet with their entries and timers intact
(`spec:AST-003` FR18, FR19).
+- **FR14 — Touch presentations keep their native exit.** A dialog or layer
+ surface in a touch presentation plays the exit its component's record gives
+ it under `spec:AST-094` FR7 and FR8. The exit switches, `--ease-exit`, and
+ `--duration-exit` do not change that exit: a theme that leaves a kind off
+ does not remove it, and a theme that turns a kind on does not replace it.
### Platform support
- Supported feature and engine floor: the tiers in the `browser-support`
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
@@ -177,6 +200,13 @@ components read through two shared primitives is a system fact.
(FR1), and a leaving passive dependent such as `Tooltip` still never shields
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
+ tokens here time pointer presentations, which its non-goals leave to the
+ theme's duration and easing tokens.
+- `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).
- `design:motion` (draft): exits apply DR1, DR2, and DR5. This record holds the
exit tokens and behavior that its content boundary leaves to other records.
- `component:Dialog`: its `visibility` concept (open, closed) gains a leaving
@@ -186,30 +216,33 @@ components read through two shared primitives is a system fact.
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 reads `--ease-exit`.
-- Consumer docs: `motion` describes both curves, that exits are off by default,
- how a theme turns each kind on, and that callers keep content rendered while a
- surface closes. The token tables and the theme template list the new tokens,
- and each member component's docs describe its exit.
+- `component:BottomSheet`: its closing curve in a pointer presentation reads
+ `--ease-exit`.
+- 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
+ while a surface closes. The token tables and the theme template list the new
+ tokens, and each member component's docs describe its exit.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member, opened and closed | A surface stays rendered after its close with default tokens |
-| FR2 | Real-browser test under a theme that sets one kind | 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 | 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 |
-| 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 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 |
## Decision log
@@ -218,12 +251,12 @@ components read through two shared primitives is a system fact.
**Reference:** `spec:AST-090/DEC-1`
**Decider:** pending owner review
-Turning exits on changes how every dialog and layer closes in every product at
-once, so the capability ships switched off and a theme opts in: the same place
-that tunes motion through its motion scale. The switches are tokens because an
-exit's timing is an implementation value, not a per-call concept
-(`spec:AST-002` FR3), and because a prop cannot reach the layers that other
-components compose, such as every `tooltip` prop.
+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
+in: the same place that tunes motion through its motion scale. The switches are
+tokens because an exit's timing is an implementation value, not a per-call
+concept (`spec:AST-002` FR3), and because a prop cannot reach the layers that
+other components compose, such as every `tooltip` prop.
Rejected: an exit prop on each component, which restates timing at every call site and misses composed layers; exits on by default, which changes every overlay in one release.
@@ -264,12 +297,26 @@ in the top layer, 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.
+### DEC-5 — Touch presentations keep their native exit
+
+**Reference:** `spec:AST-090/DEC-5`
+**Decider:** pending owner review
+
+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
+presentations' timing and easing to the theme's tokens. The switches here
+therefore govern pointer presentations only, and a touch presentation keeps
+its native exit whatever they resolve to.
+
+Rejected: letting the exit switches turn touch exits off, which removes the exit `spec:AST-094` FR7 requires.
+
## Open questions
-- **OQ1 — Whether a dialog's exit ships on, and at which duration**
- (`human-design`). Options: keep it off; default `--duration-exit-dialog` to
- `var(--duration-exit)`; or default it to a duration from the entrance band,
- because a person who closes a dialog deliberately watches it go.
+- **OQ1 — Whether a pointer-presented dialog's exit ships on, and at which
+ duration** (`human-design`). Options: keep it off; default
+ `--duration-exit-dialog` to `var(--duration-exit)`; or default it to a
+ duration from the entrance band, because a person who closes a dialog
+ deliberately watches it go.
- **OQ2 — Whether elements in page flow gain an exit kind** (`human-design`).
`FieldStatus` and `useEntryAnimation` animate in and vanish when removed. An
exit would keep a validation message in the layout while it leaves, which