Framework · Design systems · 3 min read
Token naming formula
A fixed order for building token names from general to specific (category, concept, variant, state), with a list of allowed words for each part, so every name tells people when to use it and new names stay consistent.
The kind of value. Always first.
color, space, radiusThe job the token does. Purpose, never appearance.
action, text, surfaceWhich one of the concept, or a size.
primary, danger, mdAn interaction condition. Last, and only when needed.
hover, pressed, disabledcolor . action . primary . hover → --hb-color-action-primary-hover
Use it when
- You are naming the first semantic tokens of a system.
- The token list has synonyms (
danger,error,critical) or mixed orders (color.text.subtlenext tosubtle.border.color). - Designers and developers see different names for the same token in Figma and in code.
How to use it
- Choose the parts and their order. Most systems go from general to specific: category, concept, variant, state. Write it as one line, for example
category.concept.variant.state. Output: the naming pattern. - List the allowed words for each part. Categories (
color,space,radius,font), concepts (action,text,surface,border,feedback), variants (primary,subtle,danger,sm,md), states (hover,pressed,disabled). Output: a vocabulary table, one column per part. - Ban the synonyms. For each concept, pick one word and write down the ones you won't use. "Error is not a variant; use danger." Output: a short list of banned words with their replacement.
- Name primitives and semantics differently. Primitives describe the value (
color.blue.600,space.4). Semantics describe the purpose (color.action.primary). Never put a purpose in a primitive name or a value in a semantic name. Output: two clear sets of names. - Map the name to every platform. The dots are a path through groups in the token file. Write how the same name looks in Figma, CSS (with a namespace prefix) and native code. Output: one row per platform for each token.
- Check new tokens against the pattern. In review, read the name left to right. Every part should come from the vocabulary, in order, and the state comes last and only when needed. Output: a yes or no per new token, before it ships.
Worked example
Harbour, the design system of the ferry company Tidewater, writes its pattern as category.concept.variant.state, with the CSS namespace hb-.
| Part | Allowed words (excerpt) | Example |
|---|---|---|
| Category | color, space, radius, font | color |
| Concept | action, text, surface, border, feedback, inset, stack | action |
| Variant | primary, subtle, danger, success, sm, md, lg | primary |
| State (optional) | hover, pressed, disabled, focus | hover |
So the hover colour of the main action is color.action.primary.hover. In CSS it's --hb-color-action-primary-hover, in Swift or Kotlin colorActionPrimaryHover. A team asks for color.red-error. The review rejects it twice: "red" is appearance, and "error" is a banned synonym. It ships as color.feedback.danger.
Watch out for
- Appearance in semantic names.
blue,lightandbigbecome wrong in dark mode or after a rebrand. - Two orders in one system. Autocomplete stops helping, and people create duplicates because they can't find the token they need.
- Renaming often. Every rename is a breaking change for someone. Add the new name as an alias first, then deprecate the old one.
- A pattern only in people's heads. If the grammar isn't written down, each new contributor invents their own.
Template
Copy this into the system's docs and fill the vocabulary before naming the next token.
Pattern: category.concept.variant.state (state only when needed)
Namespace: css prefix "...-"
Category: color | space | radius | font | ...
Concept: action | text | surface | border | feedback | ...
Variant: primary | subtle | danger | sm | md | lg | ...
State: hover | pressed | disabled | focus
Banned: error -> danger · critical -> danger · bg -> surface
New token: ....................................
Parts in order, all from the lists? yes / no
No appearance words (blue, light, big)? yes / no
Figma: ... CSS: --...-... iOS/Android: ...
- Design SystemsAlla KholmatovaBook · 2017 (Amazon)
- Expressive Design SystemsYesenia Perez-CruzBook · 2019 (Amazon)
- Naming Tokens in Design SystemsNathan Curtis, EightShapes (external site)
- Design Tokens Format Module 2025.10DTCG (external site)
- Create and manage variablesFigma Help (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.