Why your design tokens and your CSS are probably out of sync (and how to check)

Source: Dev.to

The Problem: Tokens and CSS Get Out of Sync

You defined the tokens, documented them, and maybe even built a Storybook page showing the full palette with variable names. Six months later, your codebase contains hard‑coded values like color: #1A1A1A in many places, spacing values of 12px scattered across components, and tokens that haven’t been referenced since the last rebrand.

These mismatches aren’t intentional; they accumulate silently:

• Deadline pressure – a component is shipped quickly, and only some CSS files get updated after a token rename.
• Onboarding – a new developer sees a hard‑coded value used in a few components and assumes it’s the convention.
• Rebrand – token values change, but the hard‑coded values remain because nobody knows they exist.

The drift is invisible because it doesn’t break anything, but it becomes a maintenance nightmare when you need to audit the system.

Signs That Drift Is Happening

• A token value changes, but the hard‑coded version stays the same.
• You have no way to locate direct values hidden in CSS.
• New designers ask, “What’s the real source of truth?” and you can’t answer cleanly.

At that point, the audit is manual and painful: grepping through CSS, cross‑referencing token files, and building a spreadsheet of coverage.

What You Need to Know

When tackling the issue, ask yourself:

• Which tokens are defined but never used in CSS?
• Where are hard‑coded values hiding?
• What is the coverage by category (colors, spacing, typography, etc.)?
• Which components have the worst token coverage?

Introducing TokenLens

TokenLens is a browser‑based auditing tool that takes:

1. Your design token definitions in JSON.
2. Your CSS files.

How It Works

• Accepts multiple JSON and CSS files (useful for split token sets or component‑based CSS).

• No account, installation, or build step required.

• Generates a report with:

  • Token coverage per category (percentage of CSS properties that reference a token vs. a hard‑coded value).
  • Unused tokens – defined in JSON but not found in any CSS file.
  • Hard‑coded value instances – specific lines where direct values are used, grouped by property type.
  • Component breakdown – CSS selectors (inferred from class names) with the lowest coverage.

Example Output

Assume a token file with 40 color tokens and several component CSS files. After running TokenLens you might see:

• 28 of 40 color tokens are referenced in CSS.
• 12 tokens exist in the definition but aren’t used anywhere.
• 23 hard‑coded hex values across 8 component files.

This gives you a clear picture of where to focus cleanup efforts and which questions to ask the design team.

Why It Matters

Designers and developers can both use the report as a shared vocabulary. Instead of a vague “our design system isn’t being followed,” you can point to concrete instances: “here are 23 specific places where hard‑coded values are used, grouped by component.”

Recommendation

If you maintain or inherit a design system, run an audit with TokenLens. The results are usually more actionable than expected.

Try it here: https://tokenlens.app

Let me know what you think in the comments!