feat(gate): measure the design-first claim, and stop pointing Copilot at Claude paths

[anilcancakir]

What changed

bin/design-tokens (new) scans lib/**/*.dart for raw Color(0x and Colors.* and exits non-zero with the offending file:line. It runs as a bin/check job (static, so in --fast too) and as a new, non-blocking Design tokens CI job. Separately, bin/sync-instructions now rewrites Claude-only references while staging a rule body.

Why

Mirrored from the uptizm fork, per the mirroring rule in AGENTS.md: a structural change there travels here in the same piece of work. This repository is the boilerplate, so tooling that catches a class of mistake belongs here before it belongs in any fork.

Nothing measured the design-first claim. design:lint validates DESIGN.md's own YAML and never reads the Dart that is supposed to obey it; flutter analyze has no opinion about a hardcoded colour. A component could ignore every semantic token and the gate would stay green.

Upstream: anilcancakir/uptizm#5 (the gate) and anilcancakir/uptizm#7 (the generator rewrite).

Evidence

$ ./bin/check                        $ ./bin/check --fast
  ok  flutter-analyze                  ok  flutter-analyze
  ok  design-tokens                    ok  design-tokens
  ok  backend-pint                     ok  backend-pint
  ok  flutter-test                   check: all green | static only, no tests ran
  ok  backend-test
check: all green | flutter backend

The gate was proven able to fail, then reverted:

$ printf '\nconst Color _qaProbe = Color(0xFF123456);\n' >> lib/ui/components/callout/callout.dart
$ ./bin/design-tokens
design-tokens: raw color literal(s) found outside the allowlist:
  lib/ui/components/callout/callout.dart:64
exit=1

The generator rewrite, before and after, with the source rule untouched:

line	before	after
design.instructions.md:9	`CLAUDE.md`	`.github/copilot-instructions.md`
design.instructions.md:95	(`.claude/agents/component-visual-reviewer.md`)	(a Claude Code agent definition; Copilot has no equivalent, so apply those criteria by hand)
design.instructions.md:5	GENERATED from .claude/rules/design.md	unchanged, deliberately

git diff .claude/rules/design.md is empty, and bin/sync-instructions --check is clean and stable across repeated runs, so the substitutions are deterministic and CI cannot flap.

• bin/check green
• Exercised for real (the checker run against the tree and against a planted violation; the generator run and re-run)

Two details that were paid for downstream, not guessed at here

Comments are stripped before the scan. A component's own docstring routinely says "no raw hex, Color(0xFF...), or Colors.* anywhere", so a naive grep flags the sentence claiming compliance. Three components in the fork did exactly that, and the job was red on arrival until the stripper existed.

Colors. needs a left word boundary. Without one it matches the tail of any identifier ending in Colors, so an ordinary kBrandColors.first reads as a violation. That single false positive put a file on the fork's allowlist that had no real violation, which is a hole rather than an exemption: it would have silently permitted the first genuine one. Color(0x deliberately has no boundary, so MaterialColor(0xFF008560 in a generated theme is still caught.

The allowlist has one entry, and that is the point

lib/config/wind_theme.g.dart, which design:sync generates. That is the measured surface of this tree. A fork therefore starts from a clean list and adds an entry only when it has a real reason to, with the reason written next to the path.

It prefers an exact file to a directory: a directory entry also exempts every file added to it later, under a reason that may not apply to them. lib/config/ was tried and rejected on exactly that ground downstream, where the directory holds fourteen files and only one is generated.

What it does not measure

Stated in the script header rather than left to be discovered. It is regex and not an AST, so Color.fromARGB, Color.fromRGBO and Color.from walk past it (zero occurrences today; the header says to add a rule the day one appears). A // inside a string literal truncates its line before the scan sees it. And a hardcoded pixel value, a colour token written without its dark: pair, and a one-off widget where a registry component already exists are all outside what a regex can see. This is a floor, not the whole of design-first.

Not required yet, on purpose

Design tokens is a new job with a new name, so it reports without blocking until someone adds it to branch protection. That is the right order for a gate that has never been green on main; bin/check is where it actually gates in the meantime.

[Copilot]

Pull request overview

Introduces an automated “design tokens” gate to enforce the repo’s design-first constraint (no raw Color(0x...) / Colors.* in lib/**), and improves generated Copilot instruction mirrors by rewriting Claude-only path references in staged rule bodies.

Changes:

• Added bin/design-tokens to scan lib/**/*.dart for raw color literals (with comment stripping + allowlist support).
• Wired the new gate into bin/check (including --fast) and added a standalone “Design tokens” CI job.
• Updated bin/sync-instructions to rewrite Claude-only references inside mirrored rule bodies (without mutating the source .claude rules).

Reviewed changes

Copilot reviewed 3 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
bin/sync-instructions	Rewrites Claude-only references while staging rule bodies so Copilot mirrors link to paths Copilot can open.
bin/design-tokens	New static scanner enforcing “token-only” color usage in lib/**, with comment stripping and an allowlist.
bin/check	Runs bin/design-tokens as part of the flutter scope (and in --fast).
.github/workflows/ci.yml	Adds a standalone “Design tokens” job to report raw color violations separately from Flutter analyze/test.
.github/instructions/design.instructions.md	Updates generated instruction text to reference Copilot-appropriate paths.
.design-token-allowlist	Introduces an allowlist (currently only lib/config/wind_theme.g.dart) with required per-entry rationale.