An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-094): a native scroll takes a touch after 10 px; touch-action never widens the author's (DEC-8) (#8453)
Cindy Zhangde3ba5e5c514
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 592cafb04a..d92470a9f9 100644--- a/docs/specs/AST-094-touch-presentations/spec.md+++ b/docs/specs/AST-094-touch-presentations/spec.md@@ -80,11 +80,18 @@ a measured, sourced difference exists.The values this record names for menus under a finger (FR29):- | Value | Default | Source |- | ---------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |- | Open delay | none in a fixed bar; 150 ms with no scroll inside a scroll view (the content-touch delay, FR11) | owner decision, 2026-10-24, departing from UIKit on the iOS 26.2 simulator (iPhone 17 Pro), 2026-10-23, which opened a held finger's menu 150–153 ms after touch-down in a fixed position and about 303 ms inside a scroll view |- | Handoff distance | 10 pt (CSS px), straight-line, from the first position the open menu sees | measured: same setup; moves of (0, 9) and (7, 7) picked nothing, and (0, 10), (10, 0) and (9, 9) picked |- | Drift allowance | 13 pt (CSS px) of movement on the trigger before the open | unmeasured, needs a measurement or justification: a 12 pt move still opened the menu and a 14 pt move did not (OQ5) |+ | Value | Default | Source |+ | ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+ | Open delay | none in a fixed bar; 150 ms with no scroll taking the touch inside a scroll view (the content-touch delay, FR11) | owner decision, 2026-10-24, departing from UIKit on the iOS 26.2 simulator (iPhone 17 Pro), 2026-10-23, which opened a held finger's menu 150–153 ms after touch-down in a fixed position and about 303 ms inside a scroll view |+ | Handoff distance | 10 pt (CSS px), straight-line, from the first position the open menu sees | measured: same setup; moves of (0, 9) and (7, 7) picked nothing, and (0, 10), (10, 0) and (9, 9) picked |+ | Drift allowance | 13 pt (CSS px) of movement on the trigger before the open | unmeasured, needs a measurement or justification: a 12 pt move still opened the menu and a 14 pt move did not (OQ5) |++ The scroll take distance FR20 names is 10 px (CSS px) of the finger's own+ travel from where it went down: measured along one axis in Mobile Safari+ 26.2 on the iOS 26.2 simulator with a slow HID drag on a scrollable page,+ where the last cancelable `touchmove` is at 10 px and `pointercancel` at+ 11 px, 2026-10-23. Measuring it straight-line for a diagonal drag is a guess+ until a diagonal drag on the same setup measures it.- **FR3 — Native physics.** Springs MUST follow UIKit's spring model(response and damping ratio, mass, stiffness and damping, and the release@@ -168,8 +175,9 @@ a measured, sourced difference exists.finger lifts during a block, and lets a finger catch the content mid-flight.- **FR10 — A second finger never breaks the first.** A second finger MUST NOTcancel or redirect a drag a recognizer has claimed. Page pinch-zoom MUST stay- the browser's whenever no pinch recognizer claims the fingers and no drag is- claimed (WCAG 1.4.4). A menu's press-tracking slide keeps+ the browser's whenever no pinch recognizer claims the fingers, no drag is+ claimed, and the element's author `touch-action` keeps `pinch-zoom` (FR18;+ WCAG 1.4.4). A menu's press-tracking slide keeps`module:DropdownMenu/useMenuPress` FR4: a second pointer or `pointercancel`ends its gesture with nothing acting, which keeps the page zoomable over anopen menu.@@ -179,8 +187,8 @@ a measured, sourced difference exists.control's press ends when the browser takes the touch (FR20), and itsactivation stays the browser's click.A cell (a table or collection cell) highlights 150 ms after touch-down inside- a scroll view, drops the highlight when the scroll wins, and activates on a- lift inside it with no scroll. A control is inside a scroll view when it sits in a scrollable container,+ a scroll view, drops the highlight when the scroll wins (FR20), and activates on a+ lift inside it with no scroll taking the touch (FR20). A control is inside a scroll view when it sits in a scrollable container,or in scrolling page content with no fixed ancestor; a control in a fixedbar (a top bar, a tab bar, a toolbar) is not. A control inside a scroll viewtakes the same 150 ms delay before its highlight and then follows its@@ -232,7 +240,10 @@ a measured, sourced difference exists.its recognizers do not use: the other axis for an axis-limited pan or swipe,`manipulation` for taps and long presses, everything for a one-way pan or apan that shares its axis with native scrolling. `pinch-zoom` MUST stay- unless a pinch or rotation recognizer is attached.+ unless a pinch or rotation recognizer is attached. The derived value is+ intersected with the element's own author `touch-action` and is never wider+ than it (DEC-8); when the author's value leaves out `pinch-zoom`, the+ author's value wins.- **FR19 — Claims are made in time and only by an owner.** Recognizers attach only where the primary pointeris coarse (FR13, DEC-6). Where the primary pointer is fine, no recognizerattaches and no touch listener is registered (FR24), so a finger on a@@ -260,7 +271,9 @@ a measured, sourced difference exists.drags to the scroll.- **FR20 — The browser can take a touch.** `pointercancel`, an uncancelable`touchmove`, or a native scroll under the touch MUST count as the browser- taking the touch: possible recognizers that share it fail, active ones are+ taking the touch, a native scroll only once that finger has moved the scroll+ take distance (FR2), so sub-pixel movement under a still finger does not+ cancel a tap (DEC-8): possible recognizers that share it fail, active ones arecancelled, and the view's press is cancelled without a release. A recognizer that never claims (a watcher) registers only passivelisteners (`architecture:react-component-runtime` INV3, INV5), and awatcher is not cancelled when the browser takes the touch: it follows the@@ -306,8 +319,8 @@ FR33 apply to menus only. A mouse keeps today's behavior.sub-menu rows and Selector keep their own opening. Under a finger, aDropdownMenu trigger in a fixed bar MUST open its menu as the fingerpresses. A trigger inside a scroll view (FR11) MUST open it once the 150 ms- content-touch delay has passed with no scroll, or at the lift of a tap that- ends sooner; a scroll that starts first takes the touch and nothing opens. Before the open, the finger may move no+ content-touch delay has passed with no scroll taking the touch (FR20), or at the lift of a tap that+ ends sooner; a scroll that takes the touch first (FR20) takes it and nothing opens. Before the open, the finger may move nomore than the drift allowance (FR2). After an open under a held finger,nothing is lit and a lift acts on nothing until the finger has travelledthe handoff distance from the first position the open menu sees; from then@@ -332,7 +345,8 @@ FR33 apply to menus only. A mouse keeps today's behavior.- **FR32 — A pan outside dismisses.** Under a finger, an open anchored menu MUST close as a touch outside itbegins to pan, and at the lift of a tap or hold outside it. A Popover'sdismissal is unchanged. A pinch stays available over it: its surface- never takes `touch-action: none`, so the page keeps zooming (FR10, FR18;+ never takes `touch-action: none`, so the page keeps zooming unless the+ author's own `touch-action` leaves out `pinch-zoom` (FR10, FR18;WCAG 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).@@ -500,30 +514,30 @@ FR33 apply to menus only. A mouse keeps today's behavior.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| 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 |-| 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, or a theme that changes a role before the public set is decided 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 layout read, a jump, or a lost velocity 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 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 |-| 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 blocked page pinch, 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 | the wrong profile's timing, a press that survives the browser taking the touch, or a control activated other than by the browser's click 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 |-| FR14 | Browser tests of a sheet over a scrolled list | scrolled and at its top | a midway handoff fails |-| FR15–FR17 | Recognizer unit tests on synthetic streams with explicit timestamps | exclusive, simultaneous, require-to-fail, nested; a blocked main thread; a pan at 10 pt per axis | a wrong winner, a late deadline, or a translation that keeps the hysteresis fails |-| FR18–FR22 | Browser tests with real touch input | per-axis pans beside native scrolling, page zoom, cancelled touches, clicks after taps, keyboard activation, a modal scroll lock, a control that keeps its press through a drag | a ghost click, a blocked scroll or zoom, or a cancelled unowned touchmove outside FR19's two exceptions fails |-| FR23 | Haptics tests on the recorded moments | tap, drag, lift | a haptic outside a native moment fails |-| FR24 | Resource tests counting listeners, observers and timers | fine primary pointer; coarse pointer enabled and disabled; many instances; unmount | a touch listener on a fine pointer, a per-instance `document` or `window` listener, or a leak fails |-| FR25 | Component tests of each moved default and its `presentation` value | default; `presentation` set to the released surface | a moved default that `presentation` does not restore, or a public threshold, fails |-| FR26–FR28, FR30 | Menu press tests on synthetic touch streams and a real-Chromium touch test | a slide from one row to another; a lift outside; a cancel; a second finger; edge autoscroll | an act on the press-start row, two acts for one gesture, a lift outside that closes, or a lit row after a cancel fails |-| FR29 | Trigger tests with explicit timestamps | a press in a fixed bar; a press in scrolling content held 149 and 150 ms; a quick tap in scrolling content; a scroll before 150 ms; a drift of 12 and 14 pt; moves before and after the handoff; `presentation="popover"` | a fixed-bar press that waits, a held finger's scroll-view open before 150 ms or after a scroll, a quick tap that does not open at its lift, an open past the drift allowance, a lift that acts before the handoff, or a `popover` trigger that opens on press fails |-| FR31–FR33 | Browser tests and storyboards under a finger | a menu, a Popover and a ContextMenu lift: open, close, a pan outside, a tap outside, a pinch over the surface; a mouse | a surface that does not grow from and shrink into its trigger, a pan outside that leaves a menu open, a Popover whose dismissal changed, a blocked pinch, a tap outside that reaches the page, or a changed mouse path fails |-| FR34, FR35 | Browser tests and storyboards under a finger | a sub-menu drilling in and its Back row returning; a tap and a drag during a popover's and a menu's growth; a pinch during growth; a mouse | a drill-in that leaves the parent's rows in place, a change between levels that does not play on its roles, a tap during growth that closes, scrolls or moves focus, a blocked pinch, or a changed mouse path fails |-| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails |-| FR41 | Browser tests with real touch input (`spec:AST-013` FR10) | a tap; a long press on a ContextMenu trigger, a DropdownMenu trigger the caller renders, a row with a context menu, and a slider thumb; a long press on a checkbox row's label and on plain text; a cancelled press; mouse and keyboard selection | a tap that selects, a hold with an action that starts a selection or callout, a label or plain text whose long press does not select natively, a suppression that outlives the press, or a change to native selection elsewhere or to mouse, keyboard, or assistive-technology selection fails |-| all | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices | per component | an unmatched curve or timing is a parity defect |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| 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 |+| 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, or a theme that changes a role before the public set is decided 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 layout read, a jump, or a lost velocity 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 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 |+| 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 | the wrong profile's timing, a press that survives the browser taking the touch, or a control activated other than by the browser's click 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 |+| FR14 | Browser tests of a sheet over a scrolled list | scrolled and at its top | a midway handoff fails |+| FR15–FR17 | Recognizer unit tests on synthetic streams with explicit timestamps | exclusive, simultaneous, require-to-fail, nested; a blocked main thread; a pan at 10 pt per axis | a wrong winner, a late deadline, or a translation that keeps the hysteresis fails |+| FR18–FR22 | Browser tests with real touch input (`spec:AST-013` FR10) | per-axis pans beside native scrolling, page zoom, cancelled touches, clicks after taps, keyboard activation, a modal scroll lock, a control that keeps its press through a drag; a still finger with sub-pixel jitter over a scroll view; a finger moved 9 px and 10 px straight, and (7, 7) and (8, 8) diagonally; a recognizer on an element whose author `touch-action` is narrower, including one without `pinch-zoom` | a ghost click, a scroll or zoom blocked other than by the author's `touch-action`, or a cancelled unowned touchmove outside FR19's two exceptions, a tap cancelled by sub-pixel movement or by under 10 px of travel, a scroll that does not take the touch at 10 px, or a derived `touch-action` wider than the author's fails |+| FR23 | Haptics tests on the recorded moments | tap, drag, lift | a haptic outside a native moment fails |+| FR24 | Resource tests counting listeners, observers and timers | fine primary pointer; coarse pointer enabled and disabled; many instances; unmount | a touch listener on a fine pointer, a per-instance `document` or `window` listener, or a leak fails |+| FR25 | Component tests of each moved default and its `presentation` value | default; `presentation` set to the released surface | a moved default that `presentation` does not restore, or a public threshold, fails |+| FR26–FR28, FR30 | Menu press tests on synthetic touch streams and a real-Chromium touch test | a slide from one row to another; a lift outside; a cancel; a second finger; edge autoscroll | an act on the press-start row, two acts for one gesture, a lift outside that closes, or a lit row after a cancel fails |+| FR29 | Trigger tests with explicit timestamps | a press in a fixed bar; a press in scrolling content held 149 and 150 ms; a quick tap in scrolling content; a scroll taking the touch before 150 ms; a drift of 12 and 14 pt; moves before and after the handoff; `presentation="popover"` | a fixed-bar press that waits, a held finger's scroll-view open before 150 ms or after a scroll, a quick tap that does not open at its lift, an open past the drift allowance, a lift that acts before the handoff, or a `popover` trigger that opens on press fails |+| FR31–FR33 | Browser tests and storyboards under a finger | a menu, a Popover and a ContextMenu lift: open, close, a pan outside, a tap outside, a pinch over the surface; a mouse | a surface that does not grow from and shrink into its trigger, a pan outside that leaves a menu open, a Popover whose dismissal changed, a pinch blocked other than by the author's `touch-action`, a tap outside that reaches the page, or a changed mouse path fails |+| FR34, FR35 | Browser tests and storyboards under a finger | a sub-menu drilling in and its Back row returning; a tap and a drag during a popover's and a menu's growth; a pinch during growth; a mouse | a drill-in that leaves the parent's rows in place, a change between levels that does not play on its roles, a tap during growth that closes, scrolls or moves focus, a pinch blocked other than by the author's `touch-action`, or a changed mouse path fails |+| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails |+| FR41 | Browser tests with real touch input (`spec:AST-013` FR10) | a tap; a long press on a ContextMenu trigger, a DropdownMenu trigger the caller renders, a row with a context menu, and a slider thumb; a long press on a checkbox row's label and on plain text; a cancelled press; mouse and keyboard selection | a tap that selects, a hold with an action that starts a selection or callout, a label or plain text whose long press does not select natively, a suppression that outlives the press, or a change to native selection elsewhere or to mouse, keyboard, or assistive-technology selection fails |+| all | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices | per component | an unmatched curve or timing is a parity defect |## Decision log@@ -606,6 +620,19 @@ watching a touch never delays the browser's scroll, and it is not cancelledwhen the browser takes the touch: it follows the scroll to the lift, so a barthat reacts to scrolling keeps hearing it.+### DEC-8 — A native scroll takes a touch after 10 px; touch-action never widens the author's++**Reference:** `spec:AST-094/DEC-8`+**Decider:** `cixzhang`, `2026-10-25`++A still finger often reports sub-pixel movement, and treating that as a scroll+cancels taps the person meant, so a native scroll counts as the browser+taking the touch only once the finger has moved 10 px. An author who narrows+an element's `touch-action` has a reason, so the value derived from+recognizers is intersected with it and never grants the browser more.++Rejected: cancelling at the first scroll event, and overriding the author's `touch-action`.+### DEC-9 — A hold does its action, not a selection; copying is the caller's menu item**Reference:** `spec:AST-094/DEC-9`