An open source design system that's fully customizable and agent ready
TypeScript
docs(AST-094, AST-057): motion guidance; gesture springs; swipe-row returns (#9915)
Cindy Zhang257573b22686
diff --git a/docs/specs/AST-057-row-actions/spec.md b/docs/specs/AST-057-row-actions/spec.mdindex 34341870b1..ee70d4a4dd 100644--- a/docs/specs/AST-057-row-actions/spec.md+++ b/docs/specs/AST-057-row-actions/spec.md@@ -54,7 +54,7 @@ review_triggers: [public-api, accessibility, behavior]| Area | Contract || ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || Public contract | `Item` carries swipe actions for a finger, a pen, and horizontal wheel input through one prop, `swipe`, whose value comes from `createSwipe({leading?, trailing?, swipeBehavior?})` (DEC-8). Each side declares the verbs a sideways drag uncovers as `SwipeAction[]` — `label`, `icon`, `onActivate`, `variant`, `hasRemoval` — and `Item` renders the panel from them (DEC-1). `swipeBehavior` is `reveal` (rest open) or `commit` (fire on release) (DEC-2). The swipe's code lives in the constructor's module, so an app that never imports `createSwipe` ships none of it (FR10). The capability is `Item`'s, available on any row whose role permits interactive descendants — a `listitem`, a role-less row — and out of scope where it does not (`option`, `menuitem*`, a radio) (DEC-3). No hover reveal and no mouse-drag swipe (DEC-4); a trackpad's horizontal scroll swipes as a finger does (DEC-7). No new DOM: the row's root translates and its panels counter-translate (DEC-5). |-| Behavior | A sideways drag by a finger or a pen, or a horizontal wheel gesture, moves the row and uncovers the side's panel. Under `reveal` (default) the row rests open so each action is tappable and a long drag fires the outermost; under `commit` the row slides out and the outermost fires; nothing rests. After an action fires the row springs back, or holds out when the action has `hasRemoval` — one bit the component cannot infer, independent of the model. The component waits for nothing afterwards. A short release springs back under both. A mouse never starts the drag; a mostly vertical drag stays the scroller's; a pointer anywhere outside a resting row closes it. |+| Behavior | A sideways drag by a finger or a pen, or a horizontal wheel gesture, moves the row and uncovers the side's panel. Under `reveal` (default) the row rests open so each action is tappable and a long drag fires the outermost; under `commit` the row slides out and the outermost fires; nothing rests. After an action fires the row returns, or holds out when the action has `hasRemoval` — one bit the component cannot infer, independent of the model. The component waits for nothing afterwards. A short release springs back under both. A mouse never starts the drag; a mostly vertical drag stays the scroller's; a pointer anywhere outside a resting row closes it. || End-user impact | A person on a phone gets the flick they expect on a mail row or a settings row, with the row's own look. A pen, or a trackpad's horizontal scroll, swipes the row the same way; a mouse drag, a keyboard, or a screen reader meets the row exactly as today. || Builder impact | One prop on `Item` (and so on `ListItem`), `swipe={createSwipe({trailing: [{label: 'Archive', icon: <Icon icon={ArchiveIcon} />, onActivate: archive, hasRemoval: true}]})}`; optionally `swipeBehavior` in the same options. Every field is known before the gesture begins, so the component paints the panel from data. The group around the rows clips in the inline axis — `List` does it; any other host does it once. The consumer documentation states that a verb reachable only by swipe is unreachable by keyboard. || Compatibility/readiness | `swipe` is absent by default; every row without it keeps its DOM and paint exactly. The released `swipeActions` and `swipeBehavior` props and their `ItemSwipe*` types are deprecated in a patch with no runtime warning (DEP-0017) and removed in 0.8.0 (CLN-0025); the `astryx upgrade` codemod that rewrites them to `swipe={createSwipe(…)}` is an opt-in early migration from the deprecating patch on, and 0.8.0's upgrade runs it again with the removal. Implementation gap: `swipe` and `createSwipe` are not built (Current-state impact). |@@ -143,11 +143,10 @@ and its panels stay put, so no element is added to any row.`render*`-shaped addition can land when a caller needs something thevocabulary cannot say (DEC-1).- **Gesture tuning.** Axis-lock distance, commit ratio, fling velocity,- resistance past the panel, and the slides and springs a swipe drives:- behavior constants in source, not public API and not design tokens (the- same ruling the touch press model received for its clocks). A close that a- tap or Escape starts plays the theme's exit tokens (FR7, `spec:AST-094`- FR45).+ resistance past the panel, and the slides and springs a swipe drives: behavior+ constants in source, not public API and not design tokens (the same ruling the+ touch press model received for its clocks). A close that a tap or Escape+ starts plays the row's spring from rest (FR7, `spec:AST-094` FR45).- **Vertical swipes**, and a swipe whose onlymeaning is dismissal (Toast already has that in `useToastGesture`).- **Public out-of-flow slots on `Item`.** Deliberately not admitted: the@@ -205,12 +204,12 @@ and its panels stay put, so no element is added to any row.| Case | Served | How || ---------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || Mail: archive and delete | Yes | Two entries in `trailing`, both `hasRemoval`, Delete `variant: 'destructive'`. Under `reveal` the panel rests open with both; a long drag fires the outermost; the row holds out and the caller removes it. |-| One destructive action | Yes | One entry with `variant: 'destructive'` and, if it removes the row, `hasRemoval`. Under `commit` the row slides out and it fires; it holds out or springs back by the bit. |-| Reversible toggle (read/unread, pin/flag) | Yes | `label` names the state the verb reaches ("Unread"); no `hasRemoval`. Under `reveal` the row springs back wearing it; under `commit` it slides out, fires, and springs back wearing it. |+| One destructive action | Yes | One entry with `variant: 'destructive'` and, if it removes the row, `hasRemoval`. Under `commit` the row slides out and it fires; it holds out or returns by the bit. |+| Reversible toggle (read/unread, pin/flag) | Yes | `label` names the state the verb reaches ("Unread"); no `hasRemoval`. Under `reveal` the row returns wearing it; under `commit` it slides out, fires, and returns wearing it. || Archive — removes the row but is not destructive | Yes | `hasRemoval` without `variant: 'destructive'`. The axes are independent: all four combinations occur (DEC-1). |-| Soft delete with Undo — destructive but row stays | Yes | `variant: 'destructive'` without `hasRemoval`: the row springs back. |+| Soft delete with Undo — destructive but row stays | Yes | `variant: 'destructive'` without `hasRemoval`: the row returns. || More than two actions | Yes | N entries on a side, outermost last. Under `reveal` each is a button. |-| An action that confirms or opens a chooser | Yes | No `hasRemoval`: the row springs back and `onActivate` opens the dialog; the caller removes the row on confirmation. A verb with no single instant (snooze) commits to opening its chooser. |+| An action that confirms or opens a chooser | Yes | No `hasRemoval`: the row returns and `onActivate` opens the dialog; the caller removes the row on confirmation. A verb with no single instant (snooze) commits to opening its chooser. || Rows in a virtualized list | Yes | Open state is the row's own; a row that unmounts takes it along. A mostly vertical drag stays the scroller's (FR6). || Rows that are links (`href`) | Yes | The axis lock separates the drag from the tap, and the click the browser synthesizes after a drag is swallowed (FR6). || `role="list"` rows | Yes | `ListItem` inherits the prop; arbitrary interactive children are valid. |@@ -246,19 +245,19 @@ constants.### Behavioral contract-| ID | Invariant | Basis | Verification state |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------- |-| FR1 | `Item` MUST take its swipe actions as one prop, `swipe`, whose value is the `Swipe` that `createSwipe(options)` returns, where `options` is `{leading?: readonly SwipeAction[]; trailing?: readonly SwipeAction[]; swipeBehavior?: SwipeBehavior}` and `SwipeAction` is `{id?, label: string, icon?: ReactNode, onActivate, isDisabled?, variant?: 'neutral' \| 'accent' \| 'destructive', hasRemoval?: boolean}` with `variant` defaulting to `accent`. An entry MUST NOT carry a node the component renders as the control. `Swipe` MUST be opaque, made only by `createSwipe`. `ListItem` MUST pass `swipe` through unchanged. The deprecated `swipeActions` and `swipeBehavior` props follow DEP-0017. | DEC-1, DEC-8; `DropdownMenu.items` data mode | Proposed |-| FR2 | `Item` MUST render each side's panel from its entries into an out-of-flow position on its existing root and MUST add no element to the row for it. The gesture MUST drive the row's travel by writing a custom property on the root; the root's transform MUST read it and each panel's transform its negation. | DEC-5; `useToastGesture` | Proposed; real-Chromium evidence required |-| FR3 | `swipeBehavior` MUST be one closed union, `SwipeBehavior`, with the values `reveal` and `commit`, default `reveal`, applying to both sides. `commit` with more than one entry on a side MUST warn in development, because the other entries have no touch path. | DEC-2 | Proposed |-| FR4 | A sideways drag by a finger or a pen, or a horizontal wheel gesture, MUST move the row and uncover the side's panel, showing each entry's `label` and `icon` as a filled surface in its `variant`'s colour; while a full swipe is confirmed (FR5) the outermost entry alone MUST cover the uncovered space; the panel MUST NOT be visible at rest, by any pixel. | Real-browser finding: a zero-width panel still paints its padding | Proposed; real-Chromium evidence required |-| FR5 | Under `reveal`, a release goes by its speed first: at the release speed or faster it opens the row while the row is opening and closes it while it is closing; a slower one opens the row past half the panel's width and closes it short of that. Speed alone MUST NOT fire an entry. Dragged past the confirm point, the row MUST run ahead toward its far edge with the outermost entry covering its place while the finger stays down; a lift still past the confirm point MUST fire the **outermost** entry and no other, at any speed; a swipe that confirmed and came back short of the confirm point MUST close the row and fire nothing; a disabled outermost entry MUST NOT confirm. Under `commit`, only a lift past the confirm point MUST slide the row out and fire the outermost entry; every other release closes; nothing MUST rest. After any entry fires, under either model, the row MUST return unless the entry has `hasRemoval`, in which case it MUST hold out at the edge it travelled toward. When a swipe fired the entry, the return is gesture-driven and springs from the release velocity; when a tap on the entry fired it, the return is tap-started and plays the theme's exit duration and easing, `--duration-exit` and `--ease-exit` (`spec:AST-094` FR45). That bit is the only thing an entry declares about the row; the component MUST NOT wait on, observe, or act on what the caller does next, and MUST NOT warn if a held-out row is never removed. A release short of the threshold MUST spring back under both models. Under reduced motion the slide out, the spring back, and the hold-out follow `design:reduced-motion`: the row reaches its resting place with no travel or spring and cross-fades (DR2) when a finger started the swipe, or, when a pen or a trackpad did, cross-fades on a coarse primary pointer (DR2) and arrives at once otherwise (DR3). `onActivate` MUST fire once the row's content has left its box, and may return a Promise. | DEC-1, DEC-2; UIKit `performsFirstActionWithFullSwipe` | Proposed; real-device evidence required |-| FR6 | The drag MUST decide its axis once, early, and a mostly vertical drag MUST stay the scroller's. A mouse MUST NOT start the drag. The click the browser synthesizes after a drag MUST NOT fire the row's primary action. | Press-model ORD1 | Proposed; real-device evidence required |-| FR7 | An open row (resting open, or settling open from the release that opened it) MUST close on a pointer landing anywhere outside it, on a touch tap on its own content, on a scroll of anything that holds it while focus is outside its open panel, on Escape with focus inside it, on firing an entry, and on unmount. That tap MUST activate nothing and paint no press, an exception to the cell press profile of `spec:AST-094` FR11. Because a drag on a neighbour is a pointer outside it, at most one row is open at a time without any shared state. A close that a tap, a pointer outside, a scroll, Escape, a fired entry's tap or the program starts plays the theme's exit duration and easing, `--duration-exit` and `--ease-exit`; a close a swipe drives keeps its measured spring from the release velocity (`spec:AST-094` FR45). Implementation gap: the shipped row settles every close on one 200 ms ease-out today. | DEC-3; SwiftUI `swipeActionsContainer()` for the outcome | Proposed |-| FR8 | Directions MUST be logical: `trailing` is uncovered by a drag toward the inline start and sits at the inline end; `leading` the reverse; so the finger, the uncovered edge, and the panel agree under RTL. | `architecture:public-component-api` INV2 (logical direction) | Proposed |-| FR9 | The element containing swipe-capable rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`. `List` MUST set it; `Item`'s consumer documentation MUST state the obligation for any other host. | DEC-5; `List` root styles | Proposed |-| FR10 | The `createSwipe` module MUST import every module the swipe runs on — the shared gesture core, the animator, the panels' rendering, and the row's gesture code — statically. `Item` and `ListItem` MUST import none of these swipe modules and MUST NOT load them with `import()`; the touch modules `Item` uses for other jobs, such as press feedback, are outside this rule. DEP-0017 makes one exception, `Item`'s deprecated path, which serves the deprecated props only and leaves with CLN-0025 in 0.8.0: the released loader, which loads the swipe code with `import()` the first time a row has `swipeActions`; the released row style `Item` applies from that row's first render; the released role gate and `commit` warning; the bridge the loaded layer fills, the click guard that reads it, and the event forwarders from the row's root into it; and the development-only coexistence diagnostic when `swipe` and a deprecated prop are both given. An app that never imports `createSwipe` therefore loads no swipe code unless a row uses the deprecated props, and a row given `swipe` is swipeable at its first paint. Importing or calling `createSwipe` MUST do no DOM work. | DEC-8; `architecture:public-component-api` INV19; `architecture:react-component-runtime` INV13 | Proposed |-| FR11 | A caller MAY call `createSwipe` inline in a render. A new `Swipe` value MUST NOT close an open row, restart a settle, or attach the gesture again; the row reads the latest value's entries and handlers, so a handler sees the caller's latest state, and a changed entry list repaints the panel. | DEC-8 | Proposed |+| ID | Invariant | Basis | Verification state |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1 | `Item` MUST take its swipe actions as one prop, `swipe`, whose value is the `Swipe` that `createSwipe(options)` returns, where `options` is `{leading?: readonly SwipeAction[]; trailing?: readonly SwipeAction[]; swipeBehavior?: SwipeBehavior}` and `SwipeAction` is `{id?, label: string, icon?: ReactNode, onActivate, isDisabled?, variant?: 'neutral' \| 'accent' \| 'destructive', hasRemoval?: boolean}` with `variant` defaulting to `accent`. An entry MUST NOT carry a node the component renders as the control. `Swipe` MUST be opaque, made only by `createSwipe`. `ListItem` MUST pass `swipe` through unchanged. The deprecated `swipeActions` and `swipeBehavior` props follow DEP-0017. | DEC-1, DEC-8; `DropdownMenu.items` data mode | Proposed |+| FR2 | `Item` MUST render each side's panel from its entries into an out-of-flow position on its existing root and MUST add no element to the row for it. The gesture MUST drive the row's travel by writing a custom property on the root; the root's transform MUST read it and each panel's transform its negation. | DEC-5; `useToastGesture` | Proposed; real-Chromium evidence required |+| FR3 | `swipeBehavior` MUST be one closed union, `SwipeBehavior`, with the values `reveal` and `commit`, default `reveal`, applying to both sides. `commit` with more than one entry on a side MUST warn in development, because the other entries have no touch path. | DEC-2 | Proposed |+| FR4 | A sideways drag by a finger or a pen, or a horizontal wheel gesture, MUST move the row and uncover the side's panel, showing each entry's `label` and `icon` as a filled surface in its `variant`'s colour; while a full swipe is confirmed (FR5) the outermost entry alone MUST cover the uncovered space; the panel MUST NOT be visible at rest, by any pixel. | Real-browser finding: a zero-width panel still paints its padding | Proposed; real-Chromium evidence required |+| FR5 | Under `reveal`, a release goes by its speed first: at the release speed or faster it opens the row while the row is opening and closes it while it is closing; a slower one opens the row past half the panel's width and closes it short of that. Speed alone MUST NOT fire an entry. Dragged past the confirm point, the row MUST run ahead toward its far edge with the outermost entry covering its place while the finger stays down; a lift still past the confirm point MUST fire the **outermost** entry and no other, at any speed; a swipe that confirmed and came back short of the confirm point MUST close the row and fire nothing; a disabled outermost entry MUST NOT confirm. Under `commit`, only a lift past the confirm point MUST slide the row out and fire the outermost entry; every other release closes; nothing MUST rest. After any entry fires, under either model, the row MUST return unless the entry has `hasRemoval`, in which case it MUST hold out at the edge it travelled toward. When a swipe fired the entry, the return is gesture-driven and springs from the release velocity; when a tap on the entry fired it, the return plays the row's spring from rest, since a swipe row's main interaction is a gesture (`spec:AST-094` FR45). That bit is the only thing an entry declares about the row; the component MUST NOT wait on, observe, or act on what the caller does next, and MUST NOT warn if a held-out row is never removed. A release short of the threshold MUST spring back under both models. Under reduced motion the slide out, the spring back, and the hold-out follow `design:reduced-motion`: the row reaches its resting place with no travel or spring and cross-fades (DR2) when a finger started the swipe, or, when a pen or a trackpad did, cross-fades on a coarse primary pointer (DR2) and arrives at once otherwise (DR3). `onActivate` MUST fire once the row's content has left its box, and may return a Promise. | DEC-1, DEC-2; UIKit `performsFirstActionWithFullSwipe` | Proposed; real-device evidence required |+| FR6 | The drag MUST decide its axis once, early, and a mostly vertical drag MUST stay the scroller's. A mouse MUST NOT start the drag. The click the browser synthesizes after a drag MUST NOT fire the row's primary action. | Press-model ORD1 | Proposed; real-device evidence required |+| FR7 | An open row (resting open, or settling open from the release that opened it) MUST close on a pointer landing anywhere outside it, on a touch tap on its own content, on a scroll of anything that holds it while focus is outside its open panel, on Escape with focus inside it, on firing an entry, and on unmount. That tap MUST activate nothing and paint no press, an exception to the cell press profile of `spec:AST-094` FR11. Because a drag on a neighbour is a pointer outside it, at most one row is open at a time without any shared state. A swipe row's main interaction is a gesture, so every close plays the row's spring (`spec:AST-094` FR45): a close that a tap, a pointer outside, a scroll, Escape, a fired entry's tap or the program starts plays the same settle as a swipe close, from rest, and a close a swipe drives starts from the release velocity. Implementation gap: the shipped row settles every close on one 200 ms ease-out today. | DEC-3; SwiftUI `swipeActionsContainer()` for the outcome | Proposed |+| FR8 | Directions MUST be logical: `trailing` is uncovered by a drag toward the inline start and sits at the inline end; `leading` the reverse; so the finger, the uncovered edge, and the panel agree under RTL. | `architecture:public-component-api` INV2 (logical direction) | Proposed |+| FR9 | The element containing swipe-capable rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`. `List` MUST set it; `Item`'s consumer documentation MUST state the obligation for any other host. | DEC-5; `List` root styles | Proposed |+| FR10 | The `createSwipe` module MUST import every module the swipe runs on — the shared gesture core, the animator, the panels' rendering, and the row's gesture code — statically. `Item` and `ListItem` MUST import none of these swipe modules and MUST NOT load them with `import()`; the touch modules `Item` uses for other jobs, such as press feedback, are outside this rule. DEP-0017 makes one exception, `Item`'s deprecated path, which serves the deprecated props only and leaves with CLN-0025 in 0.8.0: the released loader, which loads the swipe code with `import()` the first time a row has `swipeActions`; the released row style `Item` applies from that row's first render; the released role gate and `commit` warning; the bridge the loaded layer fills, the click guard that reads it, and the event forwarders from the row's root into it; and the development-only coexistence diagnostic when `swipe` and a deprecated prop are both given. An app that never imports `createSwipe` therefore loads no swipe code unless a row uses the deprecated props, and a row given `swipe` is swipeable at its first paint. Importing or calling `createSwipe` MUST do no DOM work. | DEC-8; `architecture:public-component-api` INV19; `architecture:react-component-runtime` INV13 | Proposed |+| FR11 | A caller MAY call `createSwipe` inline in a render. A new `Swipe` value MUST NOT close an open row, restart a settle, or attach the gesture again; the row reads the latest value's entries and handlers, so a handler sees the caller's latest state, and a changed entry list repaints the panel. | DEC-8 | Proposed |### Accessibility contract@@ -302,10 +301,10 @@ constants.## Current-state impact-- Implementation gap (FR5, FR7): the shipped row settles every close on one- 200 ms ease-out today, where `spec:AST-094` FR45 has a close that a tap or- Escape starts play `--duration-exit` and `--ease-exit` and a close a swipe- drives keep its measured spring.+- Implementation gap (FR5, FR7): the shipped row settles every close on one 200+ ms ease-out today, where `spec:AST-094` FR45 has every close and return play+ the row's spring: from rest when a tap or Escape starts it, and from the+ release velocity when a swipe drives it.- Implementation gap: `swipe`, `createSwipe`, and the types`SwipeAction`, `SwipeActionVariant`, `SwipeBehavior`,`CreateSwipeOptions`, and `Swipe` are not built. `Item`@@ -349,7 +348,7 @@ constants.| FR1, FR3 | `Item` and `ListItem` prop-surface suites plus exported-type checks | One, two, and four entries per side; every `variant` × `hasRemoval` combination; `commit` with two entries on a side; `Swipe` built by hand | A field with a node the row renders as the control, a silent multi-entry `commit`, a `Swipe` a caller can build without `createSwipe`, or `ListItem` reshaping the prop fails. || FR2 | `Item` DOM snapshot suite plus real-Chromium evidence | No swipe actions; one side; both sides; each render mode (`onClick`, `href`, delegation, parent role); mid-drag | A new element in any row, a changed DOM on an existing row, a panel that moves with the row, or a panel painted under the root's background or over the content fails. || FR4–FR6, FR8 | Real-Chromium dispatched-touch evidence plus physical-device check; RTL via the direction provider | Rest; a slow release short of and past half the panel; a fast release opening and closing from a short drag; a confirmed full swipe lifted, backed out, and on a disabled outermost entry; a flick under `commit`; both models; both sides; `hasRemoval` and plain entries under each; vertical drag; mouse drag; RTL; a trackpad's horizontal scroll and a mouse's horizontal wheel; a mouse drag, which must not swipe; a pen drag | A resting sliver, a fire from speed alone, a backed-out swipe that fires or rests open, a disabled outermost entry that confirms, a confirmed swipe whose outermost entry does not cover the row, `onActivate` before the row's content has left its box, a rest under `commit`, the wrong entry fired, a plain entry that holds out, a `hasRemoval` entry that springs back, a warning on a held-out row, or a mirrored panel fails. |-| FR7 | `Item` suite with two rows under one parent | Open one, drag the other; outside tap; a touch tap on the open row's content; a tap while the row settles open; a scroll of the list and of the page with focus outside the open panel and with focus inside it; Escape; entry fired; unmount | Two rows open, a row that stays open after any closing event, a tap on an open row's content that activates the row or paints a press, or a scroll that closes the row while focus is inside its open panel, fails. |+| FR7 | `Item` suite with two rows under one parent | Open one, drag the other; outside tap; a touch tap on the open row's content; a tap while the row settles open; a scroll of the list and of the page with focus outside the open panel and with focus inside it; Escape; entry fired; unmount | Two rows open, a row that stays open after any closing event, a tap on an open row's content that activates the row or paints a press, a scroll that closes the row while focus is inside its open panel, a swipe close that starts from rest instead of the release velocity, or a tap, Escape or program close on a curve instead of the row's settle spring, fails. || FR9 | `List` style assertion plus real-Chromium evidence of a row dragged past the edge | A row at the list's inline edge mid-drag; the list scrolled vertically | A horizontal scrollbar, the row painting past the list, or `hidden` where `clip` is specified fails. || FR10 | The touch-support bundle guard (main's checks plus one entry for `createSwipe`) and a module-attribution check: each public import built with the pull-request size report's esbuild options (minified ESM, code splitting, metafile), with every byte of the JavaScript the import loads eagerly — its entry output and the chunks it reaches by static import — attributed to its source module from the metafile's per-module bytes in output; the check lists those modules and their gzipped share, base against head | `Item` alone; `ListItem` alone; `Item` with `createSwipe`; every public import that renders an `Item` row; a server import of `createSwipe` | Any bytes in the eager output of `Item` alone or `ListItem` alone attributed to a swipe module — the gesture core, the animator, the panels' rendering, or the row's gesture code; a swipe module imported by `Item` or `ListItem`; an `import()` reachable from `Item` other than DEP-0017's released loader; swipe code in `Item` other than DEP-0017's deprecated path (FR10's list: the loader, the row style, the role gate, the `commit` warning, the bridge, the click guard, the event forwarders, and the coexistence diagnostic) and the `swipe` handoff, which reads the value and hands the row's root to the runtime it carries, or any of the deprecated path outside the deprecated props; or DOM work on importing or calling `createSwipe` fails. Growth of `Item` alone or `ListItem` alone attributed to `Item`'s own modules, from the deprecated path and the handoff, is reported and fails nothing; the released loader's `import()` target is a separate chunk outside the eager output. || FR11 | `Item` suite re-rendering with a new `Swipe` value | Closed, resting open, and settling; the same entries; a changed entry list; a changed handler | A new value that closes the row, restarts the settle, or attaches the gesture again, a stale handler, or a panel that keeps the old entries fails. |diff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.mdindex 0ee7f03228..1cc6e5d0f3 100644--- a/docs/specs/AST-090-exit-motion/spec.md+++ b/docs/specs/AST-090-exit-motion/spec.md@@ -72,18 +72,20 @@ 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 switches here do not reach- touch exits; a touch exit that a tap, a key or the program starts plays- `--duration-exit` and `--ease-exit`, and a gesture-driven exit keeps its- velocity spring (FR14).+ `spec:AST-094` FR7 and FR8 (FR14). The exit switches here do not reach touch+ exits; in a component whose main interaction is a tap, a touch exit that a+ tap, a key or the program starts plays `--duration-exit` and `--ease-exit`; in+ a gesture component, such as a sheet or the Lightbox, every exit plays its+ spring, and a gesture-driven exit starts from the release velocity (FR14).- Surfaces that already animate out (`Drawer`, `BottomSheet`, `MobileNav`,- `Toast`, and the `TopNavMegaMenu` panel) keep their durations and curves in- a pointer presentation, and for an exit a gesture drives, a swipe or a drag- with velocity, which keeps its measured spring. In a touch presentation, an exit that a tap, a- key or the program starts plays `--duration-exit` and `--ease-exit` (FR14),- `BottomSheet`'s close included. `BottomSheet`'s close in a pointer- presentation reads `--ease-exit` at the curve it uses (FR12); moving the- others' pointer-presentation exits onto the exit vocabulary is a visual+ `Toast`, and the `TopNavMegaMenu` panel) keep their durations and curves in a+ pointer presentation, and for an exit a gesture drives, a swipe or a drag with+ velocity, which keeps its measured spring. In a touch presentation, an exit+ that a tap, a key or the program starts plays `--duration-exit` and+ `--ease-exit` in a tap component, and the component's spring in a gesture+ component, `BottomSheet`'s close included (FR14). `BottomSheet`'s close in a+ pointer presentation reads `--ease-exit` at the curve it uses (FR12); moving+ the others' pointer-presentation exits onto the exit vocabulary is a visualchange for a separate decision.- Layers with no entrance (`Typeahead` suggestions, `MultiSelector`,`Tokenizer`, the date and time pickers, the `TabList` overflow menu, the@@ -180,14 +182,16 @@ governs them in a touch presentation.above it for the whole exit (`spec:AST-003` FR16). When it is hidden, theymove to the latest remaining outlet with their entries and timers intact(`spec:AST-003` FR18, FR19).-- **FR14 — Touch exits are never removed; tap-started exits play the theme's exit timing.** 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. A touch presentation's exit that a+- **FR14 — Touch exits are never removed; a tap component's tap-started exits+ play the theme's exit timing.** 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. In a+ component whose main interaction is a tap, a touch presentation's exit that atap, key or program starts plays the theme's exit duration and easing,- `--duration-exit` and `--ease-exit` (`spec:AST-094` FR7); a gesture-driven- exit keeps its velocity spring. The exit switches 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.+ `--duration-exit` and `--ease-exit`; in a gesture component, such as a sheet+ or the Lightbox, that exit plays the component's spring from rest, and a+ gesture-driven exit keeps its velocity spring (`spec:AST-094` FR7, FR45). The+ exit switches 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@@ -232,8 +236,9 @@ governs them in a touch presentation.it keeps its outlet and toasts stay operable above it (FR16, FR18).- `spec:AST-094`: a touch presentation keeps the exit FR7 and FR8 give it(FR14). One that a tap, a key or the program starts plays `--duration-exit`- and `--ease-exit`, and one a gesture drives keeps its velocity spring- (`spec:AST-094` FR7, FR45, DEC-26).+ and `--ease-exit` in a tap component and the component's spring in a gesture+ component, and one a gesture drives keeps its velocity spring (`spec:AST-094`+ FR7, FR45, DEC-26).- `spec:AST-108`: no claim changes. Its FR2 admits `--ease-exit` at the samecurve at every `character`; a spring-driven exit plays its own exit role anda CSS part beside it takes the spring's settle time (FR3, FR4a); and an exit@@ -251,16 +256,18 @@ governs them in a touch presentation.- `component:Popover`: AR4 keeps its focus-return claim; FR6 states when thereturn happens for a layer.- `component:BottomSheet`: its close in a pointer presentation reads- `--ease-exit`. In a touch presentation, a close that a tap, a key or the- program starts plays `--duration-exit` and `--ease-exit`, and a swipe or a- drag that closes it keeps its measured spring (`spec:AST-094` FR7, FR45).- Implementation gap: a coarse-pointer close started by a tap or key plays- `--duration-medium` today.+ `--ease-exit`. BottomSheet is a gesture component: in a touch presentation, a+ close that a tap, a key or the program starts plays the sheet's spring from+ rest, and a swipe or a drag that closes it keeps its measured spring from the+ release (`spec:AST-094` FR7, FR45). Implementation gap: a coarse-pointer close+ started by a tap or key plays `--duration-medium` today.- Consumer docs: `motion` describes both curves, that exits are off by default- in a pointer presentation, how a theme turns each kind on, that a touch- exit is never removed and a tap-started one plays the theme's exit timing, 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.+ in a pointer presentation, how a theme turns each kind on, that a touch exit+ is never removed, that a tap component's tap-started one plays the theme's+ exit timing, and that a sheet's and the Lightbox's touch close springs (FR14),+ 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@@ -340,20 +347,21 @@ is also the default.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 exits are never removed; tap-started exits play the theme's exit timing+### DEC-5 — Touch exits are never removed; a tap component's tap-started exits play the theme's exit timing**Reference:** `spec:AST-090/DEC-5`**Decider:** `cixzhang`, `2026-10-28`-On a touch device a surface keeps the look of its native counterpart, by-default and with no opt-in (`spec:AST-094`). That record springs only motion-a gesture drives and gives every other motion, under every pointer, the-theme's tokens (`spec:AST-094` FR45). The switches here govern whether a-pointer presentation's exit plays, and a touch presentation keeps its exit-whatever they resolve to. A touch exit that a tap, a key or-the program starts plays the theme's exit duration and easing,-`--duration-exit` and `--ease-exit`, and a gesture-driven exit keeps its-velocity spring (`spec:AST-094` DEC-26).+On a touch device a surface keeps the look of its native counterpart, by default+and with no opt-in (`spec:AST-094`). That record springs the motion of a+component whose main interaction is a gesture and gives a tap component's+tap-started motion, under every pointer, the theme's tokens (`spec:AST-094`+FR45). The switches here govern whether a pointer presentation's exit plays, and+a touch presentation keeps its exit whatever they resolve to. In a tap+component, a touch exit that a tap, a key or the program starts plays the+theme's exit duration and easing, `--duration-exit` and `--ease-exit`; in a+gesture component it plays the component's spring, and a gesture-driven exit+keeps its velocity spring (`spec:AST-094` FR45, DEC-26).Rejected: letting the exit switches turn touch exits off, which removes the exit `spec:AST-094` FR7 requires.diff --git a/docs/specs/AST-094-touch-presentations/motion-roles.md b/docs/specs/AST-094-touch-presentations/motion-roles.mdindex 509282902b..0353725e08 100644--- a/docs/specs/AST-094-touch-presentations/motion-roles.md+++ b/docs/specs/AST-094-touch-presentations/motion-roles.md@@ -2,7 +2,7 @@# Motion roles-Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. A role plays only for motion a gesture drives (`spec:AST-094` FR45). Motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Three approved motions keep their springs until their own records change: the layout glide (`spec:AST-105` FR4), the animator's `animate` (`spec:AST-107` FR3), and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.+The owner's goal: "The main goals are consistent timings and well-coordinated pieces." The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: "The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion." A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.| Role | Kind | Default | Named by || ------------------------------- | -------- | --------------------------------------------------------------- | ----------------------- |diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 61c58159b7..00379f4087 100644--- a/docs/specs/AST-094-touch-presentations/spec.md+++ b/docs/specs/AST-094-touch-presentations/spec.md@@ -39,15 +39,15 @@ affects_consumer_docs: []## IntentA person using an Astryx product on a phone or tablet gets controls, sheets,-menus, lists and navigation with native-feeling touch behavior: measured-physics and gesture thresholds instead of desktop motion stretched to a-finger. What a person drags follows their hand, and what they throw settles on-a spring from the speed of the throw, under every pointer. Motion that a tap,-a click, a hold, a key or the program starts plays the theme's motion tokens-(FR45).-This behavior is the default on every touch device, iOS and Android alike,-with no opt-in, and its motion keeps running at display rate while the page's-JavaScript is busy.+menus, lists and navigation with native-feeling touch behavior: measured physics+and gesture thresholds instead of desktop motion stretched to a finger. What a+person drags follows their hand, and what they throw settles on a spring from+the speed of the throw, under every pointer. In a component whose main+interaction is a tap, motion that a tap, a click, a hold, a key or the program+starts plays the theme's motion tokens; in a component whose main interaction is+a gesture, it settles on the component's springs (FR45). This behavior is the+default on every touch device, iOS and Android alike, with no opt-in, and its+motion keeps running at display rate while the page's JavaScript is busy.The behavior comes from one measured table. Its values are measured from UIKiton a named reference release, UIKit on iOS 26.2 today; each number names the@@ -59,15 +59,15 @@ a measured, sourced difference exists.## Non-goals-- The timing and easing of motion that no gesture drives. Motion that a tap,- a click, a hold, a key or the program starts, such as an entrance, a move- or a change of value, plays the theme's duration and easing tokens- (`architecture:theme-tokens`) under every pointer, a finger included- (FR45). A touch presentation's exit that no gesture drives keeps its look- and plays the theme's exit duration and easing, and no exit switch removes- it (FR7, `spec:AST-090` FR14). Gestures, press tracking, a part that follows a- pointer, and the spring that settles a gesture apply to every pointer- (FR43, FR45).+- The timing and easing of tap-started motion in a component whose main+ interaction is a tap. In such a component, motion that a tap, a click, a hold,+ a key or the program starts, such as an entrance, a move or a change of value,+ plays the theme's duration and easing tokens (`architecture:theme-tokens`)+ under every pointer, a finger included (FR45). Such a component's touch exit+ that no gesture drives keeps its look and plays the theme's exit duration and+ easing, and no exit switch removes it (FR7, `spec:AST-090` FR14). Gestures,+ press tracking, a part that follows a pointer, and the spring that settles a+ gesture apply to every pointer (FR43, FR45).- Platform-matched look and feel: glass versus material surfaces, glyphs andchrome. This record governs behavior, and touch sizing only as FR42 states.- WebKit embedded in a native app and the native Swift package. This record@@ -84,17 +84,17 @@ a measured, sourced difference exists.### Physics-- **FR1 — Measured values, the same everywhere.** Every spring, duration- and deceleration rate that a gesture's motion plays (FR45), and every rubber-band coefficient, gesture threshold, input- timing and haptic moment a touch presentation uses MUST default to the- measured native value for that use (FR2), and every component that plays- the same motion or gesture MUST use the same value; a theme reaches the- roles only through its motion knobs (FR4, DEC-15). Motion that no gesture- drives plays the theme's duration and easing tokens, not a measured value- (FR45, DEC-26).- No component uses a value of its own where a measured value exists. The same- values apply on every touch platform; a platform gets a value of its own only- where a measured, sourced difference exists (FR2).+- **FR1 — Measured values, the same everywhere.** Every spring, duration and+ deceleration rate that a gesture's motion plays (FR45), and every rubber-band+ coefficient, gesture threshold, input timing and haptic moment a touch+ presentation uses MUST default to the measured native value for that use+ (FR2), and every component that plays the same motion or gesture MUST use the+ same value; a theme reaches the roles only through its motion knobs (FR4,+ DEC-15). In a component whose main interaction is a tap, motion that no+ gesture drives plays the theme's duration and easing tokens, not a measured+ value (FR45, DEC-26). No component uses a value of its own where a measured+ value exists. The same values apply on every touch platform; a platform gets a+ value of its own only where a measured, sourced difference exists (FR2).- **FR2 — Every value has a source.** Each measured value MUST name its source next to it: Apple's documentation, a WWDC session, WebKit's ownsource where WebKit states it matches UIKit, or a measurement of UIKit onthe iOS simulator naming the app, the iOS version, the method and the date.@@ -140,32 +140,37 @@ a measured, sourced difference exists.310.7–329.9 pt/s; releases at rest stay at 45–48.5 % and advance at55–57.5 % (DEC-25).- **FR4 — Touch motion uses named roles.** Every spring, duration and curve a- touch presentation plays for a gesture (FR45) MUST be a motion role named for its use- (`architecture:theme-tokens` INV3). The roles this record names are listed below with their defaults and- sources; further roles a component's own record measures join through the- generated motion role table (DEC-5). With tempo 1 and character- standard, every role plays its measured value exactly (FR1, FR2); a theme's- tempo scales durations and its character offsets bounce through fixed- per-role weights (`spec:AST-108` FR3), and roles on the fixed list ignore- both: the on-screen keyboard (`spec:AST-099` FR8); gesture thresholds, the- content-touch delay, and momentum (`spec:AST-002` FR3); finger tracking, the- rubber band, the press model's onset delay, cancel distance, and tap flash- (`spec:AST-108` FR4), and busy loops; and the 200 ms Reduce Motion cap.- The per-role tables stay internal (DEC-15). A component MUST read touch motion through these roles- and MUST NOT play a literal. A theme's knob values MUST reach the motion at its- start, without changing how the motion runs (FR5, FR6). Motion that- must stay in step with the on-screen keyboard is not a theme role: it rides- the keyboard's own motion (`spec:AST-099` FR8,- `architecture:react-component-runtime` INV11). Gesture thresholds, the timings that decide who gets a touch (the- content-touch delay, the scroll brake, momentum memory), hold durations,- flick speeds and haptics are measured input values, not motion: they are- not motion roles, they stay internal and are not public concepts (`spec:AST-002` FR3),- except the `flickThreshold` a product passes to `spec:AST-107`'s snap-point- drag. The three knobs join the motion configuration of- `architecture:theme-authoring-contract` and `architecture:theme-tokens`- (`spec:AST-108`). It departs from the draft `design:motion` DR3- wherever the native motion settles with an overshoot or stretches with a- rubber band.+ touch presentation plays for a gesture (FR45) MUST be a motion role named for+ its use (`architecture:theme-tokens` INV3), with one exception. A+ gesture-driven exit (a release that closes or dismisses) may play a spring+ measured from the platform reference without a named motion role (FR45); its+ component's motion table lists that spring with its platform source. Every+ other gesture-driven motion plays a motion role. The roles this record names+ are listed below with their defaults and sources; further roles a component's+ own record measures join through the generated motion role table (DEC-5). With+ tempo 1 and character standard, every role plays its measured value exactly+ (FR1, FR2); a theme's tempo scales durations and its character offsets bounce+ through fixed per-role weights (`spec:AST-108` FR3), and roles on the fixed+ list ignore both: the on-screen keyboard (`spec:AST-099` FR8); gesture+ thresholds, the content-touch delay, and momentum (`spec:AST-002` FR3); finger+ tracking, the rubber band, the press model's onset delay, cancel distance, and+ tap flash (`spec:AST-108` FR4), and busy loops; and the 200 ms Reduce Motion+ cap. The per-role tables stay internal (DEC-15). A component MUST read touch+ motion through these roles and MUST NOT play a literal, apart from that+ measured gesture-driven exit spring. A theme's knob values MUST reach the+ motion at its start, without changing how the motion runs (FR5, FR6). Motion+ that must stay in step with the on-screen keyboard is not a theme role: it+ rides the keyboard's own motion (`spec:AST-099` FR8,+ `architecture:react-component-runtime` INV11). Gesture thresholds, the timings+ that decide who gets a touch (the content-touch delay, the scroll brake,+ momentum memory), hold durations, flick speeds and haptics are measured input+ values, not motion: they are not motion roles, they stay internal and are not+ public concepts (`spec:AST-002` FR3), except the `flickThreshold` a product+ passes to `spec:AST-107`'s snap-point drag. The three knobs join the motion+ configuration of `architecture:theme-authoring-contract` and+ `architecture:theme-tokens` (`spec:AST-108`). It departs from the draft+ `design:motion` DR3 wherever the native motion settles with an overshoot or+ stretches with a rubber band.| Role | Default | Source || ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |@@ -194,26 +199,37 @@ a measured, sourced difference exists.The three `springs.contextMenu*` rows are measured for ContextMenu's lift,and `component:ContextMenu` owns them (DEC-5).- A role plays only for motion a gesture drives (FR45): a release's settle, a- flick, a pan's or a pinch's settle, a rubber band's return, and a follow.- The theme's `tempo` scales a gesture's spring's duration and its+ In a component whose main interaction is a tap, a role plays only for motion a+ gesture drives: a release's settle, a flick, a pan's or a pinch's settle, a+ rubber band's return, and a follow. In a component whose main interaction is a+ gesture, its roles also settle the moves a tap, a key or the program starts+ (FR45). The theme's `tempo` scales a gesture's spring's duration and its`character` offsets the role's measured bounce by the role's fixed weight- (`spec:AST-108` FR3); the follow itself and- the rubber band stay fixed (`spec:AST-108` FR4). The rows measured for- motion that a tap, a hold, a key or the program starts, an exit included- (`springs.menuOpen`, `springs.menuClose`, `springs.subMenuOpen`,- `springs.subMenuBack`, the three `springs.contextMenu*` rows, `timing.stateChangeMs`,- `timing.curves.entrance` and `timing.curves.move`) stay as the measured- native reference, and no motion plays them: that motion plays the theme's- duration and easing tokens (FR45), and an exit plays the theme's exit- duration and easing (FR7). Three approved motions keep their springs until their own records change: the layout glide (`spec:AST-105` FR4), the animator's `animate` (`spec:AST-107` FR3), and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. A component's own record states which of- its roles a gesture drives.-- Implementation gap: the pager's measured settle after a release (DEC-25)- plays from internal constants and is not yet a named role. Its animated- scroll to a page that the program asks for is a programmatic move, so it- plays the theme's duration and easing tokens (FR45); today it plays a- 300 ms scroll on a sinusoidal curve.+ (`spec:AST-108` FR3); the follow itself and the rubber band stay fixed+ (`spec:AST-108` FR4). The rows measured for motion that a tap, a hold, a key+ or the program starts, an exit included (`springs.menuOpen`,+ `springs.menuClose`, `springs.subMenuOpen`, `springs.subMenuBack`, the three+ `springs.contextMenu*` rows, `timing.stateChangeMs`, `timing.curves.entrance`+ and `timing.curves.move`) stay as the measured native reference. No motion+ that a tap, a hold, a key or the program starts in a component whose main+ interaction is a tap plays them: that motion plays the theme's duration and+ easing tokens (FR45), and an exit plays the theme's exit duration and easing+ (FR7). Two approved motions keep their springs until their own records change:+ the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s+ `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are+ tap-started layout motion and play the theme's curve tokens (`spec:AST-105`+ FR4). Reduce Motion substitutions and continuous busy loops (such as+ ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their+ named roles; they are neither gesture- nor interaction-started motion. A+ component's own record states which of its roles a gesture drives.++ The pager's measured settle after a release (DEC-25) is not an exit, so FR4's+ exception does not cover it. Implementation gap: it plays UIKit's measured+ settle without a named role, and it doesn't yet follow `tempo` or `character`+ (usePager calls solvePaging with no theme input). Implementation gap: the+ pager is a gesture component, so its animated scroll to a page that the+ program asks for settles on the pager's spring from rest (FR45); today it+ plays a 300 ms scroll on a sinusoidal curve.Implementation gap: the sheet picker wheel's snap rate (UIKit's measuredpicker deceleration) plays from an internal constant and is not yet a named@@ -246,41 +262,106 @@ a measured, sourced difference exists.change during a drag starts from rest (DEC-25). On a starved page, aretarget may skip ahead by up to the browser's commit delay(start-at-call).-- **FR7 — Exits keep the native counterpart's look.** A touch presentation- MUST play an exit with the look of its UIKit counterpart's exit, on every- touch platform: a menu shrinks into its trigger, and an alert fades. An- exit that a tap, a key, an outside press or the program starts plays the- theme's exit duration and easing, `--duration-exit` and `--ease-exit`- (`spec:AST-090` FR14, FR45); an exit that a gesture drives keeps its spring- from the release velocity (FR38, FR45). The theme's exit switches never- remove a touch exit (`spec:AST-090` FR14). FR8 governs their reduced-motion- form. Each overlay's own record states its exit, since members own their- animation (`family:overlay-dismissal` AV6).-- **FR45 — A gesture's motion springs; other motion plays the theme's- motion tokens.** Motion that a gesture drives MUST play a spring, or for- a coast its measured deceleration rate, that starts at the gesture's- velocity, under every pointer (FR43). A gesture is- a continuous pointer movement whose velocity carries into the motion: a- drag, a flick, a swipe, a pan, a pinch, and the settle and rubber-band- return after any of them. The theme's `tempo` scales the spring's duration- and its `character` offsets the role's measured bounce by the role's fixed- weight (`spec:AST-108` FR3); the follow- and the rubber band themselves stay fixed (`spec:AST-108` FR4). A part that- follows a pointer follows it under every pointer (FR43). Every other- motion, which a tap, a click, a hold, a key or the program starts, MUST- play the theme's motion tokens, its duration and easing tokens scaled by+- **FR7 — Exits keep the native counterpart's look.** A touch presentation MUST+ play an exit with the look of its UIKit counterpart's exit, on every touch+ platform: a menu shrinks into its trigger, and an alert fades. In a component+ whose main interaction is a tap, an exit that a tap, a key, an outside press+ or the program starts plays the theme's exit duration and easing,+ `--duration-exit` and `--ease-exit` (`spec:AST-090` FR14, FR45). A component+ whose main interaction is a gesture, such as a sheet or the Lightbox, plays+ every exit on its spring: a close that a tap, a key, an outside press or the+ program starts plays the same settle as a swipe close, from rest, and an exit+ that a gesture drives starts from the release velocity (FR38, FR45). The+ theme's exit switches never remove a touch exit (`spec:AST-090` FR14). FR8+ governs their reduced-motion form. Each overlay's own record states its exit,+ since members own their animation (`family:overlay-dismissal` AV6).+- **FR45 — A component's main interaction picks springs or the theme's motion+ tokens.** A component whose main interaction is a gesture plays springs for+ its motion, including moves a tap starts inside it (a tap on a sheet detent or+ a close button settles on the same spring), so its pieces stay coordinated. A+ component whose main interaction is a tap plays the theme's curve tokens+ (duration and easing, scaled by `tempo`), never a spring, since a tap carries+ no velocity; no character or option plays a platform-measured curve for it+ (owner decision, 2026-11-04). Gesture-driven motion where the release velocity+ matters plays a spring that starts at the gesture's velocity (the settle, a+ fling, the rubber-band return), or for a coast its measured deceleration rate+ from that velocity, under every pointer (FR43). In a component whose main+ interaction is a tap, a motion a tap, key or the program starts whose record+ names no duration step, and for which the platform has a measured duration,+ plays the theme duration token whose value in the Storybook theme (neutral) is+ nearest that measurement, with the easing for its kind (entrance, exit or+ move); the measured value stays a reference in the component's motion table. A+ motion whose record names its step keeps it: a tap-started overlay exit plays+ `--duration-exit` and `--ease-exit` (FR7); an in-place toggle cross-fade is+ not an exit, and `component:ProgressBar` FR4's fill keeps `--duration-medium`.+ In a tap component, small anchored surfaces (a popover, a menu, a toggle, a+ row) and full-screen surfaces (a Dialog, an AlertDialog) each take their own+ platform measurement; no kind of motion without a named step defaults to one+ duration step. Springs follow the theme's `tempo`: tempo scales a spring's+ speed and leaves its bounce unchanged. Each spring pairs with a timing tier,+ so its settle and its companion curves finish together: menu springs with+ `--duration-medium-min`, sheet and sub-menu springs with `--duration-medium`,+ settle and emphasis springs with `--duration-medium-max`. In a tap component,+ quick taps and presses keep timing tokens and no spring. At tempo 1, every+ measured spring keeps its platform feel (owner decision, 2026-11-04). A+ gesture is a continuous pointer movement whose velocity carries into the+ motion: a drag, a flick, a swipe, a pan, a pinch, and the settle and+ rubber-band return after any of them. The theme's `tempo` scales the spring's+ duration and its `character` offsets the role's measured bounce by the role's+ fixed weight (`spec:AST-108` FR3); the follow and the rubber band themselves+ stay fixed (`spec:AST-108` FR4). A part that follows a pointer follows it+ under every pointer (FR43). In a component whose main interaction is a tap,+ every other motion, which a tap, a click, a hold, a key or the program starts,+ MUST play the theme's motion tokens, its duration and easing tokens scaled by`tempo` (`architecture:theme-tokens`, `spec:AST-108` FR2), under every- pointer, a finger included. Three approved motions keep their springs until their own records change: the layout glide (`spec:AST-105` FR4), the animator's `animate` (`spec:AST-107` FR3), and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. A tap has no velocity, so it is not a gesture.- A touch presentation keeps its own look for that motion (FR13), such as a- menu that grows from its trigger or a thumb that lifts, and plays it on- those tokens. A press that starts as a tap or a hold and continues as a- drag springs from the drag's release. A touch presentation's exit that- no gesture drives plays the theme's exit duration and easing, and no exit- switch removes it (FR7, `spec:AST-090` FR14). Gesture- thresholds, the timings that decide who gets a touch, hold durations,- flick speeds, the press model's clocks and haptics are measured input- values, not motion roles, and stay internal as FR4 states. Under reduced motion, `design:reduced-motion`- governs both kinds (FR8, FR38, FR43).+ pointer, a finger included. Two approved motions keep their springs until+ their own records change: the animator's `animate` (`spec:AST-107` FR3) and+ `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and+ edge reveal are tap-started layout motion and play the theme's curve tokens+ (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops+ (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep+ their named roles; they are neither gesture- nor interaction-started motion. A+ tap has no velocity, so it is not a gesture. Springs drive the motion of a+ component whose main interaction is a gesture; curve tokens (a duration plus+ an easing) drive the motion of a component whose main interaction is a tap.+ Spring and curve timing share that one coordinated scale, so the theme's tempo+ scales both; the spring tiers are listed below (implementation gap: springs+ are tuned independently today). A touch presentation keeps its own look for+ that motion (FR13), such as a menu that grows from its trigger, and plays it+ on those tokens. A press that starts as a tap or a hold and continues as a+ drag springs from the drag's release. In a component whose main interaction is+ a tap, a touch presentation's exit that no gesture drives plays the theme's+ exit duration and easing, and no exit switch removes it (FR7, `spec:AST-090`+ FR14). Gesture thresholds, the timings that decide who gets a touch, hold+ durations, flick speeds, the press model's clocks and haptics are measured+ input values, not motion roles, and stay internal as FR4 states. Under reduced+ motion, `design:reduced-motion` governs both kinds (FR8, FR38, FR43).+ Companion motion inside a component (a sheet's scrim fade, handle and content+ fade or scale, a Lightbox's chrome fade, a menu's backdrop) runs on the pace+ of the component's main motion: it derives from the main spring's progress and+ settle time in a gesture component, or from the main curve's duration and+ easing in a tap component, and never runs on independent timing.++ | Main interaction | Motion | Components |+ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |+ | Gesture | Springs | BottomSheet, Drawer, swipeable List rows, Lightbox, the pager and Carousel, ContextMenu's long-press presentation, Slider, pull-to-refresh |+ | Gesture | Springs: a tap, key or program turn plays `springs.settle` from rest; the flick coast keeps UIKit's measured deceleration; the slow-release snap stays as recorded | the DateInput and TimeInput wheels |+ | Tap | Curve tokens | Accordion, Disclosure, Collapsible, DropdownMenu, Popover, Tooltip, HoverCard, Dialog, AlertDialog, Tabs, Checkbox, press feedback |+ | Gesture-capable | Springs under a touch presentation: the thumb drags, so every tap, click, key or value change settles on the same spring; without a touch presentation they keep the theme's curve (owner decision, 2026-11-04) | Switch, SegmentedControl |+ | Open (as its record states today) | Theme timing for a tap dismiss; a spring from the release for a swipe | Toast |++ Toast keeps the motion its record states today: theme timing for a tap+ dismiss, and a spring from the release for a swipe (`component:Toast` FR5).+ Which main interaction classifies it is open.++ | Spring roles | Timing tier |+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |+ | `springs.menuOpen`, `springs.menuClose`, `springs.contextMenuLift`, `springs.contextMenuDismiss`, `springs.contextMenuMorph` | `--duration-medium-min` |+ | `springs.subMenuOpen`, `springs.subMenuBack`, and a sheet's springs | `--duration-medium` |+ | `springs.settle`, `springs.emphasis` | `--duration-medium-max` |+ | `segmented.selectionSpring`, `springs.directChange`, `springs.quickChange`, `springs.stateChange`, `springs.timedChange`, `springs.viewChange`, `springs.sliderLift`, `springs.sliderDrop`, `springs.sliderRelease` | no tier named yet |+ | `springs.fingerTracking` | none; a follow stays fixed (`spec:AST-108` FR4) |+- **FR8 — Reduce Motion.** Under reduced motion, touch presentations follow`design:reduced-motion` DR2 and DR4.@@ -338,21 +419,21 @@ a measured, sourced difference exists.thresholds its UIKit counterpart uses: 0.5 s and 10 pt for a plain longpress, the measured values for context menus and menus. A rubber band MUSTuse the coefficient its use measures.-- **FR13 — One rule for the touch presentation.** A touch presentation- applies under a coarse primary pointer, and only after hydration: a server- render and the hydrating render produce the pointer presentation- (`spec:AST-013` FR9). Where a presentation also depends on size, compact is- governed by `spec:AST-012` FR9 and `architecture:public-component-api`- INV17. A presentation asks for exactly the conditions its own record names- (the date and time sheet asks for the pointer only, `spec:AST-043` FR1).- A style keyed on the literal touch media query conforms, since the server- and hydrating markup are identical (DEC-6).- A touch presentation is the look and press timing a component adds under- this condition: a lift, a sheet in place of a popover, a grow from the- trigger, hit-area growth (FR42), touch press timing (FR11) and haptics- (FR23). It never decides whether a part follows a pointer or whether a- gesture's settle springs (FR43, FR45). Its other motion plays the theme's- duration and easing tokens (FR45), and its exit plays as FR7 states.+- **FR13 — One rule for the touch presentation.** A touch presentation applies+ under a coarse primary pointer, and only after hydration: a server render and+ the hydrating render produce the pointer presentation (`spec:AST-013` FR9).+ Where a presentation also depends on size, compact is governed by+ `spec:AST-012` FR9 and `architecture:public-component-api` INV17. A+ presentation asks for exactly the conditions its own record names (the date+ and time sheet asks for the pointer only, `spec:AST-043` FR1). A style keyed+ on the literal touch media query conforms, since the server and hydrating+ markup are identical (DEC-6). A touch presentation is the look and press+ timing a component adds under this condition: a lift, a sheet in place of a+ popover, a grow from the trigger, hit-area growth (FR42), touch press timing+ (FR11) and haptics (FR23). It never decides whether a part follows a pointer+ or whether a gesture's settle springs (FR43, FR45). In a tap component its+ other motion plays the theme's duration and easing tokens, and in a gesture+ component its springs (FR45); its exit plays as FR7 states.- **FR14 — Nested scrolling follows the native rule.** Who gets a drag thatstarts inside a scroll area MUST be decided once, when the drag begins. Ifthe area sits at its edge and the drag moves toward that edge, the@@ -540,22 +621,21 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 andWCAG 2.2 SC 1.4.4). Listening for that outside touch costs nothing once it ends (FR24). A menuwhose caller passes `presentation="popover"` keeps its released outsidedismissal (FR25).-- **FR33 — A ContextMenu under a finger.** With a finger or pen, the long- press that opens a ContextMenu MUST NOT close it at the lift, and a press- outside it follows FR32. After a held- finger opens it, nothing is lit and a lift acts on nothing until that finger- has travelled the handoff distance (FR2) from the first position the open- menu sees; from then on FR26–FR28 apply. On every touch device, a ContextMenu that a held- finger opens on a block trigger MUST lift the trigger above the page and- show the menu beside it, with no row lit. A tap outside closes the menu and- reaches nothing beneath it, and closing returns the trigger to its place.- The lift plays on the theme's duration and easing tokens (FR45); the- return is part of the menu's exit and plays on the theme's exit duration- and easing (FR7).- Under reduced motion FR8 applies. An inline trigger keeps today's menu, a menu presented as a- bottom sheet follows the sheet, and `presentation="popover"` keeps the- released menu without the lift (`architecture:public-component-api`- INV16).+- **FR33 — A ContextMenu under a finger.** With a finger or pen, the long press+ that opens a ContextMenu MUST NOT close it at the lift, and a press outside it+ follows FR32. After a held finger opens it, nothing is lit and a lift acts on+ nothing until that finger has travelled the handoff distance (FR2) from the+ first position the open menu sees; from then on FR26–FR28 apply. On every+ touch device, a ContextMenu that a held finger opens on a block trigger MUST+ lift the trigger above the page and show the menu beside it, with no row lit.+ A tap outside closes the menu and reaches nothing beneath it, and closing+ returns the trigger to its place. ContextMenu's long-press presentation is a+ gesture component, so the lift plays `springs.contextMenuLift`, the menu's+ grow `springs.contextMenuMorph`, and the return, part of the menu's exit,+ `springs.contextMenuDismiss` (FR7, FR45). Under reduced motion FR8 applies. An+ inline trigger keeps today's menu, a menu presented as a bottom sheet follows+ the sheet, and `presentation="popover"` keeps the released menu without the+ lift (`architecture:public-component-api` INV16).- **FR34 — A sub-menu drills in under a finger.** Under a finger on acompact touch screen, an `adaptive` sub-menu row MUST drill in: thesub-menu's rows and a leading "Back to <parent>" row replace the menu's rows@@ -856,30 +936,31 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and- BottomSheet, Toast, Lightbox, NavigationStack and keyboard dismissal: adrag that commits follows FR36–FR40.- `spec:AST-100` owns release velocity, which FR17 reads.-- Under FR45, motion that a tap, a hold, a key or the program starts plays- the theme's duration and easing tokens under a finger as under a mouse.- The records that state such motion carry it: `component:Switch` FR9, FR10- and FR15, `component:Slider` FR7, `component:ContextMenu` FR5,- `component:DropdownMenu` FR21, `component:Popover` FR9,- `component:AlertDialog` FR6, `component:Lightbox` FR5, FR12 and FR16,- `component:TreeList` FR8, `component:ProgressBar` FR4,- `component:SegmentedControl` FR9 and FR10 and `component:DateInput` FR14. A touch presentation's exit- that a tap, a key or the program starts plays `spec:AST-090`'s- `--duration-exit` and `--ease-exit`, and no exit switch removes it (FR7;- `spec:AST-090` FR14 and DEC-5 carry it). Implementation gap: Switch, Slider and- SegmentedControl still play their measured roles for a tap or a key under a- coarse pointer; ProgressBar's fill still moves linearly for- `progress.fillTrackMs` times the share of the track moved under a coarse- pointer (`component:ProgressBar` FR4); and DateInput's sheet wheel turns- onto a clamped or a tapped row on its measured tap spin, not the theme's- move tokens (`component:DateInput` FR14).-- Under FR45, an open swipe row closed by a tap or Escape (`spec:AST-057`- FR5, FR7) plays the theme's exit tokens; a swipe that closes it keeps its- measured spring.-- Under FR45, `spec:AST-105` FR4's glide, which `component:SideNav` FR6 and- `component:AppShell` FR17 ride, and `spec:AST-107`'s `settleTo` and an- `animate` call without a velocity play a spring for motion that no gesture- drives. Their records keep their springs until each carries FR45.+- Under FR45, motion that a tap, a hold, a key or the program starts plays the+ theme's duration and easing tokens in a tap component, and the component's+ springs from rest in a gesture component, under a finger as under a mouse. The+ records that state such motion carry it: on tokens, `component:DropdownMenu`+ FR21, `component:Popover` FR9, `component:AlertDialog` FR6,+ `component:TreeList` FR8 and `component:ProgressBar` FR4; on springs,+ `component:Switch` FR9, FR10 and FR15, `component:SegmentedControl` FR9 and+ FR10, `component:Slider` FR7, `component:ContextMenu` FR5,+ `component:Lightbox` FR5, FR12 and FR16 and `component:DateInput` FR14. A tap+ component's touch exit that a tap, a key or the program starts plays+ `spec:AST-090`'s `--duration-exit` and `--ease-exit`, and no exit switch+ removes it (FR7; `spec:AST-090` FR14 and DEC-5 carry it). On Switch and+ SegmentedControl, every change under a touch presentation settles on the+ spring, as it does today; without a touch presentation a click, a key or a+ change of value keeps the theme's curve, unchanged. Implementation gap:+ ProgressBar's fill still moves linearly for `progress.fillTrackMs` times the+ share of the track moved under a coarse pointer (`component:ProgressBar` FR4);+ and DateInput's sheet wheel turns onto a clamped or a tapped row on its+ measured tap spin, not `springs.settle` (`component:DateInput` FR14).+- Under FR45, a swipe row is a gesture component: a close or return that a tap+ or Escape starts (`spec:AST-057` FR5, FR7) plays the row's spring from rest,+ and a swipe that closes it keeps its measured spring from the release.+- Under FR45, `spec:AST-107`'s `settleTo` and an `animate` call without a+ velocity play a spring for motion that no gesture drives. Their records keep+ their springs until each carries FR45.- Under FR43 and FR45, a part that follows a pointer follows every pointerand its release springs from the release velocity under every pointer:`component:Switch` FR15's thumb under a mouse or a pen, `component:Slider`@@ -900,26 +981,28 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 andMotion that FR45 moves, by component. Each component's record carries its own line, except Carousel, whose trackpad paging this record states through the shared pager (FR43):-| Component | Motion | Today | Under FR45 |-| --------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |-| Switch | Thumb travel and track colour on a tap, a hold or a key, under a finger | Measured switch springs | Theme duration and easing tokens |-| Switch | Thumb lift while a finger presses, with a minimum lift time | Measured lift and settle springs | The same lift on the theme's tokens |-| Switch | A mouse's or a pen's drag | Thumb still until the release, then the theme's duration | Thumb follows; the release springs from its velocity |-| Slider | Thumb lift and drop under a finger | Measured lift and drop springs | Theme tokens |-| Slider | A mouse's or a pen's flick | Ends at the release | Coasts and settles as a finger's does |-| DropdownMenu, Popover | Grow from the trigger and shrink back under a finger | `springs.menuOpen`, `springs.menuClose` | Theme entrance tokens; theme exit duration and easing |-| DropdownMenu | Sub-menu drill-in on a compact touch screen | `springs.subMenuOpen`, `springs.subMenuBack` | Theme move tokens |-| ContextMenu | Trigger lift and the menu's grow after a long press | `springs.contextMenuLift`, `springs.contextMenuMorph` | Theme tokens |-| AlertDialog | Scale-in present under a finger | `springs.alertPresent` | Theme entrance tokens |-| Lightbox | Controls fade on a tap, a double tap's zoom, the grow from its source | Named measured roles | Theme tokens |-| TreeList | Group slide under a coarse pointer | Measured motion | Theme tokens |-| ProgressBar | Determinate fill on a value change under a coarse pointer | Linear, `progress.fillTrackMs` times the share moved | `--duration-medium` and the theme's easing, every pointer |-| DateInput | Sheet wheel turning onto a clamped or a tapped row | `picker.tapSpin.durationMs` on `timing.curves.move` | Theme move tokens |-| DateInput | Sheet wheel under a trackpad | Coarse primary pointer only | Wherever the sheet shows |-| Carousel | Paging under a trackpad swipe | Coarse primary pointer only | Every pointer |-| Every overlay | A touch exit that a tap, a key or an outside press starts | The native counterpart's timing | `--duration-exit` and `--ease-exit`; the exit switches never remove it |-| SegmentedControl | Selection slide on a tap or a key under a finger | `segmented.selectionSpring` | Theme duration and easing tokens |-| SegmentedControl | A mouse's or a pen's drag release | Slides on the theme's duration | Settles on a spring from the release velocity |+| Component | Motion | Today | Under FR45 |+| --------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Switch | Thumb travel and track colour on a tap, a hold, a click or a key under a touch presentation | Measured switch springs | The thumb's `switchControl.travel` spring from rest |+| Switch | Thumb travel and track colour on a click, a key or a value change without a touch presentation | The theme's curve (`--duration-fast`, `--ease-standard`) | Unchanged: the theme's curve |+| Switch | Thumb lift while a finger presses, with a minimum lift time | Measured lift and settle springs | `switchControl.lift` (gesture component) |+| Switch | A mouse's or a pen's drag | Thumb still until the release, then the theme's duration | Thumb follows; the release springs from its velocity |+| Slider | Thumb lift and drop under a finger | Measured lift and drop springs | `springs.sliderLift` and `springs.sliderDrop` (gesture component) |+| Slider | A mouse's or a pen's flick | Ends at the release | Coasts and settles as a finger's does |+| DropdownMenu, Popover | Grow from the trigger and shrink back under a finger | `springs.menuOpen`, `springs.menuClose` | Theme entrance tokens; theme exit duration and easing |+| DropdownMenu | Sub-menu drill-in on a compact touch screen | `springs.subMenuOpen`, `springs.subMenuBack` | Theme move tokens |+| ContextMenu | Trigger lift and the menu's grow after a long press | `springs.contextMenuLift`, `springs.contextMenuMorph` | The same springs (gesture component) |+| AlertDialog | Scale-in present under a finger | `springs.alertPresent` | Theme entrance tokens |+| Lightbox | Controls fade on a tap, a double tap's zoom, the grow from its source | Named measured roles | Springs, `springs.settle` unless the motion table names another role; the controls fade keeps the main spring's pace |+| TreeList | Group slide under a coarse pointer | Measured motion | Theme tokens |+| ProgressBar | Determinate fill on a value change under a coarse pointer | Linear, `progress.fillTrackMs` times the share moved | `--duration-medium` and the theme's easing, every pointer |+| DateInput | Sheet wheel turning onto a clamped or a tapped row | `picker.tapSpin.durationMs` on `timing.curves.move` | `springs.settle` from rest |+| DateInput | Sheet wheel under a trackpad | Coarse primary pointer only | Wherever the sheet shows |+| Carousel | Paging under a trackpad swipe | Coarse primary pointer only | Every pointer |+| Every tap-component overlay | A touch exit that a tap, a key or an outside press starts | The native counterpart's timing | `--duration-exit` and `--ease-exit`; the exit switches never remove it; a gesture component's such exit, such as a sheet's or the Lightbox's, plays its spring (FR7) |+| SegmentedControl | Selection slide on a tap, a click or a key under a touch presentation | `segmented.selectionSpring` | The selection spring from rest (gesture component under touch) |+| SegmentedControl | Selection slide on a click, a key or a program change without a touch presentation | The theme's duration and easing | Unchanged: the theme's curve |+| SegmentedControl | A mouse's or a pen's drag release | Slides on the theme's duration | Settles on a spring from the release velocity |## Verification@@ -928,13 +1011,16 @@ Motion that FR45 moves, by component. Each component's record carries its own li| FR1, FR2 | Value check over every measured value and its uses | every value; a guess and its measurement task; a platform-specific value; two components playing the same motion | an unsourced value, an unknown source kind, a guess without a listed measurement, an unsourced platform split, or two values for one use fails || FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values || FR3 pager | Unit tests of the pager's page choice against the recorded UIKit releases | releases at 292.7–298.6 pt/s that stay and 310.7–329.9 pt/s that advance, at 10, 25 and 40 % of a page; releases at rest at 45–48.5 % and 55–57.5 %; a 1.5-page drag released at 0, 600 and 3000 pt/s; a release moving back toward the start page | a page chosen by projection, a release at or past 300 pt/s that stays, or a release that travels more than one page from its start fails |-| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails |+| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role (other than a measured gesture-driven exit spring its component's motion table lists with its platform source), a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails |+| FR4 | Role unit tests over gesture-driven exits | a gesture-driven exit (a release that closes or dismisses) playing a spring measured from the platform reference with no named role; the same unnamed spring played by a program-started motion or by a gesture-driven motion that is not an exit, such as a settle | a gesture-driven exit playing a measured table spring passes; a program-started motion, or a non-exit gesture motion, playing an unnamed spring fails || FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out || FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring; a retarget before the browser reports the call's start | a layout read, a jump, or a lost velocity fails || FR6 pager | Unit and browser tests of a pager's settle start | releases just under and over 225 pt/s; a catch mid-settle; a programmatic page change mid-settle | a release under the floor whose settle starts moving, a release over it whose settle starts from rest, a catch that loses the on-screen velocity, or a programmatic page change mid-settle that starts from rest fails; a page change during a drag starts from rest || FR6 starved | Switch frame proofs on a starved main thread (4 workers on 2 cores); a unit test of a retarget on a settle tail | a second tap mid-travel, with frames read late or its lift handled 100 ms late; a first frame committed late; a retarget once the thumb is still | a jump out of a thumb that is still fails; a mid-travel step within the browser's commit delay is the known limit |-| FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), or an opacity fade over 200 ms fails |-| FR45 | Browser tests with a mouse, a pen, a trackpad and a finger at each `tempo` bound and each `character`, and with Reduce Motion | a tap, a click, a key and a programmatic change on a Switch, a menu, an alert, a sheet and a ProgressBar under a fine and a coarse pointer; a drag release, a flick and a pinch on a Switch, a Slider, a sheet, a pager and a Lightbox photo under each pointer; a tap that continues as a drag | a tap, click, key or programmatic change under a finger that plays a measured role instead of the theme's duration and easing tokens, a gesture's settle that starts from rest or plays a theme curve, a gesture's spring that ignores `character` or `tempo`, or a part that follows one pointer and not another, fails |+| FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion; a tap-, key- and program-started close of a sheet and the Lightbox | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), an opacity fade over 200 ms, or a tap-, key- or program-started close of a gesture component on the exit curve instead of its spring, fails |+| FR45 | Browser tests with a mouse, a pen, a trackpad and a finger at each `tempo` bound and each `character`, and with Reduce Motion | a tap, a click, a key and a programmatic change on a Switch, a menu, an alert, a sheet and a ProgressBar under a fine and a coarse pointer; a drag release, a flick and a pinch on a Switch, a Slider, a sheet, a pager and a Lightbox photo under each pointer; a tap that continues as a drag | a tap, click, key or programmatic change in a tap-classified component that plays a measured role or a spring instead of the theme's duration and easing tokens, a touch tap-started move in a gesture or gesture-capable component on a curve instead of its spring, a click, a key or a value change on Switch or SegmentedControl without a touch presentation that leaves the theme's curve, a velocity-carrying release that settles from rest or on a curve, a gesture's spring that ignores `character` or `tempo`, or a part that follows one pointer and not another, fails; the pager's measured settle, which does not yet follow `tempo` or `character`, is a recorded implementation gap |+| FR45 | Component source and token tests for a tap component's motion whose record names no step, with a platform measurement | a small anchored surface (a popover, a menu, a toggle, a row) and a full-screen surface (a Dialog, an AlertDialog), each with its own measurement; a tap component's overlay exit | a token cited as nearest to the measurement in the Storybook theme passes, and a tap component's overlay exit on `--duration-exit` passes; a token chosen by role alone, or nearest at Core's unthemed defaults, fails |+| FR45 | Browser frame capture of companion motion in a gesture and a tap component | a sheet's scrim, handle and content fade; a Lightbox's chrome fade; a menu's backdrop | a companion fade on its own duration fails; one driven by the main motion's progress or settle time passes || FR9, FR10 | Recognizer unit tests on synthetic streams and browser tests with real touch input | drag, second finger, pinch, page zoom, main-thread block | a second finger that breaks a drag, or a page pinch blocked other than by the author's `touch-action`, fails || FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps | inside and outside a scroll view; a drag the browser takes; a lift inside; a menu row under a finger; a press on a row of a menu whose rows fit and of one that scrolls; a slide-off lift on a Switch and on a Radio | the wrong profile's timing, a press that survives the browser taking the touch, or a control outside an action group activated other than by the browser's click, outside `spec:AST-020` FR9's slide-off exception, a row of a menu whose rows fit that waits 150 ms, or one of a scrolling menu that does not, or a slide-off lift that completes a control outside `spec:AST-020` FR9's exception, fails || FR13 | Resolver unit tests and a server-render test | coarse and fine pointer; narrow, wide and short; server render; hydrating render | a component that answers the conditions differently, or a touch presentation in the server or hydrating render, fails |@@ -1267,14 +1353,15 @@ applies unchanged.Rejected: projecting a paging release with a deceleration rate; handing aslow paging release's velocity to the settle.-### DEC-26 — Only a gesture's motion springs from measured roles; other motion plays the theme's tokens+### DEC-26 — A gesture component's motion springs from measured roles; a tap component's tap-started motion plays the theme's tokens**Reference:** `spec:AST-094/DEC-26`**Decider:** `cixzhang`, `2026-11-02`-Motion that a gesture drives continues the person's hand, so it starts at the-gesture's speed and settles on a spring under every pointer: a flick with a-mouse throws as a flick with a finger does. Motion that a tap, a click, a+Motion that a gesture drives continues the person's hand. A release that+carries the gesture's velocity starts at that speed and settles on a spring+under every pointer: a flick with a mouse throws as a flick with a finger does.+In a component whose main interaction is a tap, motion that a tap, a click, ahold, a key or the program starts has no speed to carry, so it plays thetheme's motion tokens, its duration and easing scaled by `tempo`, under everypointer, and a theme's timing reaches it as it reaches every other timed@@ -1294,14 +1381,20 @@ applies the theme's motion tokens.This narrows the measured motion roles of DEC-1, DEC-3 and DEC-15 to motion agesture drives, and extends the Non-goals' theme timing to every pointer.Measured input timings, such as who gets a touch, hold durations and flick-speeds, stay internal values and are not motion roles. A touch presentation's-exit that no gesture drives plays the theme's exit duration and easing; the-theme's exit switches still never remove it (`spec:AST-090` DEC-5).-+speeds, stay internal values and are not motion roles. A tap component's touch+exit that no gesture drives plays the theme's exit duration and easing, and a+gesture component's plays its spring; the theme's exit switches still never+remove it (`spec:AST-090` DEC-5).Rejected: keeping the measured springs for motion a tap starts under a finger.Rejected: a theme curve for a mouse release, which stops a flick dead.Rejected: following a pointer only under a finger.+On 2026-11-04 the owner set the unit of that choice: a component's main+interaction. A component whose main interaction is a gesture plays springs for+all its motion, a tap inside it included, and a component whose main+interaction is a tap plays curve tokens, so each component's pieces stay+coordinated (FR45).+### DEC-27 — Android claims rest on emulator evidence**Reference:** `spec:AST-094/DEC-27`diff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.mdindex b8f628fe01..2827317964 100644--- a/docs/specs/components/ContextMenu/ContextMenu.spec.md+++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md@@ -100,18 +100,18 @@ Consumer props, content modes, and presentation policy remain documented in## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |-| FR1 | Every render contains a caller-provided Trigger area; with `isDisabled` no invocation opens a menu and the native context menu is left alone. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests |-| FR2 | The `context-menu` target stays on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | `architecture:component-theming-surface`; current source |-| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs |-| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests |-| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST close as a pan that starts outside it begins (`spec:AST-094` FR32), MUST hand the held finger that opened it to the menu as the opening press, and MUST treat a pen's press outside as FR32 does (FR33). The lift and the grow apply only to a menu opened by touch (a touch-initiated open on a coarse pointer); a menu opened by mouse or keyboard keeps its released appearance and motion, with no lift, no tint and no grow. A touch-opened menu MUST grow out of the finger's point and shrink back into it (`spec:AST-094` FR31) as its own surface, by transform and opacity only (`spec:AST-094` FR5), with no second element such as a glass surface growing behind it, and on a block trigger MUST lift the trigger above the page with the menu beside it (FR33; DD1, DEC-2). The trigger's lift and the menu's grow play on the theme's duration and easing tokens (`spec:AST-094` FR45), and the trigger's return, part of the menu's exit, plays on the theme's exit duration and easing (`spec:AST-094` FR7); the three `springs.contextMenu*` roles stay as the measured reference (`spec:AST-094` FR4). Implementation gap: it keeps the layer's own entrance and exit, a scroll that starts outside leaves it open, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift or page tint exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 |-| FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 |-| FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` |-| FR8 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. A disabled row is reached by these keys and by typeahead and stays inert, as `component:DropdownMenu` FR17 states. Implementation gap: the arrow keys and typeahead skip disabled rows today (Current-state impact). | Current source and tests |-| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case |-| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships; ContextMenu owns its invocation, open state, outside-press listener, and cleanup itself. | `spec:AST-107` FR8 |+| ID | Invariant | Basis |+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |+| FR1 | Every render contains a caller-provided Trigger area; with `isDisabled` no invocation opens a menu and the native context menu is left alone. Pointer presentation opens a Pointer menu surface at the current local cursor anchor; touch presentation opens a Touch sheet frame containing a Touch menu surface and, for data mode, a Touch action list and Touch action rows. | Current source, docs, and tests |+| FR2 | The `context-menu` target stays on the painted Pointer menu surface and alternative Touch menu surface, not on the Trigger area or cursor anchor. | `architecture:component-theming-surface`; current source |+| FR3 | Pointer action rows retain DropdownMenu ownership. The touch frame retains BottomSheet ownership, while data-driven touch lists and rows retain List ownership. | Current source and owner docs |+| FR4 | Compound `menuContent` remains a caller-supplied pointer-menu interior and may also render inside the touch frame; the data-driven touch path instead converts the same item data to List and ListItem presentation. | Current source and tests |+| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST close as a pan that starts outside it begins (`spec:AST-094` FR32), MUST hand the held finger that opened it to the menu as the opening press, and MUST treat a pen's press outside as FR32 does (FR33). The lift and the grow apply only to a menu opened by touch (a touch-initiated open on a coarse pointer); a menu opened by mouse or keyboard keeps its released appearance and motion, with no lift, no tint and no grow. A touch-opened menu MUST grow out of the finger's point and shrink back into it (`spec:AST-094` FR31) as its own surface, by transform and opacity only (`spec:AST-094` FR5), with no second element such as a glass surface growing behind it, and on a block trigger MUST lift the trigger above the page with the menu beside it (FR33; DD1, DEC-2). The long-press presentation is a gesture component, so the trigger's lift plays `springs.contextMenuLift`, the menu's grow `springs.contextMenuMorph`, and the trigger's return, part of the menu's exit, `springs.contextMenuDismiss` (`spec:AST-094` FR4, FR7, FR45). Implementation gap: it keeps the layer's own entrance and exit, a scroll that starts outside leaves it open, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift or page tint exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 |+| FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 |+| FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` |+| FR8 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. A disabled row is reached by these keys and by typeahead and stays inert, as `component:DropdownMenu` FR17 states. Implementation gap: the arrow keys and typeahead skip disabled rows today (Current-state impact). | Current source and tests |+| FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case |+| FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships; ContextMenu owns its invocation, open state, outside-press listener, and cleanup itself. | `spec:AST-107` FR8 |### Allowed variation@@ -232,10 +232,10 @@ anchor is positioning infrastructure rather than consumer anatomy.- `spec:AST-094` owns the touch press, lift, grow, and dismissal rules (FR5).- `spec:AST-094` FR4 lists the three motion roles this component owns, measuredfor its lift: `springs.contextMenuLift`, `springs.contextMenuDismiss` and- `springs.contextMenuMorph`. They stay as the measured reference: a long- press is not a gesture, so the lift and the grow play the theme's tokens- (`spec:AST-094` FR45), and the return, part of the exit, plays the theme's- exit duration and easing (`spec:AST-094` FR7).+ `springs.contextMenuMorph`. ContextMenu's long-press presentation is a gesture+ component, so the lift plays `springs.contextMenuLift`, the grow+ `springs.contextMenuMorph`, and the return, part of the exit,+ `springs.contextMenuDismiss` (`spec:AST-094` FR7, FR45).- `family:overlay-dismissal` owns shared Escape and platform-close ordering.ContextMenu's pointer presentation is a shared-stack adopter; the touchpresentation delegates dismissal to BottomSheet, which is also a shared-stack@@ -251,7 +251,7 @@ anchor is positioning infrastructure rather than consumer anatomy.| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and scroll outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, or a tap or mouse press outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift; the scroll-outside and pen cases assert the current gaps. | `audit:ContextMenu/behavior` || FR5, DD1 touch scope | Browser tests on the touch story, the menu opened by a finger under a coarse pointer and by a mouse and by Shift+F10 under a fine pointer | Touch-opened, mouse-opened and keyboard-opened menus on a block trigger | A mouse- or keyboard-opened menu that lifts its trigger, tints the page or grows, or a touch-opened menu that blurs the page, grows a second surface, or animates anything but transform and opacity, fails. Evidence gap: the lift and the grow are unbuilt, so no test asserts either. | `audit:ContextMenu/behavior` || FR5 Reduce Motion | Browser tests on the touch story with reduced motion | A touch-opened menu opening and closing under Reduce Motion | A lift, grow or shrink that moves rather than playing an opacity-only cross-fade of 200 ms or less (`spec:AST-094` FR8) fails. Evidence gap: no test exists. | `audit:ContextMenu/behavior` |-| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a spring or a literal instead of the theme's duration and easing tokens, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` |+| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a curve or a literal instead of its spring role, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` || DEC-2 | Element-count browser test on the touch story (`spec:AST-017` FR60) | At rest and lifted, fine and coarse pointer | A lift element at rest, a copy of the trigger, or an open count beyond the layer, the shadow, the anchor and the placeholder fails. Evidence gap: the lift is unbuilt, so no test exists. | `audit:ContextMenu/anatomy` || FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` || FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` |diff --git a/docs/specs/components/DateInput/DateInput.spec.md b/docs/specs/components/DateInput/DateInput.spec.mdindex efc66de127..e8937d53f4 100644--- a/docs/specs/components/DateInput/DateInput.spec.md+++ b/docs/specs/components/DateInput/DateInput.spec.md@@ -177,7 +177,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR11 | Clear MUST emit `undefined` through the ordinary change pipeline. The pointer and bottom-sheet surfaces restore field focus using their shipped timing; the native surface MUST NOT reclaim focus because doing so reopens the OS picker. Implementation gap: when the field becomes disabled or busy while its clear control holds focus, the control unmounts and focus falls to the document body; `spec:AST-085/FR4` requires focus to stay or move to a destination this record names. | Current source and focused clear tests; `spec:AST-085/FR4` || FR12 | No surface renders native `disabled`. A disabled field MUST stay focusable with `aria-disabled`, block typing, picking, clearing, and opening, describe its disabled reason when one is given, and take disabled paint. While busy (`isLoading` or a pending Action) the pointer and bottom-sheet surfaces expose `aria-disabled` and `aria-busy`, stay focusable, and block new commits; the native surface does the same for `isLoading`, and during a pending Action stays editable so the OS picker remains attached but rejects additional commits until the Action settles. A busy field that is not disabled keeps its ordinary paint and Spinner, shows no hover ring while commits are blocked, and keeps its keyboard focus ring. While disabled or busy, the field ignores Enter and blur and shows no typed rejection. Typed text whose date typing has not reported stays, and the next Enter or blur once the field is editable commits or rejects it; a new `value` replaces it. Text whose date typing already reported through `onChange` gives way to the field's value once the field is editable again, whether or not the change took it; a focused field keeps the text until the next Enter or blur. Caller handlers other than focus and blur MUST NOT run while the field is disabled (`spec:AST-085` FR2). Implementation gap: only a caller `onClick` is skipped while disabled; caller key, paste, and pointer handlers (such as `onKeyDown`, `onKeyUp`, `onPaste`, and `onPointerDown`) still run on every surface, the native field included. | `spec:AST-085/FR1–FR6`; `family:input-fields/FR4–FR6`; `family:buttons/FR4`; current source and focused tests || FR13 | A bottom-sheet picker wheel that comes to rest on a disabled row (outside `min`/`max`) MUST continue to the nearest enabled row, a tie going toward the committed row, and select it there. A wheel resting on its committed row MUST NOT select or commit, even when that row is outside the bounds, so opening a bounded sheet never changes an untouched value: a committed value outside the bounds stays, and an empty field stays empty. This holds for every wheel in the DateInput, TimeInput, and DateTimeInput sheets. | DEC-1; UIDatePicker on the iOS 26.2 simulator; current source |-| FR14 | A shown bottom-sheet picker wheel whose value changes from outside, as when a bound clamps the time after another wheel turned, MUST turn onto the new row rather than jump to it, on the theme's move duration and easing tokens, as a tap on a row does (`spec:AST-094` FR45). The internal motion role `picker.tapSpin.durationMs`, UIKit's measured 300 ms, stays as the measured reference. Under a finger, a tapped row commits its value when its turn ends; a keyboard or assistive-technology activation commits at once. Implementation gap: under a finger, the turn and a tapped row's turn still play `picker.tapSpin.durationMs` on `timing.curves.move`; under a mouse, the turn plays the browser's smooth scroll. | UIDatePicker on the iOS 26.2 simulator; current source |+| FR14 | A shown bottom-sheet picker wheel whose value changes from outside, as when a bound clamps the time after another wheel turned, MUST turn onto the new row rather than jump to it, on `springs.settle` from rest, as a tap, a key or a program turn does: the wheel's main interaction is a gesture (`spec:AST-094` FR45). The internal motion role `picker.tapSpin.durationMs`, UIKit's measured 300 ms, stays as the measured reference. Under a finger, a tapped row commits its value when its turn ends; a keyboard or assistive-technology activation commits at once. Implementation gap: with the touch presentation, a turn onto a row plays `picker.tapSpin.durationMs` on `timing.curves.move`, whatever pointer starts it, not `springs.settle`; without it, the wheel is a scrolling column and a click or key turn plays the browser's smooth scroll. | UIDatePicker on the iOS 26.2 simulator; current source || FR15 | Wherever the sheet shows, a sheet wheel's pan takes a trackpad's two-finger scroll, as `spec:AST-094` FR43 allows a record to grant: the rows follow the fingers, coast on at the lift with the fingers' last speed, the coast starting from that speed (`spec:AST-094` FR45), and rest on a row by FR13. A mouse-wheel notch turns the wheel one row, as an arrow key does, with no coast. A ctrl-scroll stays the page's zoom (`spec:AST-094` FR43). Implementation gap: a trackpad drives the wheel only under a coarse primary pointer. | `spec:AST-094` FR43; current source || FR16 | Enter in the pointer field's text input commits typed text that has not been committed and is then held back, so a form never submits the value from before the commit. With no typed text pending, Enter is not prevented, so a form submits as it does from any text field, except on a disabled or busy field, where Enter does nothing (`spec:AST-085` FR2). || FR17 | In a sheet wheel, Arrow, Page, Home and End move through the wheel's enabled values in time order, skipping disabled ones, and stop at the first or last enabled value; a key with no enabled value in its direction commits nothing, under every presentation. On a 12-hour hour wheel, time order follows the full time (12 PM comes before 1 PM), not the column's row order. | Owner decision (cixzhang, 2026-11-02); current source |diff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.mdindex 2241ad74b3..7410e4f2a5 100644--- a/docs/specs/components/Lightbox/Lightbox.spec.md+++ b/docs/specs/components/Lightbox/Lightbox.spec.md@@ -131,24 +131,24 @@ FR21). Consumer props and usage remain documented in `Lightbox.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | --------------------------- |-| FR1 | The 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 | settled |-| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | settled |-| 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 | settled |-| 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` | settled; implementation gap |-| FR5 | Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Every spring a gesture drives in them (the zoom settle, the page settle, the dismiss and the pinch close) is a named motion role read through the motion role table, never a literal, and starts at the gesture's velocity; motion that a tap, a double tap, a key or the program starts (the controls fade and a double tap's zoom transition) plays the theme's duration and easing tokens (`spec:AST-094` FR45). Under reduced motion they follow AR6. | `spec:AST-094` FR4, FR13 | settled; implementation gap |-| FR6 | With `hasZoom`, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page. | `spec:AST-094` FR3, FR10 | settled; implementation gap |-| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by `spec:AST-094` FR3's paging rule (DEC-25). Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR3, FR14, FR36–FR39, DEC-25 | settled; implementation gap |-| FR8 | On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports `onOpenChange(false)` at the lift; a release moving back springs back. Video is unchanged. | `spec:AST-094` FR36–FR40 | settled; implementation gap |-| FR9 | With `hasZoom`, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer. | `spec:AST-094` FR36, FR37 | settled; implementation gap |-| FR10 | With `hasZoom`, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden. | `architecture:public-component-api` INV16 | settled; implementation gap |-| FR11 | A mouse, a pen, and a trackpad also use FR7's drag paging, FR8's drag to close, a ctrl-wheel or trackpad pinch over the photo for FR6's zoom and FR9's close, and a wheel to pan a zoomed photo; over the photo these replace the browser's page zoom and scroll. A double-click zooms 2× about the clicked point. A click on the photo keeps the controls, and the viewer opens and closes at once. | `spec:AST-094` FR43; `spec:AST-017` FR59 | settled; implementation gap |-| FR12 | Inside `experimental` only, under a coarse pointer, the photo grows out of its source when the viewer opens, on the theme's duration and easing tokens (`spec:AST-094` FR45), and returns into it when it closes, on the theme's exit duration and easing (`spec:AST-094` FR7): the element `experimental.sourceFor(index)` returns, else the opener when it shows a picture. A close reports `onOpenChange(false)` at the request; the viewer stays only until the photo lands. Pointer input during the entrance is held; keys and assistive technology stay live. Without `experimental`, opening is unchanged and closing plays FR16. | `spec:AST-017` FR21; `spec:AST-094` FR35 | settled; implementation gap |-| FR13 | `hasZoom={false}` turns off FR6, FR9, and FR10. FR7 and FR8 add to the buttons, keys, and Escape and remove none of them, so Lightbox takes no `presentation` prop. | `architecture:public-component-api` INV16 | settled |-| FR14 | Gestures, paging, motion, and reduced motion run through Core's one shared set of internal touch modules; Lightbox bundles no copy of a module's primitive and adds no gesture listener outside them. | `architecture:react-component-runtime` INV13 | settled; implementation gap |-| FR15 | Lightbox supports a Picture-in-Picture window as its only second document; there it ranks Escape and platform close among that window's members. | `family:overlay-dismissal` FR8 | settled |-| FR16 | Under a coarse primary pointer, a close that is not a drag down (FR8), a pinch in (FR9), or a return into a source (FR12) plays the touch exit: Close, Escape, a platform close, and a tap beside the photo while the controls are shown (ORD3). The photo shrinks a little and fades out in place with the backdrop and controls, as the native viewer's zoom transition does without a source, on the theme's exit duration and easing, `--duration-exit` and `--ease-exit` (`spec:AST-090` FR14; `spec:AST-094` FR7, FR45). `onOpenChange(false)` reports at the request, and the viewer takes no input while the exit plays. Under a fine pointer the viewer closes at once (FR11). | `spec:AST-094` FR7 | settled; implementation gap |+| ID | Candidate invariant | Basis | Draft review state |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | --------------------------- |+| FR1 | The 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 | settled |+| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | settled |+| 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 | settled |+| 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` | settled; implementation gap |+| FR5 | Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Lightbox's main interaction is a gesture, so every move in them (the zoom settle, a double tap's zoom, the page settle, the dismiss and the pinch close) is a spring on a named motion role read through the motion role table, never a literal, and a release starts at the gesture's velocity; the controls fade is companion motion on the pace of the main spring (`spec:AST-094` FR45). Under reduced motion they follow AR6. | `spec:AST-094` FR4, FR13 | settled; implementation gap |+| FR6 | With `hasZoom`, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page. | `spec:AST-094` FR3, FR10 | settled; implementation gap |+| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by `spec:AST-094` FR3's paging rule (DEC-25). Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR3, FR14, FR36–FR39, DEC-25 | settled; implementation gap |+| FR8 | On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports `onOpenChange(false)` at the lift; a release moving back springs back. Video is unchanged. | `spec:AST-094` FR36–FR40 | settled; implementation gap |+| FR9 | With `hasZoom`, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer. | `spec:AST-094` FR36, FR37 | settled; implementation gap |+| FR10 | With `hasZoom`, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden. | `architecture:public-component-api` INV16 | settled; implementation gap |+| FR11 | A mouse, a pen, and a trackpad also use FR7's drag paging, FR8's drag to close, a ctrl-wheel or trackpad pinch over the photo for FR6's zoom and FR9's close, and a wheel to pan a zoomed photo; over the photo these replace the browser's page zoom and scroll. A double-click zooms 2× about the clicked point. A click on the photo keeps the controls, and the viewer opens and closes at once. | `spec:AST-094` FR43; `spec:AST-017` FR59 | settled; implementation gap |+| FR12 | Inside `experimental` only, under a coarse pointer, the photo grows out of its source when the viewer opens, and returns into it when it closes, on springs, `springs.settle` unless the motion table names another role, since Lightbox's main interaction is a gesture (`spec:AST-094` FR7, FR45): the element `experimental.sourceFor(index)` returns, else the opener when it shows a picture. A close reports `onOpenChange(false)` at the request; the viewer stays only until the photo lands. Pointer input during the entrance is held; keys and assistive technology stay live. Without `experimental`, opening is unchanged and closing plays FR16. | `spec:AST-017` FR21; `spec:AST-094` FR35 | settled; implementation gap |+| FR13 | `hasZoom={false}` turns off FR6, FR9, and FR10. FR7 and FR8 add to the buttons, keys, and Escape and remove none of them, so Lightbox takes no `presentation` prop. | `architecture:public-component-api` INV16 | settled |+| FR14 | Gestures, paging, motion, and reduced motion run through Core's one shared set of internal touch modules; Lightbox bundles no copy of a module's primitive and adds no gesture listener outside them. | `architecture:react-component-runtime` INV13 | settled; implementation gap |+| FR15 | Lightbox supports a Picture-in-Picture window as its only second document; there it ranks Escape and platform close among that window's members. | `family:overlay-dismissal` FR8 | settled |+| FR16 | Under a coarse primary pointer, a close that is not a drag down (FR8), a pinch in (FR9), or a return into a source (FR12) plays the touch exit: Close, Escape, a platform close, and a tap beside the photo while the controls are shown (ORD3). The photo shrinks a little and fades out in place with the backdrop and controls, as the native viewer's zoom transition does without a source, on a spring from rest, `springs.settle` unless the motion table names another role, with the backdrop and controls fading on its pace (`spec:AST-094` FR7, FR45). `onOpenChange(false)` reports at the request, and the viewer takes no input while the exit plays. Under a fine pointer the viewer closes at once (FR11). | `spec:AST-094` FR7 | settled; implementation gap |### Allowed variation@@ -229,7 +229,7 @@ under `spec:AST-020` FR1; reduced motion cites `design:reduced-motion`.touch drag starts them (DR2), including a mouse, pen, or trackpad releasewhere the primary pointer is coarse (`spec:AST-094` FR43). Otherwise theycomplete at once (DR3). The momentum coast of a thrown zoomed photo is direct- movement and continues (DR2). These motions read the named motion roles or the theme's tokens (FR5), which carry the+ movement and continues (DR2). These motions read the named motion roles (FR5), which carry thereduced-motion path.- **AR7 — Focus visible and not obscured (WCAG 2.2 2.4.7, 2.4.11).** Everyfocusable control and the zoom target show the shared focus indicator. Adiff --git a/docs/specs/components/SegmentedControl/SegmentedControl.spec.md b/docs/specs/components/SegmentedControl/SegmentedControl.spec.mdindex 76e01fb0a6..1633e7f63a 100644--- a/docs/specs/components/SegmentedControl/SegmentedControl.spec.md+++ b/docs/specs/components/SegmentedControl/SegmentedControl.spec.md@@ -138,8 +138,8 @@ Consumer migration instructions belong in consumer docs and release notes.| FR6 | Size resolves from an explicit `size`, then the nearest size provider, then `md`, and reaches every segment. | `architecture:component-size-cascade` INV3–INV5; current source || FR7 | `isDisabled` sets `aria-disabled` on the radiogroup, disables every segment, dims the control to half opacity, and blocks selection. The group MUST keep a Tab stop while disabled, placed as in FR2, and pointer events stay on (`spec:AST-085` FR1, FR7). With `disabledMessage`, a reason tooltip opens on hover and keyboard focus; the reason MUST describe the focusable segment (`spec:AST-085` FR5, FR7). Implementation gap: caller handlers on the radiogroup, such as `onKeyDown`, still run while disabled (`spec:AST-085` FR2). | `spec:AST-085`; current tests || FR8 | The radiogroup owns `role`, `aria-label` (from `label`), `aria-disabled`, and `data-size`; a caller value for any of them is replaced. Other base props reach the radiogroup, and `ref` reaches it. Implementation gap: a caller `aria-describedby` is replaced, by the disabled-reason id or by nothing, against `architecture:public-component-api` INV5. | `architecture:public-component-api` INV5; current source and tests |-| FR9 | Under every pointer, a change of selection slides the selected surface from the old segment to the new one as one surface, the radiogroup's `::before`, animating transform and opacity only. A change that a tap, a click, a key or the program starts slides on the theme's duration and easing tokens, a finger included (`spec:AST-094` FR45); a drag's release settles on a spring from the release velocity (FR10, FR13). | Owner direction; `spec:AST-094` FR13; current source and tests |-| FR10 | A drag's release settles on the internal `segmented.*` motion roles with UIKit's measured values, starting at the release velocity under every pointer, with the theme's `character` and `tempo` shaping the spring (`spec:AST-094` FR4, FR45, DEC-15; thresholds internal under `spec:AST-002` FR3). Under Reduce Motion the old surface fades out in place as the new one fades in (`design:reduced-motion` DR1–DR3). With a fine pointer under Reduce Motion, the theme's transition shows the change. Implementation gap: under a finger a tap's, a click's or a key's slide still plays `segmented.selectionSpring`, and under a mouse or a pen a drag's release slides on the theme's duration. | UIKit measurements (iOS 26.2); `design:reduced-motion` DR1–DR3; current tests |+| FR9 | Under every pointer, a change of selection slides the selected surface from the old segment to the new one as one surface, the radiogroup's `::before`, animating transform and opacity only. Under a touch presentation, a change that a tap, a click, a key or the program starts settles on the same spring as a drag's release, from rest: under touch, SegmentedControl's main interaction is a gesture (`spec:AST-094` FR45). Without a touch presentation, a change that a click, a key or the program starts slides on the theme's duration and easing tokens, as released. A drag's release settles on that spring from the release velocity (FR10, FR13). | Owner direction; `spec:AST-094` FR13; current source and tests |+| FR10 | A drag's release settles on the internal `segmented.*` motion roles with UIKit's measured values, starting at the release velocity under every pointer, with the theme's `character` and `tempo` shaping the spring (`spec:AST-094` FR4, FR45, DEC-15; thresholds internal under `spec:AST-002` FR3). Under Reduce Motion the old surface fades out in place as the new one fades in (`design:reduced-motion` DR1–DR3). With a fine pointer under Reduce Motion, the theme's transition shows the change. Implementation gap: under a mouse or a pen a drag's release slides on the theme's duration. | UIKit measurements (iOS 26.2); `design:reduced-motion` DR1–DR3; current tests || FR11 | Under a finger, a held unselected segment paints the pressed overlay on its part, as under a mouse (`design:user-states` DR1); no theme role changes or dims it. | `design:user-states` DR1; current tests || FR12 | During a drag of the selected surface, the selected label's colour follows the surface, with an internal hysteresis around each boundary; the weights change at the lift. A tap selects through the browser's click (`spec:AST-094` FR11). | Owner decision (weights at the lift); current tests || FR13 | Under a finger, a drag from the selected segment carries the selected surface with the finger, within an internal overshoot past the end segments, and the lift commits the segment nearest the finger through that segment's click; a drag that starts on another segment leaves the surface in place and commits where it lifts, as a menu's press-tracking slide commits where it lifts (`spec:AST-094` FR26–FR28). A mouse and a pen drag the same way (`spec:AST-094` FR43). Under Reduce Motion the surface still follows the pointer, as direct movement (`design:reduced-motion`), and a finger's release cross-fades; under a fine pointer a mouse's or a pen's release lands at once (DR3). A lift outside the control commits nothing (FR3). | `spec:AST-094` FR26–FR28, FR43; `design:reduced-motion`; current tests |@@ -230,21 +230,21 @@ segment parts as well.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |-| FR1, AR1 | `SegmentedControl.test.tsx` rendering, size, and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states | Control with several segments; sizes | Lost group semantics or name fails. Evidence gap: no test asserts the `segmented-control` target or `data-size`. | `audit:SegmentedControl/anatomy` |-| FR2, FR3, ORD2, AR2 | `SegmentedControl.test.tsx` keyboard-navigation, unmatched-value and Tab-stop cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states; the radio-group pattern's aborted-press check on `segmented-option-unselected`; the `segmented-group-selected-rtl` state's arrow round trip under `dir="rtl"`; `SegmentedControl.interaction.browser.spec.ts` slide-off cases for a finger and a mouse, with focus in the group or not | Arrows, wrap, Home, End; Tab-in with an unmatched or disabled selection | A value change on Tab entry, no wrap, or landing on a disabled segment fails. A press that slides off with focus outside the group and still selects fails. A press with focus already in the group that selects before its lift fails. | `audit:SegmentedControl/accessibility` |-| FR4, ORD1 | `SegmentedControl.test.tsx` container handler forwarding cases | Caller `onKeyDown`, with and without `preventDefault` | A caller key handler that cannot cancel navigation fails. Evidence gap: no test asserts the caller `onFocus` order or the keyboard hint. | `audit:SegmentedControl/behavior` |-| FR5 | `SegmentedControl.test.tsx` layout cases | Hug, fill, narrow row, icon-only | A control that overflows, or squeezes icon-only segments, fails. | `audit:SegmentedControl/layout` |-| FR6 | Evidence gap: no test asserts size precedence or its propagation | — | — | `audit:SegmentedControl/layout` |-| FR7, AR3 | `SegmentedControl.test.tsx` disabled and disabledMessage cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-disabled` and `segmented-group-disabled-with-message` states | Group and item disabled; with reason | A selection while disabled, or a missing reason tooltip, fails. Evidence gap: no test asserts the half opacity, or caller handlers while disabled. The `segmented-group-disabled` state declares a Tab stop. | `audit:SegmentedControl/accessibility` |-| FR8 | `SegmentedControl.test.tsx` role-override and data-testid cases | Forwarded role | A forwarded prop that overrides the role fails. Evidence gap: no test asserts `ref` or a caller `aria-describedby`. | `audit:SegmentedControl/api` |-| FR9, FR10, PR2 | `useSegmentedSelectionMotion.test.ts` slide, retarget, keyboard, Reduce Motion and fine-pointer cases; `SegmentedControl.interaction.browser.spec.ts` slide, measured-spring, Reduce Motion, busy-main-thread and mouse-click proofs in Chromium and WebKit | a tap, a retarget, keyboard selection, Reduce Motion, a mouse | a second surface or added element, a Layout or Paint per frame, a tap-, click- or key-started slide that plays a measured role instead of the theme's duration and easing tokens, a drag release under any pointer that settles from rest or on a theme curve instead of a spring from its velocity, or travel under Reduce Motion fails | `audit:SegmentedControl/theming` |-| FR11 | `SegmentedControl.interaction.browser.spec.ts` pressed-overlay proofs; `PressedState.a11y.chromium.spec.ts` segmented-control cases | a held unselected segment, a held selected segment | an unselected segment without the pressed overlay, or a dim under the default theme fails | `audit:SegmentedControl/theming` |-| FR12, FR13 | `useSegmentedSelectionMotion.test.ts` and `useSegmentedTouchTracking.test.ts` drag, face and lift cases; `SegmentedControl.interaction.browser.spec.ts` drag, overshoot, hysteresis, tap-click, slide-off, Reduce Motion drag, mouse and pen proofs | a hold, a drag, a release between segments, the end overshoot, a slow dither, a tap, a drag from another segment, a lift outside, Reduce Motion | a weight change mid-drag, a label that flips twice in a small dither, a commit anywhere but the segment nearest the finger, a commit after a lift outside, or a surface that stays put under Reduce Motion fails | `audit:SegmentedControl/anatomy` |-| PR1 | Evidence gap: no test asserts the absence of global listeners | — | — | `audit:SegmentedControl/behavior` |-| Target inventory | `packages/core/src/theme/themingTargets.test.ts` | Control and item targets | A rendered class absent from the documented targets fails. | `audit:SegmentedControl/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:SegmentedControl/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |+| FR1, AR1 | `SegmentedControl.test.tsx` rendering, size, and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states | Control with several segments; sizes | Lost group semantics or name fails. Evidence gap: no test asserts the `segmented-control` target or `data-size`. | `audit:SegmentedControl/anatomy` |+| FR2, FR3, ORD2, AR2 | `SegmentedControl.test.tsx` keyboard-navigation, unmatched-value and Tab-stop cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states; the radio-group pattern's aborted-press check on `segmented-option-unselected`; the `segmented-group-selected-rtl` state's arrow round trip under `dir="rtl"`; `SegmentedControl.interaction.browser.spec.ts` slide-off cases for a finger and a mouse, with focus in the group or not | Arrows, wrap, Home, End; Tab-in with an unmatched or disabled selection | A value change on Tab entry, no wrap, or landing on a disabled segment fails. A press that slides off with focus outside the group and still selects fails. A press with focus already in the group that selects before its lift fails. | `audit:SegmentedControl/accessibility` |+| FR4, ORD1 | `SegmentedControl.test.tsx` container handler forwarding cases | Caller `onKeyDown`, with and without `preventDefault` | A caller key handler that cannot cancel navigation fails. Evidence gap: no test asserts the caller `onFocus` order or the keyboard hint. | `audit:SegmentedControl/behavior` |+| FR5 | `SegmentedControl.test.tsx` layout cases | Hug, fill, narrow row, icon-only | A control that overflows, or squeezes icon-only segments, fails. | `audit:SegmentedControl/layout` |+| FR6 | Evidence gap: no test asserts size precedence or its propagation | — | — | `audit:SegmentedControl/layout` |+| FR7, AR3 | `SegmentedControl.test.tsx` disabled and disabledMessage cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-disabled` and `segmented-group-disabled-with-message` states | Group and item disabled; with reason | A selection while disabled, or a missing reason tooltip, fails. Evidence gap: no test asserts the half opacity, or caller handlers while disabled. The `segmented-group-disabled` state declares a Tab stop. | `audit:SegmentedControl/accessibility` |+| FR8 | `SegmentedControl.test.tsx` role-override and data-testid cases | Forwarded role | A forwarded prop that overrides the role fails. Evidence gap: no test asserts `ref` or a caller `aria-describedby`. | `audit:SegmentedControl/api` |+| FR9, FR10, PR2 | `useSegmentedSelectionMotion.test.ts` slide, retarget, keyboard, Reduce Motion and fine-pointer cases; `SegmentedControl.interaction.browser.spec.ts` slide, measured-spring, Reduce Motion, busy-main-thread and mouse-click proofs in Chromium and WebKit | a tap, a retarget, keyboard selection, Reduce Motion, a mouse | a second surface or added element, a Layout or Paint per frame, a slide under a touch presentation on a curve instead of the selection spring from rest, a click's, a key's or a program change's slide without a touch presentation off the theme's curve, a drag release under any pointer that settles from rest or on a theme curve instead of a spring from its velocity, or travel under Reduce Motion fails | `audit:SegmentedControl/theming` |+| FR11 | `SegmentedControl.interaction.browser.spec.ts` pressed-overlay proofs; `PressedState.a11y.chromium.spec.ts` segmented-control cases | a held unselected segment, a held selected segment | an unselected segment without the pressed overlay, or a dim under the default theme fails | `audit:SegmentedControl/theming` |+| FR12, FR13 | `useSegmentedSelectionMotion.test.ts` and `useSegmentedTouchTracking.test.ts` drag, face and lift cases; `SegmentedControl.interaction.browser.spec.ts` drag, overshoot, hysteresis, tap-click, slide-off, Reduce Motion drag, mouse and pen proofs | a hold, a drag, a release between segments, the end overshoot, a slow dither, a tap, a drag from another segment, a lift outside, Reduce Motion | a weight change mid-drag, a label that flips twice in a small dither, a commit anywhere but the segment nearest the finger, a commit after a lift outside, or a surface that stays put under Reduce Motion fails | `audit:SegmentedControl/anatomy` |+| PR1 | Evidence gap: no test asserts the absence of global listeners | — | — | `audit:SegmentedControl/behavior` |+| Target inventory | `packages/core/src/theme/themingTargets.test.ts` | Control and item targets | A rendered class absent from the documented targets fails. | `audit:SegmentedControl/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:SegmentedControl/theming` |## Current-state impactdiff --git a/docs/specs/components/Slider/Slider.spec.md b/docs/specs/components/Slider/Slider.spec.mdindex fdb7b90327..665492c475 100644--- a/docs/specs/components/Slider/Slider.spec.md+++ b/docs/specs/components/Slider/Slider.spec.md@@ -109,15 +109,15 @@ modes, states, and usage remain documented in `Slider.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------- |-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |-| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and DEC-1 | Approved additive target contract |-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |-| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled (after a release, once its coast settles; FR7), or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3) | Approved |-| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs or on their shared value, such as its mark label, moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. Until then the upper thumb, drawn over the lower one, holds the press, its focus and its pressed state, so a press that never moves changes no value and leaves focus on the upper thumb. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests | Accepted contract |-| FR7 | Every pointer — a finger, a pen, or a mouse — drags a thumb by its travel. A press on a thumb changes no value. Once the pointer has moved `spec:AST-094/FR19`'s 10 px from where it pressed — a distance the pointer travels, not a zone around the thumb — the value moves by the pointer's further travel along the track over the track's length, from wherever the thumb was grabbed, so the thumb never jumps to the pointer; each move is written to the thumb with no component render (`spec:AST-094/FR9`). Between coincident range thumbs, FR6's first movement is the one that crosses the 10 px. A finger or a pen claims the drag only along the track, so a swipe across it scrolls the page; a mouse claims in any direction. Under a coarse primary pointer, after hydration (`spec:AST-094/FR13`), each thumb takes a finger or a pen through a 48 px touch target that grows toward a range's other thumb only to half the gap (`spec:AST-094/FR42`), and the held thumb lifts and drops back on the theme's duration and easing tokens (`spec:AST-094/FR45`). A finger's or a pen's drag that brings the value to either end plays UISlider's end haptic where the browser can vibrate, and a mouse's drag plays none; iOS Safari has no haptic for that moment (`spec:AST-094/FR23`). After any pointer's release, a finger's, a pen's or a mouse's, the thumb coasts toward 0.4 of the release's momentum projection and settles on the `springs.sliderRelease` motion role, about 0.6 s, with `onChange` firing through the coast (`spec:AST-094/FR45`); the role is internal, with UISlider's measured value at `tempo` 1 and `'standard'`, and follows the theme's motion knobs (`spec:AST-094/FR4`). `springs.sliderLift` and `springs.sliderDrop` stay as UISlider's measured reference, and no motion plays them. Implementation gap: under a coarse primary pointer the thumb still lifts on `springs.sliderLift` and drops on `springs.sliderDrop`, and a mouse's or a pen's drag ends at its release, with no coast. A tap or a click on the track still sets the value: a finger's tap when it lifts, and a mouse press at once, where a primary click lands; a secondary click and a wheel or trackpad scroll change nothing (`spec:AST-094/FR43`). Under reduced motion the thumb does not lift, a tap's value applies at once, and the coast continues (`design:reduced-motion/DR2`). | UIKit measurements and maintainer decision (DEC-4) | Approved |+| ID | Candidate invariant | Basis | Review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- |+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and DEC-1 | Approved additive target contract |+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |+| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled (after a release, once its coast settles; FR7), or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3) | Approved |+| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs or on their shared value, such as its mark label, moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. Until then the upper thumb, drawn over the lower one, holds the press, its focus and its pressed state, so a press that never moves changes no value and leaves focus on the upper thumb. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests | Accepted contract |+| FR7 | Every pointer — a finger, a pen, or a mouse — drags a thumb by its travel. A press on a thumb changes no value. Once the pointer has moved `spec:AST-094/FR19`'s 10 px from where it pressed — a distance the pointer travels, not a zone around the thumb — the value moves by the pointer's further travel along the track over the track's length, from wherever the thumb was grabbed, so the thumb never jumps to the pointer; each move is written to the thumb with no component render (`spec:AST-094/FR9`). Between coincident range thumbs, FR6's first movement is the one that crosses the 10 px. A finger or a pen claims the drag only along the track, so a swipe across it scrolls the page; a mouse claims in any direction. Under a coarse primary pointer, after hydration (`spec:AST-094/FR13`), each thumb takes a finger or a pen through a 48 px touch target that grows toward a range's other thumb only to half the gap (`spec:AST-094/FR42`), and the held thumb lifts and drops back on springs, `springs.sliderLift` and `springs.sliderDrop`, since Slider's main interaction is a gesture (`spec:AST-094/FR45`). A finger's or a pen's drag that brings the value to either end plays UISlider's end haptic where the browser can vibrate, and a mouse's drag plays none; iOS Safari has no haptic for that moment (`spec:AST-094/FR23`). After any pointer's release, a finger's, a pen's or a mouse's, the thumb coasts toward 0.4 of the release's momentum projection and settles on the `springs.sliderRelease` motion role, about 0.6 s, with `onChange` firing through the coast (`spec:AST-094/FR45`); the role is internal, with UISlider's measured value at `tempo` 1 and `'standard'`, and follows the theme's motion knobs (`spec:AST-094/FR4`). Implementation gap: a mouse's or a pen's drag ends at its release, with no coast. A tap or a click on the track still sets the value: a finger's tap when it lifts, and a mouse press at once, where a primary click lands; a secondary click and a wheel or trackpad scroll change nothing (`spec:AST-094/FR43`). Under reduced motion the thumb does not lift, a tap's value applies at once, and the coast continues (`design:reduced-motion/DR2`). | UIKit measurements and maintainer decision (DEC-4) | Approved |### Observed current target asymmetry@@ -316,9 +316,10 @@ A thumb that jumps to the pointer changes the value on a press nobody meant as aRejected: a mouse keeping the jump to the pointer, which gives one Slider two drags by device.-`spec:AST-094/DEC-26` supersedes this decision's finger-only coast and its-measured lift: a mouse's or a pen's release coasts as a finger's does, and-the lift and drop play on the theme's duration and easing tokens.+`spec:AST-094/DEC-26` supersedes this decision's finger-only coast: a mouse's or+a pen's release coasts as a finger's does. Slider is a gesture component, so the+lift and drop play springs, `springs.sliderLift` and `springs.sliderDrop`+(`spec:AST-094` FR45).## Open questionsdiff --git a/docs/specs/components/Switch/Switch.spec.md b/docs/specs/components/Switch/Switch.spec.mdindex 7e07a15577..c3adfb5900 100644--- a/docs/specs/components/Switch/Switch.spec.md+++ b/docs/specs/components/Switch/Switch.spec.md@@ -74,15 +74,15 @@ system_specs:## Contract at a glance-| Area | Contract |-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | None changes. Switch takes `label`, `value`, `onChange`, `changeAction`, `isLoading`, `isDisabled`, `disabledMessage`, `isRequired`, `isOptional`, `status`, `size`, `labelPosition`, `labelSpacing`, field content, and base props. |-| Behavior | A native checkbox with `role="switch"` drawn as a track and thumb. A change calls `onChange`, then an optional `changeAction` with the optimistic value; while busy the switch shows a Spinner in the thumb and refuses changes. Its press and drag work for every pointer: the thumb follows a drag and settles from the release on a spring, and a tap or a key moves it on the theme's motion tokens (FR15). |-| End-user impact | People flip a setting that takes effect at once and hear when it is saving. Keyboard and screen-reader users can reach a disabled switch and its reason. |-| Builder impact | None. |-| Compatibility/readiness | Under a finger a hold and a press slid off now toggle the switch, and a tap moves the thumb on the theme's motion tokens; under a mouse or a pen the thumb now follows a drag, and a drag past the flip distance flips it (FR15); a coarse pointer's hit area grows toward 44 px (FR10); no API, default, or DOM change. Caller handlers other than `onClick` run while disabled, and caller ARIA lands on the field root; both are listed under Current-state impact. |-| Review checks | Reject a lost switch role or name, a change while disabled or busy, focus moving on change, a ring painted anywhere but the track, a thumb that travels the wrong way under RTL, or a disabled switch that submits. |-| Governing rules | `spec:AST-021` switch pattern; `spec:AST-085` FR1–FR3, FR5, FR6; `spec:AST-086` FR8; `design:user-states` DR1, DR2 (pressed overlay); `design:reduced-motion` DR1; WCAG 2.5.2, 3.2.2, 1.4.11; `spec:AST-094` FR4, FR7, FR45, FR11, FR13, FR24, FR42, FR43; `spec:AST-020` FR9 (DEC-5). |+| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | None changes. Switch takes `label`, `value`, `onChange`, `changeAction`, `isLoading`, `isDisabled`, `disabledMessage`, `isRequired`, `isOptional`, `status`, `size`, `labelPosition`, `labelSpacing`, field content, and base props. |+| Behavior | A native checkbox with `role="switch"` drawn as a track and thumb. A change calls `onChange`, then an optional `changeAction` with the optimistic value; while busy the switch shows a Spinner in the thumb and refuses changes. Its press and drag work for every pointer: the thumb follows a drag and settles from the release on a spring. Under a touch presentation a tap, a click, a key or a change of `value` settles it on the same spring from rest; without one, a click, a key or a change of `value` moves it on the theme's motion tokens, as released (FR15). |+| End-user impact | People flip a setting that takes effect at once and hear when it is saving. Keyboard and screen-reader users can reach a disabled switch and its reason. |+| Builder impact | None. |+| Compatibility/readiness | Under a finger a hold and a press slid off now toggle the switch, and under a touch presentation every tap, click or key settles the thumb on the thumb's spring from rest; under a mouse or a pen the thumb now follows a drag, and a drag past the flip distance flips it (FR15); a coarse pointer's hit area grows toward 44 px (FR10); no API, default, or DOM change. Caller handlers other than `onClick` run while disabled, and caller ARIA lands on the field root; both are listed under Current-state impact. |+| Review checks | Reject a lost switch role or name, a change while disabled or busy, focus moving on change, a ring painted anywhere but the track, a thumb that travels the wrong way under RTL, or a disabled switch that submits. |+| Governing rules | `spec:AST-021` switch pattern; `spec:AST-085` FR1–FR3, FR5, FR6; `spec:AST-086` FR8; `design:user-states` DR1, DR2 (pressed overlay); `design:reduced-motion` DR1; WCAG 2.5.2, 3.2.2, 1.4.11; `spec:AST-094` FR4, FR7, FR45, FR11, FR13, FR24, FR42, FR43; `spec:AST-020` FR9 (DEC-5). |This table is a review projection; the body below is authoritative.@@ -90,12 +90,15 @@ This table is a review projection; the body below is authoritative.Switch presents a labelled boolean setting whose change takes effectimmediately. It owns the switch control, its change and Action pipeline, busy-and disabled behavior, label placement, and the field's theming anatomy.-Its press and drag work for a mouse, a pen and a finger: the thumb follows a-drag and settles from the release on a spring under every pointer, and a tap,-a key or a change of value moves it on the theme's motion tokens (FR15).-Under a touch presentation the thumb also lifts while a finger presses-(FR13–FR15); a keyboard or assistive technology keeps its released behavior. Consumer usage lives in `Switch.doc.mjs`.+and disabled behavior, label placement, and the field's theming anatomy. Its+press and drag work for a mouse, a pen and a finger: the thumb follows a drag+and settles from the release on a spring under every pointer; under a touch+presentation a tap, a click, a key or a change of value settles it on the same+spring from rest, and without one a click, a key or a change of value moves it+on the theme's motion tokens, as released (FR15). Under a touch presentation the+thumb also lifts while a finger presses (FR13–FR15); a keyboard or assistive+technology keeps its released behavior. Consumer usage lives in+`Switch.doc.mjs`.## Compatibility and migration@@ -104,12 +107,12 @@ Under a touch presentation the thumb also lifts while a finger pressesdrag moves the thumb and past the flip distance flips it (FR15); `yes` for a keyboard andassistive technology; `size="md"`, `labelPosition="end"`,`labelSpacing="hug"`-- Compatibility class: a touch presentation adds the lift and the finger's- hold and slide-off (FR13–FR15), every pointer drags the thumb by the same- follow and flip rule and settles it on a spring (FR15), a tap under a finger- moves the thumb on the theme's motion tokens (FR15), and a coarse pointer's- hit area grows toward 44 × 44 px (FR10); every public prop, default,- export, and DOM element stays as it was+- Compatibility class: a touch presentation adds the lift and the finger's hold+ and slide-off (FR13–FR15), every pointer drags the thumb by the same follow+ and flip rule and settles it on a spring (FR15), under a touch presentation a+ tap, a click or a key settles the thumb on the same spring from rest (FR15),+ and a coarse pointer's hit area grows toward 44 × 44 px (FR10); every public+ prop, default, export, and DOM element stays as it was- Controlled/uncontrolled behavior: controlled only; `value` is required, andthe switch shows an optimistic value only while a `changeAction` is pending- Migration decision: none@@ -149,39 +152,44 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | The current render places a thumb inside the switch track and arranges that control with its label: a visually hidden native `<input type="checkbox" role="switch">` sits over a decorative track, with the label after it by default or before it with `labelPosition="start"`. | `spec:AST-021`; current source, docs, and focused tests |-| FR2 | The field, track, thumb, and label carry their existing local targets. The field reflects `data-label-position` and `data-label-spacing` only for non-default values; the track reflects `data-size`, `data-checked`, and `data-disabled`; the thumb reflects `data-size` and `data-checked`. | `architecture:component-theming-surface`; current source and tests |-| FR3 | A busy switch renders Spinner inside the thumb; a status message renders through detached FieldStatus. | Current source, docs, and focused tests |-| FR4 | The input is named by its label (or a caller `aria-labelledby`) and described by any caller description, then the description, status message, and disabled reason that exist; the description is not part of the name. A click on the label or description toggles the switch. | `spec:AST-021`; current tests |-| FR5 | A change calls `onChange(checked, event)`; unless that call prevents default, `changeAction(checked, event)` runs in a transition and the switch shows the proposed state while the Action is pending, and `value` once it settles. | Current tests |-| FR6 | While `isLoading`, or while the shown state differs from `value`, the input sets `aria-busy`, ignores pointer input, refuses changes, keeps focus, and the switch announces its busy start once per busy period through the shared channel. | `spec:AST-086` FR8; current tests |-| FR7 | Disabled: `aria-disabled="true"` on a focusable input, no `name`, detached from its form (so it neither submits nor blocks submission when required), no change, no caller `onClick` on the field, no hover or press paint, and a half-opacity track. With `disabledMessage`, a reason tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: caller DOM handlers other than `onClick`, such as `onKeyDown`, still run on the field root while disabled (`spec:AST-085` FR2). | `spec:AST-085` FR1–FR3, FR5; current tests |-| FR8 | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, and `aria-required` follows its own `isRequired` only; an off switch is an answer, so a form default (`component:FormLayout` FR5) gives it no required state; `aria-invalid` follows `status` (`false` on a required switch without an error), so the browser's own invalid state never shows before an error. | Current tests |-| FR9 | Keyboard focus paints the shared focus outline on the track. Hovering the enabled row tints the track; pressing paints the pressed overlay on both, applying `design:user-states` DR1 and DR2; a touch press fades out from the row. Track color transitions are instant under reduced motion; under a finger the colour fades with the thumb's cross-fade (FR15). | `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2 for the pressed overlay; `design:reduced-motion`; current tests |-| FR10 | The thumb travels toward the inline end when on, mirrored under RTL, and moves without a transition under reduced motion (`design:reduced-motion` DR1); under a finger it cross-fades to its rest instead (FR15). Where the primary pointer is coarse, the switch's hit area grows around the track toward 44 by 44 CSS pixels, each side stopping at half the gap to a neighbouring target so a tap goes to the nearer one (`spec:AST-094` FR42, `utils/hitArea.ts`), with nothing visible added. | WCAG 2.5.8; current tests; `design:reduced-motion` DR1; `spec:AST-094` FR42 |-| FR11 | Under forced colors, on and off stay distinguishable (Highlight track when on), and the hover tint does not hide the thumb. | WCAG 1.4.11; current tests |-| FR12 | `ref`, `onFocus`, and `onBlur` reach the input, and a caller `aria-labelledby` and `aria-describedby` name and describe it. Other base props (`id`, `data-*`, other ARIA, `onClick`, and other handlers), `className`, `style`, `xstyle`, and `width` reach the field root. Caller ARIA attributes name and describe the switch, so they MUST reach the input (`architecture:public-component-api` INV5). Implementation gap: ARIA other than `aria-labelledby` and `aria-describedby`, such as `aria-label`, lands on the field root. | Current tests; `architecture:public-component-api` INV5 |-| FR13 | The thumb is one circle under any pointer, at each state's size: a drag moves it under every pointer, a touch presentation lifts it, nothing reshapes it, and its lift and rubber band derive from the box it renders. | Owner direction, 2026-10-26 |-| FR14 | The thumb, lifted under a finger or banded past either end under any pointer, paints inside the track, in either writing direction. | Owner direction, 2026-10-25 |-| FR15 | For every pointer (`spec:AST-094` FR43) a tap, a hold of any length or a short drag toggles the switch at the release (a tap through the browser's click; where the browser sends no click for a finger's release, as for a hold, the switch clicks its input itself), and a drag commits the side it flipped the switch to, which it reaches once the pointer is the track width less the thumb width from where it pressed, toward the other end, and leaves again once the pointer comes back past where it pressed (measured in `motion/uikit/switch.ts`: `travel`, `flipDistance`). A finger's drag commits wherever the finger lifts; a mouse's or a pen's commits when it is released inside the switch's tracking bounds, its box grown by UIControl's 70 px tracking expansion. Under a finger a press slid off and lifted outside without a flip toggles it too, as `spec:AST-094` FR11 allows for a toggle under `spec:AST-020` FR9's slide-off exception (DEC-5); a mouse or a pen released outside those bounds leaves it alone, flipped or not, as the native checkbox does. Under every pointer the thumb follows the drag on `switchControl.tracking`, banded past either end, and the track's colour changes where the drag flips the switch; at the release the thumb settles to the committed end on `switchControl.travel`, starting at the release velocity, with the theme's `character` and `tempo` shaping the spring (`spec:AST-094` FR43, FR45). A tap, a hold without a drag, a key or a change of `value` moves the thumb and the track's colour on the theme's duration and easing tokens under every pointer, a finger included (`spec:AST-094` FR45). Under a touch presentation the thumb also lifts while a finger presses, on the same tokens; under a fine primary pointer it does not lift (`spec:AST-094` FR13). At a release the track's colour changes over the settle spring's computed time (`spec:AST-108` FR4a). The switch's own click, for a hold and for a flipping drag, is the exception `spec:AST-094` FR11 states for Switch. Under reduced motion nothing lifts or springs: a tap, a release or a change cross-fades the thumb to its rest and the track colour with it, while a dragging pointer still moves the thumb. A finger's slide-off toggle (`spec:AST-020` FR9, DEC-5; `spec:AST-094` FR11) meets WCAG 2.5.2 Pointer Cancellation through its Abort or Undo option: sliding back, or toggling again, undoes it. A mouse or pen released outside the tracking bounds cancels the press. | `spec:AST-094` FR11, FR13, FR43, FR45; `spec:AST-020` FR9/DEC-5; `design:reduced-motion`; WCAG 2.5.2 |+| ID | Invariant | Basis |+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | The current render places a thumb inside the switch track and arranges that control with its label: a visually hidden native `<input type="checkbox" role="switch">` sits over a decorative track, with the label after it by default or before it with `labelPosition="start"`. | `spec:AST-021`; current source, docs, and focused tests |+| FR2 | The field, track, thumb, and label carry their existing local targets. The field reflects `data-label-position` and `data-label-spacing` only for non-default values; the track reflects `data-size`, `data-checked`, and `data-disabled`; the thumb reflects `data-size` and `data-checked`. | `architecture:component-theming-surface`; current source and tests |+| FR3 | A busy switch renders Spinner inside the thumb; a status message renders through detached FieldStatus. | Current source, docs, and focused tests |+| FR4 | The input is named by its label (or a caller `aria-labelledby`) and described by any caller description, then the description, status message, and disabled reason that exist; the description is not part of the name. A click on the label or description toggles the switch. | `spec:AST-021`; current tests |+| FR5 | A change calls `onChange(checked, event)`; unless that call prevents default, `changeAction(checked, event)` runs in a transition and the switch shows the proposed state while the Action is pending, and `value` once it settles. | Current tests |+| FR6 | While `isLoading`, or while the shown state differs from `value`, the input sets `aria-busy`, ignores pointer input, refuses changes, keeps focus, and the switch announces its busy start once per busy period through the shared channel. | `spec:AST-086` FR8; current tests |+| FR7 | Disabled: `aria-disabled="true"` on a focusable input, no `name`, detached from its form (so it neither submits nor blocks submission when required), no change, no caller `onClick` on the field, no hover or press paint, and a half-opacity track. With `disabledMessage`, a reason tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: caller DOM handlers other than `onClick`, such as `onKeyDown`, still run on the field root while disabled (`spec:AST-085` FR2). | `spec:AST-085` FR1–FR3, FR5; current tests |+| FR8 | Enabled, the input submits `on` under `htmlName` when on and nothing when off; `isRequired` sets native `required`, and `aria-required` follows its own `isRequired` only; an off switch is an answer, so a form default (`component:FormLayout` FR5) gives it no required state; `aria-invalid` follows `status` (`false` on a required switch without an error), so the browser's own invalid state never shows before an error. | Current tests |+| FR9 | Keyboard focus paints the shared focus outline on the track. Hovering the enabled row tints the track; pressing paints the pressed overlay on both, applying `design:user-states` DR1 and DR2; a touch press fades out from the row. Track color transitions are instant under reduced motion; under a finger the colour fades with the thumb's cross-fade (FR15). | `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2 for the pressed overlay; `design:reduced-motion`; current tests |+| FR10 | The thumb travels toward the inline end when on, mirrored under RTL, and moves without a transition under reduced motion (`design:reduced-motion` DR1); under a finger it cross-fades to its rest instead (FR15). Where the primary pointer is coarse, the switch's hit area grows around the track toward 44 by 44 CSS pixels, each side stopping at half the gap to a neighbouring target so a tap goes to the nearer one (`spec:AST-094` FR42, `utils/hitArea.ts`), with nothing visible added. | WCAG 2.5.8; current tests; `design:reduced-motion` DR1; `spec:AST-094` FR42 |+| FR11 | Under forced colors, on and off stay distinguishable (Highlight track when on), and the hover tint does not hide the thumb. | WCAG 1.4.11; current tests |+| FR12 | `ref`, `onFocus`, and `onBlur` reach the input, and a caller `aria-labelledby` and `aria-describedby` name and describe it. Other base props (`id`, `data-*`, other ARIA, `onClick`, and other handlers), `className`, `style`, `xstyle`, and `width` reach the field root. Caller ARIA attributes name and describe the switch, so they MUST reach the input (`architecture:public-component-api` INV5). Implementation gap: ARIA other than `aria-labelledby` and `aria-describedby`, such as `aria-label`, lands on the field root. | Current tests; `architecture:public-component-api` INV5 |+| FR13 | The thumb is one circle under any pointer, at each state's size: a drag moves it under every pointer, a touch presentation lifts it, nothing reshapes it, and its lift and rubber band derive from the box it renders. | Owner direction, 2026-10-26 |+| FR14 | The thumb, lifted under a finger or banded past either end under any pointer, paints inside the track, in either writing direction. | Owner direction, 2026-10-25 |+| FR15 | For every pointer (`spec:AST-094` FR43) a tap, a hold of any length or a short drag toggles the switch at the release (a tap through the browser's click; where the browser sends no click for a finger's release, as for a hold, the switch clicks its input itself), and a drag commits the side it flipped the switch to, which it reaches once the pointer is the track width less the thumb width from where it pressed, toward the other end, and leaves again once the pointer comes back past where it pressed (measured in `motion/uikit/switch.ts`: `travel`, `flipDistance`). A finger's drag commits wherever the finger lifts; a mouse's or a pen's commits when it is released inside the switch's tracking bounds, its box grown by UIControl's 70 px tracking expansion. Under a finger a press slid off and lifted outside without a flip toggles it too, as `spec:AST-094` FR11 allows for a toggle under `spec:AST-020` FR9's slide-off exception (DEC-5); a mouse or a pen released outside those bounds leaves it alone, flipped or not, as the native checkbox does. Under every pointer the thumb follows the drag on `switchControl.tracking`, banded past either end, and the track's colour changes where the drag flips the switch; at the release the thumb settles to the committed end on `switchControl.travel`, starting at the release velocity, with the theme's `character` and `tempo` shaping the spring (`spec:AST-094` FR43, FR45). Under a touch presentation, a tap, a hold without a drag, a mouse click, a key or a change of `value` settles the thumb on the same `switchControl.travel` spring from rest, and the track's colour changes on that spring's pace: under touch, Switch's main interaction is a gesture (`spec:AST-094` FR45). Without a touch presentation, a click, a key or a change of `value` moves the thumb and the track's colour on the theme's duration and easing tokens, as released. Under a touch presentation the thumb also lifts while a finger presses, on the `switchControl.lift` spring, and settles back on `switchControl.settle` after at least `switchControl.minimumLiftMs`; under a fine primary pointer it does not lift (`spec:AST-094` FR13). At a release the track's colour changes over the settle spring's computed time (`spec:AST-108` FR4a). The switch's own click, for a hold and for a flipping drag, is the exception `spec:AST-094` FR11 states for Switch. Under reduced motion nothing lifts or springs: a tap, a release or a change cross-fades the thumb to its rest and the track colour with it, while a dragging pointer still moves the thumb. A finger's slide-off toggle (`spec:AST-020` FR9, DEC-5; `spec:AST-094` FR11) meets WCAG 2.5.2 Pointer Cancellation through its Abort or Undo option: sliding back, or toggling again, undoes it. A mouse or pen released outside the tracking bounds cancels the press. | `spec:AST-094` FR11, FR13, FR43, FR45; `spec:AST-020` FR9/DEC-5; `design:reduced-motion`; WCAG 2.5.2 |### Motion rolesThis record names these motion roles, and the generated motion role tablecarries them (`spec:AST-094` FR4, DEC-5). Each value is measured on UISwitch,-iOS 26.2 (`motion/uikit/switch.ts`), and a theme reaches them only through-its motion knobs (`spec:AST-094` DEC-15). The switch plays-`switchControl.tracking` and `switchControl.travel` for a drag and its-release under every pointer (FR15). The other rows are measured for motion-that a tap or a press starts, which plays the theme's duration and easing-tokens (`spec:AST-094` FR45), so the switch plays none of them.-Implementation gap: under a coarse primary pointer the switch still plays-`switchControl.lift`, `switchControl.settle`, `switchControl.minimumLiftMs`,-`switchControl.travel`, `switchControl.wellOn` and `switchControl.wellOff`-for a tap, and under a fine primary pointer the thumb does not follow a drag-and a release settles on the theme's duration.+iOS 26.2 (`motion/uikit/switch.ts`), and a theme reaches them only through its+motion knobs (`spec:AST-094` DEC-15). The switch plays `switchControl.tracking`+and `switchControl.travel` for a drag and its release under every pointer+(FR15). Under a touch presentation a tap, a click, a key or a change of `value`+settles on `switchControl.travel` from rest too, and the thumb lifts on+`switchControl.lift` while a finger presses and settles back on+`switchControl.settle` after at least `switchControl.minimumLiftMs`+(`spec:AST-094` FR45); the other rows stay measured references the switch does+not play. Implementation gap: under a touch presentation the switch still plays+`switchControl.wellOn` and `switchControl.wellOff` for every change, a tap, a+click, a key or a change of `value`, instead of changing the track colour on the+travel spring's pace, and under a fine primary pointer the thumb does not follow+a drag and a release settles on the theme's duration. Without a touch+presentation a click, a key or a change of `value` slides the thumb and the+track colour on `--duration-fast` and `--ease-standard`, which stays the+released behavior, not a gap.| Role | Default | Use || ----------------------------- | --------------------------------------- | ------------------------------------------------------------ |@@ -313,22 +321,22 @@ making the absence intentional.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |-| FR1, FR4 | `Switch.test.tsx` structure, label, description, and interaction suites | On/off, size, label position, hidden label | Removing stable parts, or folding the description into the name, fails; the caller description first is asserted. Evidence gap: no test asserts the label order (the position cases count children only) or the disabled reason last. | `audit:Switch/anatomy` |-| FR2 | `Switch.test.tsx` label-target, labelSpacing, and pressed-state cases; `themingTargets.test.ts` | Current local targets | A missing label, field, track, or thumb target, or a missing `data-label-spacing`, fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts `data-label-position`, or the track and thumb `data-size`, `data-checked`, and `data-disabled`. | `audit:Switch/theming` |-| FR3, FR5, FR6 | `Switch.test.tsx` loading, announcement, and status suites | Busy, pending Action, StrictMode, re-busy, detached status | Removing composed feedback, or announcing more than once per busy period, fails. Evidence gap: no test asserts the Spinner inside the thumb, `changeAction` after `onChange` with `preventDefault`, the optimistic state, or that pointer input is ignored while busy. | `audit:Switch/anatomy` |-| FR7, FR8 | `Switch.test.tsx` disabled, disabledMessage, and form cases; `PressedState.a11y.chromium.spec.ts` disabled press case | Disabled with and without reason; required; on and off | A change while disabled, a submitted disabled value, a blocked submit, or press paint on a disabled switch fails. Evidence gap: no test asserts the absent hover tint, the half-opacity track, or that caller `onKeyDown` still runs while disabled (the FR7 gap). | `audit:Switch/behavior` |-| FR8 | `FormLayout.test.tsx` required-default and switch `isRequired` cases; `Switch.test.tsx` required case | Unmarked under a required default: no `aria-required`, no `required`, and the form submits; `isRequired`: `aria-required` plus native `required`, and an off submission is blocked | An unmarked switch under a required default carrying `aria-required` or `required`, or an `isRequired` switch without both, fails. | `audit:Switch/behavior` |-| FR9–FR11 | `Switch.test.tsx` pressed-state, RTL, coarse-pointer, and forced-colors cases; `Switch.focusRing.source-build.test.mjs` | Mouse and touch press; RTL; coarse pointer; forced colors | Missing press paint, unmirrored travel, or lost forced-colors state fails. Evidence gap: no test asserts the hover tint, instant transitions under reduced motion with a mouse, or the track focus outline; the source-build check covers only how the outline finds the input. | `audit:Switch/visual` |-| FR12 | `Switch.test.tsx` rest-forwarding and ref cases | Root attributes; caller labelledby and describedby | A dropped ref, or a caller `aria-labelledby` or `aria-describedby` on the root, fails; the rest-forwarding case asserts `aria-label` on the root, which is the FR12 gap, so fixing the gap changes that test. Evidence gap: no test distinguishes `onFocus` and `onBlur` on the input from the root, or asserts a caller `onClick`, other handlers, `className`, `style`, `xstyle`, or `width` on the root. | `audit:Switch/api` |-| FR10 (coarse hit area), FR13–FR15 | `__tests__/Switch.interaction.browser.spec.ts` (Chromium and WebKit, real touch input), `__tests__/SwitchPointer.interaction.browser.spec.ts` (Chromium and WebKit, a real mouse; Chromium, a real pen), `Switch.test.tsx` hit-area cases and listener counts, and `switchTouch.test.ts` | The circle at each state's size; the 44 × 44 px hit area, and its stop halfway to a link beside it; a tap, a hold, a short drag, a flipping drag and a press slid off and lifted outside; right to left; Reduce Motion; a mouse or a pen drag past the flip, past it and back, and slid off; a click and a right click; a fine pointer's listeners at rest | A reshaped thumb, a hit area under 44 × 44 px with nothing near, a hit area past the midpoint to a neighbour, a thumb painted outside the track, a slid-off press that leaves the switch alone under a finger, a flip at any other distance, a mouse or pen drag that does not flip at the flip distance, a mouse or pen slid off that toggles, a lift under a fine pointer, a thumb that does not follow a mouse or pen drag, a release that settles on a theme curve or from rest, a tap under a finger that plays a measured role instead of the theme's tokens, or more than one listener at rest under a fine pointer fails. | `audit:Switch/behavior` |-| Switch pattern — semantics | `__tests__/Switch.a11y.test.tsx` (DOM layer, higher layers reported unrun) and `__tests__/Switch.a11y.chromium.spec.ts` (accessibility tree) | Off, on, on after a controlled update, described, hidden label, disabled, focusable-disabled, required, invalid, loading | Losing the switch role, the accessible name, the visible label's words within that name, the exposed on/off state, an attached description, or disabled, required, and invalid exposure fails the shared contract. | `audit:Switch/anatomy` |-| Switch pattern — interaction | `__tests__/Switch.a11y.chromium.spec.ts` (real browser) | Every state, each checked for what applies to it: round trips, pointer cancellation, and focus-on-change cover the operable states (off, on, on after a controlled update, described, hidden label, required, invalid); Tab reach-and-escape covers every focusable state, adding focusable-disabled and loading; inoperability covers the states the user cannot change (disabled, focusable-disabled, loading). | Losing either direction of a pointer or Space round trip, letting a mouse press slid off the control still change it (WCAG 2.5.2; under a finger FR15's reversible-toggle exception applies), moving focus when the state changes (WCAG 3.2.2), failing to reach or leave the control by Tab, or changing a state the user is not meant to be able to change fails the shared contract. | `audit:Switch/anatomy` |-| Switch pattern — label stability | `__tests__/Switch.a11y.chromium.spec.ts`, reported not gated | Every operable state: off, on, on after a controlled update, described, hidden label, required, invalid | The APG requires the label not to change with the state. No current record adopts it, so the expectation is advisory: a name that flips across a round trip is reported, and does not fail the build. | `audit:Switch/anatomy` |-| Switch pattern — state inventory | `__tests__/Switch.a11y.chromium.spec.ts` inventory assertion | Every bound state | The labels `__tests__/Switch.a11y.states.ts` claims each state renders are compared against the rendered page, so a stale inventory is reported as one rather than as a standards failure. | `audit:Switch/anatomy` |-| ORD1, ORD2, PR1 | ORD1 is covered by the FR5 and FR7 rows, and the caller-description-first part of ORD2 by the FR1 row. Evidence gap: no test asserts the rest of the ORD2 order or listener bounds | — | — | `audit:Switch/behavior` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all current targets | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |+| FR1, FR4 | `Switch.test.tsx` structure, label, description, and interaction suites | On/off, size, label position, hidden label | Removing stable parts, or folding the description into the name, fails; the caller description first is asserted. Evidence gap: no test asserts the label order (the position cases count children only) or the disabled reason last. | `audit:Switch/anatomy` |+| FR2 | `Switch.test.tsx` label-target, labelSpacing, and pressed-state cases; `themingTargets.test.ts` | Current local targets | A missing label, field, track, or thumb target, or a missing `data-label-spacing`, fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts `data-label-position`, or the track and thumb `data-size`, `data-checked`, and `data-disabled`. | `audit:Switch/theming` |+| FR3, FR5, FR6 | `Switch.test.tsx` loading, announcement, and status suites | Busy, pending Action, StrictMode, re-busy, detached status | Removing composed feedback, or announcing more than once per busy period, fails. Evidence gap: no test asserts the Spinner inside the thumb, `changeAction` after `onChange` with `preventDefault`, the optimistic state, or that pointer input is ignored while busy. | `audit:Switch/anatomy` |+| FR7, FR8 | `Switch.test.tsx` disabled, disabledMessage, and form cases; `PressedState.a11y.chromium.spec.ts` disabled press case | Disabled with and without reason; required; on and off | A change while disabled, a submitted disabled value, a blocked submit, or press paint on a disabled switch fails. Evidence gap: no test asserts the absent hover tint, the half-opacity track, or that caller `onKeyDown` still runs while disabled (the FR7 gap). | `audit:Switch/behavior` |+| FR8 | `FormLayout.test.tsx` required-default and switch `isRequired` cases; `Switch.test.tsx` required case | Unmarked under a required default: no `aria-required`, no `required`, and the form submits; `isRequired`: `aria-required` plus native `required`, and an off submission is blocked | An unmarked switch under a required default carrying `aria-required` or `required`, or an `isRequired` switch without both, fails. | `audit:Switch/behavior` |+| FR9–FR11 | `Switch.test.tsx` pressed-state, RTL, coarse-pointer, and forced-colors cases; `Switch.focusRing.source-build.test.mjs` | Mouse and touch press; RTL; coarse pointer; forced colors | Missing press paint, unmirrored travel, or lost forced-colors state fails. Evidence gap: no test asserts the hover tint, instant transitions under reduced motion with a mouse, or the track focus outline; the source-build check covers only how the outline finds the input. | `audit:Switch/visual` |+| FR12 | `Switch.test.tsx` rest-forwarding and ref cases | Root attributes; caller labelledby and describedby | A dropped ref, or a caller `aria-labelledby` or `aria-describedby` on the root, fails; the rest-forwarding case asserts `aria-label` on the root, which is the FR12 gap, so fixing the gap changes that test. Evidence gap: no test distinguishes `onFocus` and `onBlur` on the input from the root, or asserts a caller `onClick`, other handlers, `className`, `style`, `xstyle`, or `width` on the root. | `audit:Switch/api` |+| FR10 (coarse hit area), FR13–FR15 | `__tests__/Switch.interaction.browser.spec.ts` (Chromium and WebKit, real touch input), `__tests__/SwitchPointer.interaction.browser.spec.ts` (Chromium and WebKit, a real mouse; Chromium, a real pen), `Switch.test.tsx` hit-area cases and listener counts, and `switchTouch.test.ts` | The circle at each state's size; the 44 × 44 px hit area, and its stop halfway to a link beside it; a tap, a hold, a short drag, a flipping drag and a press slid off and lifted outside; right to left; Reduce Motion; a mouse or a pen drag past the flip, past it and back, and slid off; a click and a right click; a fine pointer's listeners at rest | A reshaped thumb, a hit area under 44 × 44 px with nothing near, a hit area past the midpoint to a neighbour, a thumb painted outside the track, a slid-off press that leaves the switch alone under a finger, a flip at any other distance, a mouse or pen drag that does not flip at the flip distance, a mouse or pen slid off that toggles, a lift under a fine pointer, a thumb that does not follow a mouse or pen drag, a release that settles on a theme curve or from rest, a tap, a click, a key or a `value` change under a touch presentation that settles on a curve instead of `switchControl.travel` from rest, a click, a key or a `value` change without a touch presentation that leaves the theme's curve, or more than one listener at rest under a fine pointer fails. | `audit:Switch/behavior` |+| Switch pattern — semantics | `__tests__/Switch.a11y.test.tsx` (DOM layer, higher layers reported unrun) and `__tests__/Switch.a11y.chromium.spec.ts` (accessibility tree) | Off, on, on after a controlled update, described, hidden label, disabled, focusable-disabled, required, invalid, loading | Losing the switch role, the accessible name, the visible label's words within that name, the exposed on/off state, an attached description, or disabled, required, and invalid exposure fails the shared contract. | `audit:Switch/anatomy` |+| Switch pattern — interaction | `__tests__/Switch.a11y.chromium.spec.ts` (real browser) | Every state, each checked for what applies to it: round trips, pointer cancellation, and focus-on-change cover the operable states (off, on, on after a controlled update, described, hidden label, required, invalid); Tab reach-and-escape covers every focusable state, adding focusable-disabled and loading; inoperability covers the states the user cannot change (disabled, focusable-disabled, loading). | Losing either direction of a pointer or Space round trip, letting a mouse press slid off the control still change it (WCAG 2.5.2; under a finger FR15's reversible-toggle exception applies), moving focus when the state changes (WCAG 3.2.2), failing to reach or leave the control by Tab, or changing a state the user is not meant to be able to change fails the shared contract. | `audit:Switch/anatomy` |+| Switch pattern — label stability | `__tests__/Switch.a11y.chromium.spec.ts`, reported not gated | Every operable state: off, on, on after a controlled update, described, hidden label, required, invalid | The APG requires the label not to change with the state. No current record adopts it, so the expectation is advisory: a name that flips across a round trip is reported, and does not fail the build. | `audit:Switch/anatomy` |+| Switch pattern — state inventory | `__tests__/Switch.a11y.chromium.spec.ts` inventory assertion | Every bound state | The labels `__tests__/Switch.a11y.states.ts` claims each state renders are compared against the rendered page, so a stale inventory is reported as one rather than as a standards failure. | `audit:Switch/anatomy` |+| ORD1, ORD2, PR1 | ORD1 is covered by the FR5 and FR7 rows, and the caller-description-first part of ORD2 by the FR1 row. Evidence gap: no test asserts the rest of the ORD2 order or listener bounds | — | — | `audit:Switch/behavior` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all current targets | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |No repository check resolves `delegatesTo` owner and target pairs; the pairsabove match the current Spinner and FieldStatus targets.diff --git a/scripts/motion-roles-table.mjs b/scripts/motion-roles-table.mjsindex 0afaf2a180..cba6cf219d 100644--- a/scripts/motion-roles-table.mjs+++ b/scripts/motion-roles-table.mjs@@ -109,7 +109,7 @@ export function renderMotionRoleTable(roles, {fr4, records}) {'','# Motion roles','',- "Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. A role plays only for motion a gesture drives (`spec:AST-094` FR45). Motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Three approved motions keep their springs until their own records change: the layout glide (`spec:AST-105` FR4), the animator's `animate` (`spec:AST-107` FR3), and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.",+ "The owner's goal: \"The main goals are consistent timings and well-coordinated pieces.\" The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: \"The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion.\" A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.",'','| Role | Kind | Default | Named by |','| --- | --- | --- | --- |',