A practical guide to start naming Design Tokens, using the Tokens glossary as a reference rather than a rulebook.

Token naming is not standardized. One system may call a base value default, another neutral, base, or rest. The goal is not to find the one correct word. It is to create a language that tells your team what a decision means, where it belongs, and when to use it.

Start with meaning, not with the value

A token name should describe a decision, not just the value currently behind it. color.blue.500 is useful as a primitive. It does not tell a product team where to use that blue. color.background.brand does.

That distinction is the foundation of a maintainable system, values can change but meaning should remain stable.

Use a simple naming formula

There are many useful formulas for token names. This is my favourite starting point because it is easy to understand, scale, and keep consistent:

[category].[element].[role].[modifier].[state]

You can explore other naming patterns in this list of options.

Examples

color.background.brand
color.background.success.subtle
color.text.error
color.icon.info.inverted
color.border.focus

Do not add every segment by default. color.text.error is complete without a modifier or state. Likewise, omit default when it is already the understood base state.

Name the layers separately

Primitive tokens

Primitive tokens store raw values or scale options without claiming a UI purpose. Common alternative names are primitive, reference, global, base, core, foundation, and raw.

color.blue.500

Semantic tokens

Semantic tokens describe intended meaning and usage independently of the underlying value. They are also called aliases, system tokens, purpose tokens, role tokens, or decision tokens.

color.background.brand

Component tokens

Use component scope when a shared semantic token is not precise enough for a component, or when you have a multi-brand Design System or different modes where the component has a different look and feel in each mode.
Example: A component that has a border in one mode versus another that does not, where a global semantic rule cannot be established, only a component-specific one.

button.color.secondary.border.brand

Build a small glossary before a large token set

Before naming hundreds of tokens, agree on a short glossary. For each term, document:

• Concept: the main word being defined.

• Naming segment: whether it acts as category, element, role, modifier, or state.

• Definition: what it means and when it is appropriate.

• Scale: values ordered by intensity, size, hierarchy, or sequence.

• Synonyms and related concepts: alternatives that should be compared, not blindly treated as equivalents.

• Naming examples: references that show how the term appears in practice.

The glossary also connects a term to a naming role, token family, token property, source system, and original source. This makes decisions traceable instead of relying on memory or personal preference.

A practical first workshop

Start with one token category, usually colour. Do not try to name every family at once. Work through one category until the structure feels clear, then repeat the same approach for the next one.

1. Choose four component groups to test the category. Pick components that expose different needs, so the naming is tested in real contexts:

   • Feedback: a Badge, Toast, or Notification.

   • Form: an Input or another form element.

   • Surface: a Card or Modal.

   • Action and controls: a Button, Segmented Control, Switch, Progress Bar, or Divider.
     
     

2. Paint them with primitive colours first. Use the raw scale while you explore the UI, for example color.blue.500, color.red.600, or color.gray.100. This makes the visual decisions concrete before you lock in names.
   
   

3. Turn repeated decisions into semantic colours. When the same primitive is used for the same purpose across several components, create a reusable semantic token such as color.background.success, color.text.error, or color.border.focus.
   
   

4. Scale from the semantic base. Once that base is stable, add modifiers, states, and component-level variables only where they add useful meaning. Keep following the same naming structure so new variables remain predictable.
   
   

5. Test the names with design and development. Can each person predict a token’s use without looking up its value? Record accepted terms and rejected alternatives in the glossary.
   
   

Keep the system intentionally incomplete

A good naming system does not need a term for every possible variation on day one. Add a segment only when it communicates a real distinction. If a modifier cannot change a decision, it is probably noise.

Use the Tokens glossary to compare vocabulary, scales, token families, and examples. Treat it as a map for making intentional choices, not a template to copy literally.