utils/dopamine-ux/TODO-02-structural-check.md

Add a structural-token drift checker to CI

findings (2, ranked by value over effort)

1. Spacing, radius and type have never been drift-checked — palette_check.py parses hex only, so three whole token categories can diverge across stacks while CI stays green. Motion inherits the same hole.
2. palette_map.py points at a "scale check" that does not exist — a comment describing a guarantee nobody wrote.

what

palette_check.py guarantees the colour palette agrees across all stack copies. It does not check anything else — verified 2026-08-16 by reading its four parsers, every one of which requires a #RRGGBB value:

parse_css : r"(--[a-z0-9-]+)\s*:\s*(#[0-9A-Fa-f]{6})\s*;"
parse_dart: r"static const Color (\w+) = Color\(0x[fF]{2}([0-9A-Fa-f]{6})\)"
parse_tk  : r'^\s{4}(\w+):\s*str\s*=\s*"(#[0-9A-Fa-f]{6})"'
parse_md  : r"^\|\s*`([a-z0-9-]+)`\s*\|\s*`(#[0-9A-Fa-f]{6})`"

So spacing, radius and type have been silently unprotected all along, and the motion tokens added by prompt 01 inherit the same hole. A --duration-fast: 120ms is invisible to every parser: CI passes while the stacks drift apart.

Worse, scripts/palette_map.py:159 claims structural values are "checked by the scale check" — no such script exists anywhere in ~/src/utils. That comment describes a check that was never written. This prompt writes it.

where

Repo: ~/src/utils.

Create ~/src/utils/unified-design-system/scripts/structural_check.py.

Edit ~/src/utils/.github/workflows/palette-drift.yml — add a step invoking it. The workflow deliberately has no paths: filter; keep it that way.

Fix the stale comment at ~/src/utils/unified-design-system/scripts/palette_map.py (~:159) to name the real script.

Sources to compare (three code stacks + the prose freeze):

Role	Path
prose freeze	~/src/utils/unified-design-system/tokens.md (spacing/radius/type)
motion freeze	~/src/utils/unified-design-system/motion.md (created by prompt 01 — run it first)
web/React	~/src/utils/web_ui/src/tokens.css
Flutter/Dart	~/src/utils/design_system/lib/src/tokens.dart
Python/Tkinter	~/src/utils/gatelock/gatelock/_window.py (class LockConfig)

must

• Cover motion (durations, easing) and the already-unprotected spacing, radius and type scales, in one checker.

• Mirror palette_check.py's two-halves design, because it is the part that actually works:

  1. Agreement — for each mapped token, resolve it in every non-n/a stack and fail if values disagree.
  2. Completeness, bidirectional — every structural value parsed out of any source must be mapped, or explicitly exempted. This is what catches "added it to one stack, forgot the others".

• Support an explicit n/a per stack, and require a reason string. Tkinter has no animation framework; a duration legitimately does not exist there. An honest n/a with a reason is correct — a fabricated constant is not.

• Adjudicate with exit codes. Exit non-zero on drift with a message naming the token and the disagreeing files. No warnings-only mode.

• Keep every file ≤ 250 lines (~/src/utils/file_length/config.py). Note palette_check.py is 231 and palette_map.py is 162 — that pair was split precisely to stay under the cap. Split yours the same way from the start (structural_check.py + structural_map.py) rather than discovering the problem at 251 lines.

• Ruff-clean under the repo's config. No # noqa, no type: ignore.

• Expect it to fail on first run. Spacing/radius/type have never been compared; there may be real pre-existing drift. That is the point of writing it. Fix whatever it surfaces, in the stack copy that is wrong, and say in the session summary what drifted.

• must not: weaken the checker, add an exemption, or narrow its scope to make it green. If a token genuinely differs per stack for a good reason, encode it as an n/a/variant with the reason recorded, not as a silent skip.

• must not: modify palette_check.py. It works; it is simply colour-only. The two scripts run side by side.

• must not: change any token value to resolve a disagreement without saying so explicitly — that is a design change, and tokens.md is a freeze. Surface it and let kuhy decide which value is canonical.

• optional: teach it the shadow tier too, if that falls out cheaply.

done

1. python3 ~/src/utils/unified-design-system/scripts/structural_check.py exits 0, and exits non-zero when you deliberately break one stack copy (test both directions — a checker that never fails is not a checker).
2. It is wired into ~/src/utils/.github/workflows/palette-drift.yml and the workflow passes.
3. palette_map.py's "scale check" comment names the real script.
4. ~/src/utils/scripts/check_file_length.sh --all reports no new violations.
5. The session summary states what drift, if any, the first run found.

verify

Desktop. Run the script, paste the output. Then prove it fails: change one spacing or duration value in one stack copy, re-run, paste the non-zero exit and the message, and revert. Both halves of that demonstration are required — the passing run alone proves nothing.

read first

• ~/src/utils/unified-design-system/scripts/palette_check.py — the design to mirror. Read NON_COLOUR_CSS: it is the regex that currently excludes spacing/radius/type/shadow from the colour check, and therefore the precise list of what you are now covering.
• ~/src/utils/unified-design-system/scripts/palette_map.py — the PALETTE tuple of Token(canonical, md, css, dart, tk, why) rows. Your map wants the same shape, including the why field.
• ~/src/utils/.github/workflows/palette-drift.yml — how palette_check.py and ramp_check.py are invoked; add your step alongside.
• ~/src/utils/unified-design-system/motion.md — what prompt 01 created.
• ~/src/utils/unified-design-system/tokens.md — the spacing/radius/type tables. Do not edit it; it is 260 lines and already over the cap.

context you would otherwise rediscover

• The four "stack copies" are really three code stacks plus a prose freeze. There is no fourth code stack; do not hunt for one.
• ~/src/dufs-cloud/app/lib/ui/theme.dart is a fifth, uncompared copy of the palette (the Flutter app has no design_system dependency and hand-restates every hex). It is out of scope here — prompt 07 wires it up properly. Do not add it as a source to this checker; wait until 07 has removed it.
• Three Flutter apps (diet-guard, workout_app, wake_alarm) similarly hand-transcribe tokens into local lib/ui/theme.dart files. Those are deliberately outside the checker's scope for now — bringing them in is a much larger job than this prompt.
• ~/src/utils/gatelock/ is a package inside this monorepo, not a separate repo.

REMOVE ME AFTER FINISH