Naming design tokens

How to effectively name your design tokens in a systematic and future-proof way.

Design tokens are the single source of truth for design primitives like colors or tokens. If you are new to the topic, you may want to learn the basics of design tokens first.

Note: This article aims to be an exhaustive reference for naming design tokens. If you find some information is missing, please do let me know via a comment or email so I can add it.

Naming token levels

Tokens are commonly split into different levels, each level has a specific use case, which I will explain later.

There are a few common names for this level concept:

• token levels
• token types
• token tiers
• token layers
• token groups

It does not really matter which one you use. However, you should make sure that you choose one that is widely understood within your organisation.

It’s best to choose one name e.g. token tiers and use it consistently. You should also explain it in the beginning of any documentation. Design tokens are complicated enough for people new to the topic, we don't want to make it harder.

I will use the term token tiers throughout this article to refer to the different types of tokens.

Token tiers

There are three tiers that are commonly used in design systems. Each token tier adds a specific capability to the design system. You can choose if you want to use all tiers or only one or two.

First Tier Tokens

Token in this tier store the raw values and with this build the basis of the design system. Because of this common names are:

• core tokens
• base tokens
• basic tokens
• foundation tokens
• meta tokens