You defined the tokens. You documented them. You probably even built a Storybook page showing the full palette with variable names.
And then six months passed.
Now your codebase has color: #1A1A1A in fourteen places, a spacing value of 12px scattered across components, and three tokens that haven't been referenced in any CSS file since the last rebrand.
Nobody did this on purpose. It just happened — and that's exactly what makes it hard to catch.
The silent drift problem
Design tokens are a bridge that connects design decisions and code. Instead of hardcoding values, you reference a named token. Colors, spacing, typography, radius, everything flows from a single source of truth.
In practice, here's how it usually goes:
A deadline hits. Someone needs to ship a component fast.
A token gets renamed. The design team updates the naming convention from color-primary to brand-blue-600. The JSON gets updated. The documentation gets updated. Some CSS files get updated. Not all of them.
A new developer joins. They're onboarding fast, looking at existing code for patterns. They find a hardcoded value used in three components and assume that's the convention. They follow it.
A rebrand happens. The token values change. But the hardcoded values don't, because nobody knows they exist.
None of these are catastrophic events. They're small, reasonable decisions made under normal constraints. The problem is that they compound invisibly — until you're maintaining a design system that's theoretically rigorous but practically inconsistent.
The drift is invisible for a simple reason: it doesn't break anything.
You only notice the problem when:
- A token value changes, but the hardcoded version doesn't update with it
- You try to do a systematic audit and realize you have no way to know where direct values are hiding
- You onboard a new designer who asks "so what's the real source of truth here?" and you don't have a clean answer
At that point, the audit is manual and painful. You're grepping through CSS, cross-referencing token files, and building a picture of coverage in a spreadsheet.
What a token coverage audit actually needs to surface
When I ran into this problem on a project, I wrote down what I actually wanted to know:
- Which tokens are defined but never used in CSS?
- Where are hardcoded values hiding?
- What's the coverage by category?
- Which components are the worst offenders?
This felt like a well-defined problem.
So I built a tool to solve it: TokenLens
How TokenLens works
TokenLens is a browser-based auditing tool. You give it two things:
- Your design token definitions in JSON
- Your CSS files
Here's the flow in more detail.
Step 1: Upload your files
TokenLens accepts multiple files at once — useful if your tokens are split across multiple JSON files, or your CSS is organized by component. There's no account, no install, no build step.
Step 2: Get the report
The output covers:
- Token coverage for each token category, what percentage of relevant CSS properties reference a token vs. a hardcoded value
- Unused tokens, defined in JSON that don't appear in any CSS file
- Hardcoded value instances, specific lines where direct values are used instead of tokens, grouped by property type
- Component breakdown, which CSS selectors (inferred from class names) have the worst coverage
An example
Let's say you have a token file with 40 color tokens and a set of component CSS files.
After running the audit, you might find:
- 28 of your 40 color tokens are actually referenced in CSS
- 12 tokensexist in the definition but aren't used anywhere
- 23 instances of hardcoded hex values across 8 component files
That's a picture you can act on.
You know where to focus, what to clean up first, and what questions to ask the design team.
What I learned building this
Designers use this tool as much as developers. Not because they're reading the JSON, but because the report gives a shared vocabulary for a conversation that's usually fuzzy — "our design system isn't being followed" becomes "here are 23 specific places where it isn't, grouped by component."
Try it
If you maintain a design system, or you're inheriting one, I'd genuinely recommend running an audit on your current codebase. The results are usually more actionable than you'd expect.
Let me know what you think in the comments!
Top comments (0)