Why your design system has 4000 tokens and nobody uses 200 of them

If your design system has 4000 tokens and you cannot find the one you need in under 15 seconds, you do not have a design system. You have a token landfill.

How it happens

Token bloat is rarely a single decision. It is the accumulation of small “let me just add a token for this” requests, each individually reasonable, that compound into a system that nobody trusts. Three things drive it:

• No naming convention. color-blue-500 and color-primary-500 and color-brand-blue all exist, refer to the same value, and were added in different quarters.
• No rejection rule. Token requests get approved if they look reasonable in isolation. There is no “what does this break if it changes?” gate.
• No audit cadence. Tokens accrete; they are never pruned.

The audit

I ran this audit on a real system that had grown to 4047 tokens:

1. Usage frequency. Pull every token reference across the codebase. Tokens with zero references: delete. Tokens with one reference: question.
2. Duplicate values. Two tokens pointing at the same hex are either redundant or wrong. Both need a conversation.
3. Semantic vs primitive. Every primitive token (blue-500) needs a semantic wrapper (color-action-default). Components consume semantic only.
4. Aliasing. Multiple semantic tokens can alias to the same primitive. That is fine. Multiple primitives for the same value is the bug.

The cleanup

From 4047 tokens to 280, in 9 weeks, without breaking the product:

• Wrote codemods that rewrote 1700 unused tokens out of the codebase.
• Established a “deprecated” tier — old tokens still resolve but warn in dev tools, giving teams a window to migrate.
• Set a hard rule: new tokens require a written justification and a sign-off. Most requests turn out to be “I want a shade I can already achieve via existing semantics.”

The conversation

The hardest part was not technical. It was telling teams “no” to token requests without sounding like a gatekeeper. The reframe that worked: “Your token request is reasonable. The system already supports this. Here is how. If that pattern is broken, let us fix the pattern, not add a token.”