Skip to content

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

TypeScript

docs(core): the scroll-to-top note says what Reduce Motion does with a tap-started decay (#8494)

Cindy Zhang3ab7f32dbe84
diff --git a/.changeset/scroll-to-top-reduced-motion-note.md b/.changeset/scroll-to-top-reduced-motion-note.md
new file mode 100644
index 0000000000..f8fb37fba3
--- /dev/null
+++ b/.changeset/scroll-to-top-reduced-motion-note.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the UIKit scroll table's scroll-to-top note says that under Reduce Motion a tap-started scroll to the top cross-fades on a coarse pointer and jumps otherwise, since only momentum after a throw keeps decaying. No behavior change.
+
+@cixzhang
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
index b4eefd7876..4c85d6ed55 100644
--- a/packages/core/src/motion/uikit/scroll.ts
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -113,9 +113,12 @@ export const scroll = {
* approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
* 1.6 s for 500, 2000 or 8000 pt), which is a decay at this per-millisecond
* rate (e^(−0.0097)) whose rest point is the top: a decay with a
- * starting velocity of 9.7 × the distance per second. It is not a throw's
- * momentum, so under Reduce Motion it does not coast: it follows
- * `design:reduced-motion` DR2 (the coast exception covers only a throw).
+ * starting velocity of 9.7 × the distance per second. A tap starts it, not
+ * a throw, so under Reduce Motion it is a transition, not a coast: it
+ * cross-fades to the top within 200 ms on a coarse pointer (DR2) and jumps
+ * there on any other (DR3). Only momentum that continues a throw keeps
+ * decaying under Reduce Motion (`design:reduced-motion` DR2, DEC-2), so a
+ * component checks for Reduce Motion before it plays this decay.
* @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
* iPhone 17 Pro, setContentOffset log after status-bar taps (starts 85–95
* ms after the tap), Oct 23 2026