The Brew
In one project, the same gray was used as:
gray-100
bg-light
surface-low-contrast
All of them mapped to nearly identical hex codes — but they weren’t treated the same. Each one lived in a different file, named by a different person, with a slightly different purpose.
Result? Developers applied them inconsistently. Components rendered differently. QA flagged visual issues that weren’t visual — they were systemic.
That’s token drift — when naming diverges from meaning, and consistency gets lost in translation.
Here’s how to fix it:
Create a naming convention — with categories like color role (bg, text, border) and state (hover, active, subtle).
Align naming with usage intent — don’t name it gray-light if it’s used for error background. Try levels - Global, Semantic, Component from the complexity of the design system.
Clean up quarterly — run token audits regularly and prune what’s duplicated, unclear, or legacy.
Pro Tip:
Tokens are a language. Don’t let dialects emerge. Use Figma’s variable modes to organize tokens by theme or purpose (e.g., brand, UI, accessibility). This helps catch overlaps early.
Sip Thoughtfully
Tokens should reduce confusion. If they multiply it, they’ve lost the plot. Drift isn’t just about naming — it’s about system health.
Your Turn: Pick one token from your design system. Does its name match its purpose — not just in theory, but in practice? If not, rename or retire it. One clean token saves hours of confusion down the line.
Connect on LinkedIn
Book a vibe check via Topmate
Tour my universe on Bento
All links are one tap away.
