utils/unified-design-system/DOCS-motion.md

Motion, haptics and sound (frozen values)

Split out of tokens.md on 2026-08-22 to hold every file under the shared 250-line cap, when the motion scale was added. Both are part of the same token spec — this is a filing change, not a scoping change.

Not yet checked by a script. scripts/palette_check.py parses #RRGGBB only, so every value below is invisible to it — a --duration-fast: 120ms matches none of its four parsers. palette_map.py:159 claims structural values are "checked by the scale check"; no such script exists yet. Until dopamine-ux prompt 02 writes it, these three stacks are kept in agreement by hand, and editing a value here means editing it in web_ui/src/tokens.css and design_system/lib/src/tokens.dart in the same commit.

Duration

Four steps. The scale is deliberately short: a duration vocabulary with ten entries gets picked from at random, which is drift wearing a token's name.

Token	Value	Rationale
instant	0ms	No animation. The reduced-motion collapse target, and the honest choice for anything that must feel direct.
fast	120ms	State on an element already under the cursor/finger — hover, press, checkbox, ripple. Below ~100ms reads as instant, so this is the floor at which motion is perceived as motion.
base	200ms	The default. Anything that enters, leaves or moves within the current view: toasts, expanding rows, tab switches.
slow	320ms	Full-surface change — sheets, dialogs, page transitions. Above ~350ms the interface feels like it is waiting on itself, so this is the ceiling, not a midpoint.

Anything needing a duration not on this scale is a signal the interaction is wrong, not that the scale is short.

Easing

Three curves, as cubic-bezier control points. Named for what the motion does at its end, because that is the part the eye actually reads.

Token	Cubic-bezier	Rationale
standard	(0.2, 0, 0, 1)	The default for anything that starts and ends on screen. Fast out of the gate, settles gently.
decelerate	(0, 0, 0, 1)	Entering the screen. Starts at full speed (the element is already "in motion" from off-stage) and eases to rest.
accelerate	(0.3, 0, 1, 1)	Leaving the screen. Eases in, exits at speed — no settle, because there is nothing to settle onto.

Never ease-in-out on an element that enters or exits: symmetric easing makes an arrival look like it is braking into place and a departure look reluctant.

Reduced motion — mandatory

Motion tokens collapse to 0ms. Easing becomes irrelevant at zero duration and needs no separate handling.

Stack	How it is detected
web/React	@media (prefers-reduced-motion: reduce)
Flutter/Dart	MediaQuery.of(context).disableAnimations
Python/Tk	n/a (tk) — see below

Haptics and sound are unaffected. They are not motion, and a user who suppresses animation has not asked to be denied confirmation that a tap landed. This is the rule most often got wrong by collapsing all feedback under one flag.

The OS motion preference is honoured automatically and is not the sound toggle. The sound opt-out is a separate, user-facing setting (below).

Haptics

Mapped onto Flutter's HapticFeedback API. This is the highest-value row in this file: HapticFeedback comes from flutter/services.dart and needs no new dependency, so an app can adopt it the day it reads this.

Semantic event	Call	Rationale
Selection changed (tab, chip, picker)	selectionClick	The lightest cue available. Fires often, so it must be nearly free.
Recorded something (meal, workout, task)	lightImpact	The confirming tap. Fires on the recording, not on the number recorded — see the corollary below.
Completed a whole flow (finished a workout, closed a streak)	mediumImpact	Reserved for genuine completion. If everything is mediumImpact, nothing is.
Error / rejected input	heavyImpact	Distinct by weight, not just by pattern — the one cue that must be felt without looking.

Reward the recording, never the number recorded. The haptic on logging a meal is legitimate; a haptic on hitting a calorie target rewards eating less rather than recording honestly, and corrupts the app's own data. Same shape in workout_app (reward logging a workout, not beating a PB) and todo (reward capture, not completion count).

Sound

Three named semantic cues. Each app owns its own asset files — this file freezes the vocabulary and the policy, not the audio.

Cue	Fires when
confirm	An action was recorded. Pairs with lightImpact.
complete	A flow finished. Pairs with mediumImpact.
error	Input was rejected. Pairs with heavyImpact.

Policy:

1. Sound ships on, as an opt-out. A cue nobody ever hears is not a cue. The toggle is per-app and user-facing.
2. The sound toggle is not the reduced-motion preference, and neither implies the other. Two settings, two meanings.
3. Never a cue without its haptic sibling. Sound is the part that fails — silenced phone, no speaker, noisy room — so it is the redundant channel, and the haptic carries the meaning alone whenever it has to.
4. Keep cues under ~300ms. A sound outlasting slow is still playing after the thing it describes has finished.

Stack mapping

Stack	File	Form
Flutter/Dart	design_system/lib/src/tokens.dart	class AppDuration / class AppCurve
web/React	web_ui/src/tokens.css	--duration-* / --ease-* custom props
Python/Tk	gatelock/gatelock/_window.py	n/a (tk)

n/a (tk): Tkinter has no animation framework, and gatelock's LockConfig carries no motion values. Adding them for symmetry would ship a dead constant that reads as a supported feature — an honest n/a beats a lie about scope. Haptics and sound are likewise n/a there: it is a fullscreen desktop lock surface with no haptic hardware.

Only ~/todo consumes design_system as a package; diet-guard, workout_app and wake_alarm hand-transcribe these values into local lib/ui/theme.dart copies. Tokens added here therefore reach exactly one app automatically — the rest is per-app work, which is what dopamine-ux prompts 03–09 are for.