Design token naming: the three-tier system, and where it breaks

The convention is close to universal, which makes it easy to adopt the shape without the reasoning. Each tier answers a different question, and knowing which question keeps you from putting things in the wrong place.

The rule that makes this work, and the one most often broken: nothing outside the semantic tier may reference a primitive. The moment a component uses blue-600 directly, the primitive tier has become a public API and you can no longer change a value without auditing the whole codebase — which was the entire reason for having tiers.

:root {
  /* Tier 1: primitives. Values only. Nobody uses these directly. */
  --blue-600: #2563eb;
  --red-600:  #dc2626;
  --gray-500: #6b7280;

  /* Tier 2: semantic. Roles. This is the public API. */
  --color-primary:   var(--blue-600);
  --color-danger:    var(--red-600);
  --text-muted:      var(--gray-500);

  /* Tier 3: component. Only where a component truly deviates. */
  --button-danger-bg: var(--color-danger);
}

/* ✅ product code */
.alert { color: var(--color-danger); }

/* ❌ reaches past the semantic layer */
.alert { color: var(--red-600); }

Read left to right, general to specific: category, role, variant, state. Not every token needs all four, and the ones that do are usually interactive.

Consistency matters far more than which pattern you pick. A codebase where half the tokens read text-color-muted and half read color-text-muted costs everyone a lookup every time, forever. Pick one order, write it down, and enforce it in review.

Here is the pattern applied, rather than described. Read the role names, not the colours — the question each one answers is "what is this for", and a name that only answers "what colour is it" has failed the tier it sits in.

One question resolves most naming arguments in seconds:

Run it against real cases and the answers are unambiguous:

The --shadow-card case is the subtle one, and worth dwelling on. Naming a token after its implementation locks the implementation in. Once every card in the codebase says box-shadow: var(--shadow-card), moving to border-based elevation is a refactor rather than a token change — which is exactly the coupling tokens were supposed to remove.

Most token systems that fail, fail here. The component tier starts small and legitimate, then absorbs everything, and eventually you have four hundred tokens, half of which have one consumer.

The mechanism is always the same. Someone needs a button background that is not quite --color-primary. Adding --button-primary-bg takes thirty seconds and adding it to the semantic tier requires a conversation. So the component token goes in, and the next person does the same, and the semantic tier stops being the source of truth without anyone deciding that.

A useful audit: count component-tier tokens with exactly one consumer. If that number is large, the tier is being used as an escape hatch, and the fix is upstream.

These recur across almost every token system that stops being used. Each has a cheap fix if caught early and an expensive one if not.

1. 1

   Numbered scales with no anchor

   color-1 through color-12 tells nobody anything, and the numbers acquire meaning only through folklore. Numbered scales are fine in the primitive tier, where the number tracks a real dimension like lightness. They are never acceptable in the semantic tier, because the whole point of that tier is to say what something is for.

2. 2

   Encoding the theme in the name

   --light-bg and --dark-bg as separate tokens means every component references both and branches. One name, two values, switched by theme — that is what the token layer is for. If you find if (theme === 'dark') in component code, the tokens are named wrong.

   Copy

   /* ❌ */  --light-bg: #fff;  --dark-bg: #0a0a0a;
   /* ✅ */  --surface-base: #fff;
            [data-theme="dark"] { --surface-base: #0a0a0a; }

3. 3

   Sizes named after where they are used today

   --text-hero is fine until the hero size shows up in a pricing table. --text-4xl or --font-scale-7 names the step, not the site, and survives being reused. Name by position in a scale, not by first customer.

4. 4

   Status colours doubling as brand colours

   The most common way a system becomes unable to show state. If the brand green and the success green are the same token, you cannot restyle the brand without changing what success looks like, and you cannot tell a healthy row from a branded one. Keep the status set reserved and say so in a comment.

5. 5

   Abbreviations that only one person expands

   --clr-bg-scndry saves eleven characters and costs every reader a decoding step forever, including a model that has to guess whether scndry is secondary or a typo. Autocomplete makes length nearly free. Write the words.

Tokens increasingly have to travel: from a design tool to CSS, into a Tailwind theme, into a native platform, into a shadcn registry item, into a DESIGN.md an agent reads. That puts a constraint on names most teams do not think about until the first export breaks.

The practical rule: pick names that are simultaneously a valid CSS custom property, a valid JSON key and a readable English phrase. Flat, lowercase, hyphenated satisfies all three, and the DTCG/W3C token format's nested groups can be generated from a flat set far more easily than the reverse.

The highest-leverage naming decision is not the pattern. It is whether the names in your design tool are identical to the names in code.

Salesforce's SLDS 2 is the clearest published example: its Figma library uses the same semantic hook names as the CSS — their own examples are radius-border-4 and font-scale-4 — so designs map one-to-one to live code. Their stated goal is a shared vocabulary bridging design and development.

The practical effect is that a whole class of handoff bug stops existing. When a designer says font-scale-4 and a developer types font-scale-4, there is no translation step and therefore nowhere for meaning to leak. Compare that with a Figma style called "Heading / Large" mapping to a CSS variable called --text-2xl, where every handoff is a lookup and every lookup is a chance to guess wrong.

Token naming used to be a human ergonomics question — autocomplete, readability, onboarding. Increasingly the heaviest reader of your token file is a coding agent, and that changes which failures matter.

A human who cannot tell which of two greys to use will ask, or pick one and be told in review. A model will pick one, silently, in every file it touches, and the inconsistency arrives faster than review can catch it. Ambiguity in the semantic tier is a much more expensive defect than it used to be.

We sampled 299 DESIGN.md files published for agents to read and found that 86% specify colours as raw hex values with no semantic role attached at all. Not badly-named tokens — no tokens. A model given #6b7280 and told it is part of the palette will use it wherever a mid-grey is plausible: body text, borders, icons, placeholders, disabled states. Five different jobs, one value, no way to change any of them independently later.

The second version costs three extra lines and buys the ability to darken your borders without darkening your captions — which is a change you will want, and which the first version makes impossible without a codebase-wide audit.

If you are naming a system from scratch, this is a defensible minimum. It is small on purpose — a system nobody can hold in their head gets ignored.

/* Surfaces — what things sit on */
--surface-base        /* the page */
--surface-raised      /* cards, panels */
--surface-overlay     /* modals, popovers */
--surface-sunken      /* wells, inset areas */

/* Text — by emphasis, never by colour */
--text-primary
--text-secondary
--text-muted
--text-disabled
--text-on-accent      /* text sitting on the accent colour */

/* Borders — by weight of presence */
--border-subtle
--border-strong
--border-focus

/* Action — the interactive colour and its states */
--action-primary
--action-primary-hover
--action-primary-active

/* Status — reserved. Nothing decorative uses these. */
--status-success
--status-warning
--status-danger
--status-info

Two notes on that set. Text tokens are named by emphasis rather than colour, so they stay true in dark mode. Status tokens carry a comment reserving them, because the most common way a status system breaks is a designer using the success green as a decorative accent and then nobody being able to tell a healthy row from a branded one.