utils/dopamine-ux/01-motion-tokens.md

Add motion, haptic and sound tokens to the unified design system

findings (3, ranked by value over effort)

1. No motion token exists in any stack — greenfield. Every app that wants an animation currently invents its own number, and one already has.
2. No haptic vocabulary exists — the highest-value gap, because HapticFeedback needs no dependency, so three of four apps can adopt it the day this lands.
3. tokens.md is 260 lines against a 250 cap — it cannot absorb a new section, so motion needs a sibling file.

what

The shared design system has colour, spacing, radius, type and shadow tokens — and no motion tokens at all. Verified 2026-08-16: no Duration, Curve, --duration-*, --ease-*, or haptic constant exists in any stack copy. There is not even a prose position that motion is out of scope.

Consequence across kuhy's Flutter fleet: exactly one animation exists in four apps — a lone AnimatedContainer(duration: Duration(milliseconds: 200)) with an inline magic number. Every other transition is a Flutter/browser default.

Create the motion token layer so the per-app prompts (03–09) have something canonical to consume instead of each inventing durations.

where

Repo: ~/utils (git repo, has CI + the file-length gate wired).

Create ~/utils/unified-design-system/motion.md — the prose freeze.

Do NOT append to ~/utils/unified-design-system/tokens.md. It is 260 lines and the cap is 250, so it already fails the gate; adding to it makes that worse. screen-size.md was split out of it for exactly this reason — follow that precedent and add a pointer line in tokens.md only if you can do so without growing it (i.e. by shortening another line).

Then mirror the tokens into the three code stacks:

Stack	File	Form
Flutter/Dart	~/utils/design_system/lib/src/tokens.dart	class AppDuration / class AppCurve
web/React	~/utils/web_ui/src/tokens.css	--duration-*, --ease-* custom props
Python/Tkinter	~/utils/gatelock/gatelock/_window.py (class LockConfig)	int ms fields — only if meaningful; see must not

There are three code stacks plus the prose freeze. Do not go hunting for a fourth — it does not exist.

must

• Define a small scale. Recommended, but use judgement: instant 0ms · fast 120ms · base 200ms · slow 320ms, and easing standard (0.2, 0, 0, 1) · decelerate (0, 0, 0, 1) · accelerate (0.3, 0, 1, 1). Justify each value in motion.md in one line — the file is a freeze, so the reasoning has to survive without you.

• Include a haptic vocabulary mapped to Flutter's HapticFeedback API: which semantic event gets selectionClick vs lightImpact vs mediumImpact. This is the highest-value part — HapticFeedback needs no dependency, so three of four apps can adopt it immediately.

• Include a sound vocabulary: named semantic cues (confirm, complete, error) with the rule that sound ships on (opt-out) per app, and that each app owns its own asset files.

• State the reduced-motion contract in motion.md: web uses @media (prefers-reduced-motion: reduce), Flutter uses MediaQuery.of(context).disableAnimations. Motion tokens collapse to 0ms under it; haptics and sound are unaffected (they are not motion).

• Keep every file at or under 250 lines (~/utils/file_length/config.py, MAX_LINES = 250). .md and .py are capped; .css is not.

• Cut tags at the end — this is the step that makes the work reach consumers:

  • design_system-v0.2.0 (consumed by ~/todo, currently on v0.1.0)
  • web_ui-v0.3.2 (consumed by ~/dufs-cloud/web, currently on v0.3.1) Print both tag names at the end of the session; prompts 06, 07 and 08 need them.

• must not: add motion values to the Tkinter LockConfig just for symmetry. Tkinter has no animation framework. If a duration has no meaning there, mark the row n/a (tk) in motion.md and leave the Python alone. An honest n/a beats a dead constant.

• must not: express any motion token as a hex-looking value. The existing palette_check.py parses #RRGGBB and would either ignore it or trip on it.

• must not: touch any colour token, or add a colour alongside the motion work. That would break palette_check.py's completeness half.

• must not: add # noqa or type: ignore anywhere.

• optional: a prefers-reduced-motion helper in ~/utils/design_system/lib/src/ and/or web_ui/src/ so consumers get the collapse behaviour without reimplementing it. Nice, not required.

done

All four hold:

1. ~/utils/unified-design-system/motion.md exists, is ≤250 lines, and defines duration, easing, haptic and sound vocabularies with a one-line rationale each.
2. python3 ~/utils/file_length/check.py (or ~/utils/scripts/check_file_length.sh --all) reports no new violations. tokens.md (260), nielsen-audit.md (258) and README.md (257) are pre-existing failures — do not fix them here, but do not add a fourth.
3. python3 ~/utils/unified-design-system/scripts/palette_check.py still exits 0.
4. Both tags exist: git -C ~/utils tag | grep -E 'design_system-v0.2.0|web_ui-v0.3.2' prints two lines.

verify

Desktop, any way you like — this prompt ships no UI. Run the two gate commands in done and paste their output. Then confirm the token names you chose are what prompts 03–09 will reference by printing the Dart class and the CSS custom-prop block.

read first

• ~/utils/unified-design-system/tokens.md — the existing freeze; match its table format and tone exactly. Note its length problem before editing.
• ~/utils/unified-design-system/screen-size.md — the precedent for a sibling file split out of tokens.md (32 lines; short and self-contained).
• ~/utils/design_system/lib/src/tokens.dart — AppPalette, AppSpacing, AppRadius, AppTextSize. Your AppDuration/AppCurve sit alongside these.
• ~/utils/web_ui/src/tokens.css — the full custom-prop list.
• ~/utils/design_system/lib/src/feedback.dart — showToast/showError and _show. confirm.dart next to it already imports package:flutter/services.dart, so HapticFeedback is one call away with no new import. This is the natural home for a shared haptic helper.
• ~/utils/unified-design-system/scripts/palette_check.py — read the four parse_* regexes to see why motion tokens are invisible to it. Prompt 02 builds the checker that covers them; do not extend this script here.

context you would otherwise rediscover

• Green CI does not mean no drift for these tokens. palette_check.py only matches #RRGGBB, so a --duration-fast: 120ms is invisible to every one of its parsers. palette_map.py:159 claims structural values are "checked by the scale check" — no such script exists. Prompt 02 writes it.
• ~/utils/gatelock/ is a package inside the ~/utils monorepo, not a standalone repo. It is consumed as a pinned git dependency.
• Only ~/todo depends on design_system; diet-guard, workout_app and wake_alarm hand-transcribe the token values into local lib/ui/theme.dart copies. So tokens added here reach exactly one app automatically — the others are handled per-prompt.