token-conformance-review

What It Does

Scans UI source for hard-coded design values that should resolve back to a declared token: hex literals, raw px/rem/em, unregistered color names, ad-hoc font stacks, magic shadow values. The presence of color.primary.500 in tokens.md while a component inlines #1a73e8 is a finding, not a stylistic preference.

token findings default to high severity — this is the load-bearing check for "is the design system actually being followed."

Use This When

Use this for every design-test run. It is one of the two primary "is the contract followed" skills, alongside component-conformance-review.

Inputs

• Read docs/instructions/design-system/tokens.md to know what's declared.
• Read the contract-summary from design-system-coverage (lists every declared token name).
• Read references/token-leak-checklist.md before scanning.
• Read tailwind.config.* if present — Tailwind theme entries count as tokens too.

Procedure

The mechanics are deterministic — drive them with the scripts in scripts/ rather than re-deriving them on every finding. Reserve LLM reasoning for the "is this leak resolvable to which token" judgment, not for parsing files.

1. Run scripts/parse-tokens.sh <tokens.md> once and persist the TSV (<name>\t<value>\t<namespace>). This is the declared truth.
2. Run scripts/scan-tokens.sh to grep the source roots for hard-coded value patterns. Each hit is an investigation candidate.
3. For each leak hit, run scripts/match-leak-to-token.sh --leak <value> --tokens <parsed.tsv> [--namespace <ns>]. It uses scripts/normalize-color.sh internally so #1A73E8, #1a73e8, and rgb(26,115,232) all resolve to the same canonical form. The output is one of:
   • match\t<token-name> → emit a token finding, high severity. Required action: writes itself: replace <leak> at <file>:<line> with <token-name> from tokens.md.
   • ambiguous\t<n1>,<n2>... → still a finding; pick the more specific token (most dotted segments) and explain the alternatives in the finding body.
   • no-match → emit a parallel documentation-drift finding pointing at the gap in the contract; the token leak finding becomes medium until the gap is filled.
4. If the hit lands inside a known exemption path (**/*.test.*, **/*.stories.*, **/__tests__/**, src/design-tokens/**, tailwind.config.*) the scanner already drops it — never re-check those manually.