Token mapping

A read-only report that lands raw values (hex, px, shadows) on a token list someone else owns. Classes, normalising and tolerances are in references/mapping-rules.md. "Check the tokens on the settings page" is enough of an ask. Find the values and the list yourself.

Steps

1. Find the list. Token files, theme entries, custom properties on :root, a component library's variable pairs. A framework's default theme is not the team's list, and neither is a public system's (Geist's names never stand in for the team's). Record its name, location and how you read it. If a read fails, say so and stop. Never fill a list from memory.
2. Find the values. What the person named, else the branch diff, else the product code. Record each with its file, line, property and job.
3. Resolve. Follow every alias to its final value in each mode. Write down every disagreement between two sources.
4. Normalise both sides (lengths to px, colours to OKLCH compared by delta E OK) with code, never by eye.
5. Classify each row once per mode. Purpose first, then value.
   • Exact: the token's stated job covers the row and the values match.
   • Semantic: the job covers it and the value is inside tolerance. State the difference in numbers.
   • Ambiguous: two or more tokens fit and nothing picks one. Name every candidate.
   • Gap: no token's job covers it, or the only fitting token is out of tolerance. A gap never gets a new name.
6. Count and close. When gaps are over 30% of rows and number 12 or more, the list is usually the wrong one. Say so, still deliver the table, and lead with Status: not actionable (gap threshold).

Report