Design Systems · Step 2 · 6 min read
Naming tokens
A token name is a tiny piece of documentation people read hundreds of times a day. How to build names from general to specific, name primitives by what they are and semantics by what they're for, pick a scale people can extend, and keep one name across Figma, JSON, CSS and native code.
The name is the interface of a token. Nobody reads a token's value; they read its name, in a Figma picker, in autocomplete, in a code review. A good name tells you when to use it without opening the docs. A bad one gets used wherever its colour happens to look right, and then the system means nothing. Naming is the cheapest place to get a design system right, and the most expensive place to fix later.
What you'll be able to do after reading:
- Build a token name from general to specific, in a fixed order
- Name primitives by what they are and semantic tokens by what they're for
- Choose a scale that can grow without renaming
- Keep one name across design tools and platforms
1. A name is a sentence
colorcategory: what kind of valuefeedbackconcept: the jobdangervariant: which one
buttoncomponentprimaryvariantpadding-inlineproperty
| System | A real token name | The order of its parts |
|---|---|---|
| Harbour | color. | category, concept, variant |
| Atlassian | color. | foundation, property, modifier |
| Adobe Spectrum | negative-content-color-default | concept, property, category, state |
| IBM Carbon | $text-primary | property, emphasis; the theme sets the value |
| Material Web | --md-sys-color-primary | namespace, tier, category, role |
Read color.feedback.danger left to right: it's a colour, for feedback, the danger kind. Each part narrows the one before. That's the main rule: from general to specific, always in the same order.
Atlassian describes its names the same way, in three parts: a foundation ("such as color, elevation, or space"), a property ("the UI element the token is being applied to, such as a border, background, shadow"), and an optional modifier ("its color role, emphasis, or interaction state"). It also notes that "not every token has a modifier. For example, color.text is our default body text color" (Atlassian, Design tokens).
The figure shows that big systems choose different orders. Spectrum puts the concept first (negative-content-color-default); Atlassian and Harbour put the category first. Either works. Mixing orders inside one system is what doesn't.
2. Primitives: what they are
Primitive names describe the value, neutrally, so they never become wrong:
- Colour: hue and step.
color.blue.600,color.sand.50,color.coral.600. Higher numbers are darker. The gaps (50, 100 … 900) leave room to add a step later without renaming. - Space: a numbered scale. Harbour uses
space.1tospace.8for 4 to 64 px. - Radius, font size: small named or numbered sets.
radius.sm,radius.md;font.size.300.
Never put a purpose in a primitive name (color.brand-blue): the day the brand changes, the name lies. And never put a value in it (space.16px): the day you change the value, it lies the other way.
3. Semantics: what they're for
Semantic names describe purpose, never appearance:
| Instead of | Use | Why |
|---|---|---|
color.blue-button |
color.action.primary |
In dark mode it isn't the same blue |
color.red-text |
color.feedback.danger |
A rebrand might make danger coral or orange |
color.light-grey-bg |
color.surface.subtle |
"Light" is wrong in dark mode |
space.16 |
space.inset.md |
The value can change with density |
GOV.UK makes the same point for its colours: use govuk-functional-colour("brand") "rather than #1d70b8", and "only use the variables in the context they're designed for" (GOV.UK Design System, Colour). A purpose name used for the wrong purpose is still drift, just better disguised.
Useful parts for semantic names, in Harbour's order:
- Category:
color,space,radius,font - Concept:
action,text,surface,border,feedback,inset,stack - Variant:
primary,subtle,danger,success, or a size:sm,md,lg - State, last and only when needed:
hover,pressed,disabled
So: color.action.primary.hover, color.text.subtle, color.border.focus, space.stack.lg.
4. Scales that can grow
Two kinds of scale names are common, and both work if you choose once:
- Numbers (
space.1 … space.8,font.size.100 … 600): easy to extend at the top, hard to squeeze a step in between unless you leave gaps (100, 200, 300). - T-shirt sizes (
sm,md,lg,xl): easy to read, and fine for semantic tokens with few steps (space.inset.sm/md/lg). Awkward pastxxxl.
Harbour uses numbers for primitives and t-shirt sizes for semantics, so space.inset.md → space.4 reads naturally.
5. One name, many syntaxes
A token is written differently in each place, but it should be the same name:
| Where | Harbour's color.action.primary |
|---|---|
| Token file (DTCG JSON) | groups color › action › primary; referenced as {color.action.primary} |
| Figma variable | primary inside the groups color › action, in a Semantic collection |
| CSS | --hb-color-action-primary |
| Swift or Kotlin | colorActionPrimary |
The DTCG format doesn't allow ., { or } inside a single name, because the dot is how groups and references are written (DTCG, Format Module 2025.10). So the dots in color.action.primary are a path through groups, not part of one long name. The hb- prefix in CSS is a namespace: it keeps Harbour's properties from clashing with anyone else's on the page.
Figma lets you set a code name per platform for each variable, which Dev Mode then shows in its code snippets; there's room for up to three, for Web, Android and iOS (Figma Help, Create and manage variables). Fill them in, so designers and developers see the same token.
6. Common mistakes
- Appearance in semantic names:
blue,light,big. - Purpose in primitive names:
brand-blue,error-red. - Two orders in one system:
color.text.subtlenext tosubtle.border.color. - Synonyms:
danger,errorandcriticalfor the same thing. - Renaming tokens often. Every rename is a breaking change for someone (see Deprecation and breaking changes).
7. Vocabulary
| Term | Meaning |
|---|---|
| Category | The kind of value: colour, space, radius, font |
| Concept | The job a semantic token does: action, text, surface, feedback |
| Variant | Which one of the concept: primary, subtle, danger, md |
| State | An interaction condition: hover, pressed, disabled |
| Namespace | A prefix that marks a system's names, like hb- |
| Path | The groups a token sits in, written with dots |
8. Try it (no tools needed)
- Write five colour names you've seen in a real file or codebase.
- Mark each: does it describe the value, the purpose, or both?
- Rename the ones that mix the two, using category, concept, variant, state.
Reflection questions: Which of your new names would still be right after a rebrand? After dark mode?
9. If you already practise
- Write your naming grammar down as a one-line pattern, like
category.concept.variant.state, with the allowed words for each part. New tokens get checked against it. - Keep a list of banned synonyms. "Error is not a variant; use danger."
- Before renaming, add the new name as an alias of the old one and deprecate the old name over a release, so nobody breaks overnight.
Checklist
Learn more
- Atlassian: Design tokens
- Adobe Spectrum: Design tokens
- GOV.UK Design System: Colour
- Design Tokens Community Group: Format Module 2025.10, names and groups
- Figma Help: Create and manage variables, code syntax
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 · on naming as shared language (Amazon)
- Expressive Design SystemsYesenia Perez-CruzBook · A Book Apart, 2019 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Token tiers · Colour, type and spacing as tokens · Tokens from Figma to code · Deprecation and breaking changes · Motion tokens · Token naming formula