find-token-drift
Skill1 starsChanged 6 days agoMITView on GitHub
Use for "audit our design tokens", "how many greys do we use", "find hard-coded colours", "token drift", "which paddings are off-scale", "design system cleanup", "re-run the token audit". Inventories every colour, spacing, radius, font size, shadow and z-index in a front-end codebase (tokens, hard-coded values, theme overrides, inline styles), clusters near-duplicates by perceptual distance and scale closeness, and reports each cluster with call sites, a proposed token and whether the swap would show or break contrast. Works from source, no browser. Keeps a small catalog in the repo for re-runs. User-invoked. NOT for a lint rule in CI, a codemod that rewrites the values, visual regression testing, or auditing component duplication (use find-reinvention).
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hands-offSkill
- hill-climbSkill
- optimize-agent-instructionsSkill
- asset-gardenSkill
- clean-code-stewardSkill
- css-override-censusSkill
- debt-ledgerSkill
- find-component-reinventionSkill
- find-contract-driftSkill
- find-dead-codeSkill
- find-dead-cssSkill
- find-dependency-overlapSkill
- find-reinventionSkill
- optimize-commentsSkill
- optimize-docsSkill
- pattern-censusSkill
- test-gardenSkill
- theme-paritySkill
- type-rhythmSkill
- vocabulary-driftSkill
- ui-feature-specSkill
- oie-channel-code-reviewSkill
- oie-plugin-developmentSkill
- batch-workSkill
- deep-code-reviewSkill
- triage-cardSkill
- write-testsSkill
- postmortemSkill
- brainstormSkill
- debate-planSkill
- steelmanSkill
- unslopSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Stop and say which is missing:
- Distinctive: line 64
Write an extractor per detected syntax in the work folder, using a real parser where one exists.
- Very specific: line 72
Run verify --check occ on the source, tokens and occurrences.
- Distinctive: line 79
Write the canary file (see Check) in the work folder in the target's main token syntax, extract it with the same extractors, and run steps …
- Very specific: line 85
Run cluster with the tokens, occurrences, surfaces and scopes.
- Very specific: line 90
Read reference/JUDGE.md. The judge reads source for the top 15 clusters per category by uses, applies team decisions from the catalog …
- Very specific: line 97
Run measure with the cluster input and the plan.
- Very specific: line 103
Write the report as reference/REPORT.md lays out, the per-line change list to the work folder, and the catalog files as CATALOG.md lists …
- Very specific: line 111
Write the item 5 plan row yourself.
- Distinctive: line 133
Run the same steps in order, one syntax extractor and one judge batch at a time.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Find token drift
Count every design value the code uses, measure how far each sits from the theme, and prove which swaps are safe. A model never counts a value or computes a distance: the tool does, from source bytes, and the model only judges intent.
What it writes. In the target repo, only its catalog folder (reference/CATALOG.md). It edits no code and commits nothing. Everything temporary goes in a work folder outside the repo.
Prerequisites
Stop and say which is missing:
- You can run commands and write files.
- A runtime with arbitrary-precision integers to build the tool in.
- A parser for each style syntax in scope, or the hand-written fallback in step 3.
Source goes only to the model provider you already use.
Roles
You coordinate and hold the tool's output, never the values. Workers write extractors and read source; a cheaper model is enough for extraction, and the judge in step 6 needs the most capable model available to you. With one model, use it for everything. Start each step from the tool's output in a fresh context.
0. Build and prove the tool
Implement reference/ALGORITHM.md and reference/COLOUR.md
to satisfy reference/CONTRACT.md in the work folder. Run every fixture in
reference/fixtures/. If any fixture fails, stop and report which. Never edit a fixture to make it
pass, and never continue with a partly passing tool.
1. Scope and setup
Record the commit and read all source at it (a detached checkout in the work folder, or a snapshot when
there is no version control). Detect which syntaxes the target uses with
reference/SYNTAXES.md. Find the root font size (html { font-size: 62.5% } gives
10px) for --root-px, the surface tokens (page and card backgrounds), and the scopes (CODEOWNERS
entries, else top-level folders). If the catalog has config.jsonl, start from it and say what changed.
Exclude generated, vendored and test files by path, and list the exclusions.
2. Tokens
Extract every token definition in every mode as token records, as SYNTAXES.md describes for each
source: CSS custom properties, SCSS and LESS variables, JS theme objects, Tailwind config or @theme,
design-token JSON. A token defined as another token is a ref. Each record carries the span of its
definition.
3. Occurrences
Write an extractor per detected syntax in the work folder, using a real parser where one exists. It
emits one occ per value site, as SYNTAXES.md describes: theme-scale uses are ref, literals are
literal, and every colour or length literal in a style context is an occurrence, with category other
for properties outside the six. For a syntax with no parser, hand-write a lexer and name the syntax in the
report header as lexed.
4. Prove the inventory
Run verify --check occ on the source, tokens and occurrences. Run sweep on the same source and
verify --check coverage with the occurrences, tokens and ignore records (comments, and literals that
are not style such as href="#add"). Both must pass. Then the tripwire: run coverage again with one real
occurrence removed. It must fail; if it passes, the check is broken and the run stops.
4b. Canaries
Write the canary file (see Check) in the work folder in the target's main token syntax, extract it with the same extractors, and run steps 4, 5 and 7 on it in their own tool calls. Never mix its records into the real run's input; they appear only on the Canaries line.
5. Cluster
Run cluster with the tokens, occurrences, surfaces and scopes. When a category has fewer than 3 token
values, the report leads with a proposed scale from the largest clusters.
6. Judge
Read reference/JUDGE.md. The judge reads source for the top 15 clusters per
category by uses, applies team decisions from the catalog first, and writes one plan record per value:
SNAP to a named token, NEW token, KEEP with an intent and a cited line, or SPLIT by role. It never writes a
number. More batches run only on request, each with its cost estimate.
7. Measure
Run measure with the cluster input and the plan. Rejected plan rows go back to the judge once with the
reason; rows rejected twice are dropped from the plan and listed as blocked in the report. Only a
CONFIRMED snap becomes a default in the decision list.
8. Report and catalog
Write the report as reference/REPORT.md lays out, the per-line change list to the
work folder, and the catalog files as CATALOG.md lists them. On a re-run, run diff against the saved
values first. Then append the run record as reference/CATALOG.md "Run record" says. Hand back the
report path, its header and the decision list.
Check
The canary file defines its own canary tokens (a neutral, a surface, a spacing step, a z-index) and uses.
Write the item 5 plan row yourself. Run verify --check canaries with one expect record per item below
and the canary run's output:
- A canary token colour written in another notation:
exact. - A neutral within 20 milli of the canary neutral:
snap. - A neutral about 150 milli from every canary token:
lone. - The canary neutral at an alpha more than 8/255 below 255:
lone. - A text grey that just passes 4.5 on the canary surface, planned SNAP to a canary token within snap
distance that does not (
#767676to#7a7a7aon white):measuregivesREFUTED. - A z-index one above the canary layer token:
token_plus_n, distance 1. - A spacing value 1px off the canary step:
near; and a 1px hairline:hairline. - One occurrence per detected syntax, written in that syntax (an
sxmultiplier, a Tailwind arbitrary value, avar()): extracted with the expected kind and category. - A chart palette array with one entry equal to a canary token: the judge plans KEEP
palette.
The run fails, and the report says so above the header, when any of these happens: a fixture fails;
verify --check occ or verify --check coverage fails; the tripwire passes; any canary fails; the judge's
plan still has rejected rows after one resend and they cover more than 10% of judged uses; the run record
is missing, or disagrees with this report's commit, value or check. A run that
could not perform one of these checks has failed it.
If you cannot run work in parallel
Run the same steps in order, one syntax extractor and one judge batch at a time. The work folder is the progress record: a step is done when its tool check passes, so a stopped run resumes by re-running the checks and continuing from the first that fails. If you cannot start fresh contexts, say in the report header that the judge and the extractors shared one context.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

