Design Systems at Scale: Tokens Are an API, Not a Palette
Most design systems fail not at the component layer but at the token layer. Three tiers, one enforced rule, and the CI gate that makes a rename safe.
- Design Systems
- Architecture
A design system stops being a design system the moment a product team opens a
component file and types #1c1c1a. Not because the hex is wrong - it is
probably exactly right - but because the system just lost the ability to answer
"what happens if we change this?"
I have shipped three design systems to more than a dozen teams each. Every failure traced back to the same place, and it was never the components.
The failure is always the token layer
Component libraries are easy to get right because they are easy to review. A button either has the correct padding or it does not, and a visual diff will tell you. Tokens are harder because they encode intent, and intent is invisible in a screenshot.
Here is the shape of the problem. A team defines:
:root {
--gray-800: #1c1c1a;
--gray-900: #141413;
--gray-950: #0a0a0a;
}Six months later, half the product uses --gray-900 for card backgrounds and
the other half uses it for page backgrounds. Both are defensible. Neither is
documented. Changing --gray-900 now means auditing every usage by hand,
because the name records a value, not a decision.
The test for a token name: can you change the value without reading the call sites? If the answer is no, the name is describing the wrong thing.
Three tiers, and the rule that holds them
The architecture that has survived contact with real teams is three tiers, each with exactly one job.
| Tier | Named for | Example | Who may reference it |
|---|---|---|---|
| Primitive | What it is | --stone-900: #141413 | The semantic tier only |
| Semantic | What it means | --bg-surface: var(--stone-900) | Components, utilities |
| Component | Where it lives | --nav-h, --measure-prose | One component each |
The tiers are not the interesting part - plenty of teams draw this diagram. The interesting part is the single rule that makes it load-bearing:
A primitive may never appear in component source, and a component token may never invent a raw value.
Without enforcement that rule decays in about two sprints. With enforcement it holds for years, because every colour in the product becomes traceable to one line in the primitive tier.
Enforcing it with a lint rule
Documentation does not enforce anything. A custom ESLint rule does:
import type { Rule } from "eslint";
const RAW_COLOR = /#[0-9a-f]{3,8}\b|\brgba?\(|\bhsla?\(/i;
/**
* Rejects raw colour literals in component source. The autofix is deliberately
* absent: there is no way to guess which *semantic* token the author meant,
* and a wrong guess is worse than a failed build.
*/
export const noRawColor: Rule.RuleModule = {
meta: {
type: "problem",
docs: { description: "Use a semantic colour token, not a raw value" },
messages: {
rawColor:
"Raw colour `{{ value }}`. Reference a semantic token (--bg-*, --text-*, --accent-*) instead.",
},
schema: [],
},
create(context) {
return {
Literal(node) {
if (typeof node.value !== "string") return;
if (!RAW_COLOR.test(node.value)) return;
context.report({
node,
messageId: "rawColor",
data: { value: node.value },
});
},
};
},
};Two details matter more than the regex.
The first is that there is no autofix. A fixer would have to guess whether
#141413 meant --bg-surface or --bg-elevated, and a plausible-but-wrong
token is far more expensive than a build failure - it ships, it looks fine, and
it diverges silently.
The second is scope. The rule runs on components/** and app/**, never on the
token definition files themselves. A rule that cannot express its own exception
gets globally disabled within a week.
Renaming a token without fear
The real test of the architecture is a rename. Here is the migration that used to take a quarter and now takes an afternoon.
# 1. Add the new name as an alias. Both resolve; nothing breaks.
# --bg-raised: var(--bg-elevated);
# 2. Codemod every consumer in one pass.
npx jscodeshift -t codemods/rename-token.ts \
--token=bg-elevated --to=bg-raised \
'packages/*/src/**/*.{ts,tsx,css}'
# 3. Mark the old name deprecated and fail CI on *new* usage only.
npm run tokens:deprecate -- --token=bg-elevated --removal=v5
# 4. Delete the alias in the next major.The alias in step 1 is what makes this safe. Teams migrate on their own schedule, CI blocks regressions rather than existing code, and the system never enters a state where some consumers are broken.
What CI actually gates
Three checks, in increasing cost order:
- Token lint - no raw colours outside the token tier. Runs in seconds.
- Contrast audit - every
--text-*/--bg-*pair resolved and checked against WCAG AA. Catches the case where a primitive nudge quietly pushes body copy to 4.2:1. - Visual regression - 1,200 component permutations, sharded. The slow one, so it runs last.
-
Manual design review on every PR- removed. It did not scale past ten teams and gave false confidence.
The contrast audit earns its place. A designer lightening --stone-900 by four
percent to improve card separation is a reasonable request that can
simultaneously break body-text contrast three tiers downstream. No human
reviewer catches that; a resolved-value test catches it every time.
What I would do differently
I would not build the component library first. Both times I did, the token layer ended up reverse-engineered from components that had already made inconsistent decisions, and we spent a year paying that back.
Start with primitives and semantics. Ship them as a stylesheet with no components at all and let one product team consume it directly. The gaps show up within a week, and fixing a semantic tier with one consumer costs nothing - fixing it with forty costs a roadmap.