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

This tier is mainly responsible for the look of the final product by defining the all values that can be used. This idea leads to names like:

• global tokens
• brand tokens
• palette tokens
• option tokens
• choice tokens

Lastly, tokens in this tier are normally intended to only be used internally. This is why they are sometimes called private tokens or internal tokens.

In this article, I will refer to them as core tokens.

Second Tier Tokens

Tokens in this tier reference core tokens. Their name describes the intended use of the token. Because of this common names are:

• semantic tokens
• alias tokens
• applied tokens
• purpose tokens

Tokens in this tier are use the most throughout the application. They represent the choices the design system team made in regards to when to use which token. This is why the following names are common:

• common tokens
• application tokens
• decision tokens

In contrast to tier one tokens, those tokens are supposed to be used by everyone and are thus sometimes named public tokens.

I this article I will refer to them as semantic tokens.

Third Tier Tokens

Tokens in this tier reference semantic tokens and tie them to a specific component value. Because of this common names are:

• component tokens
• overwrites
• overwrite tokens
• scoped tokens

I this article I will refer to them as component tokens.

Elements of token names

Token names are made up of different elements. Depending on the tier different elements are combined to form a token name.

Namespacing

This refers to a prefix that is added to all tokens in the system, like --md in material design or spectrum- in adobes system. This namespace helps avoid problems were your design tokens use the same names as tokens from other systems that are used in combination. This happens for example when integrating into a system that uses something like bootstrap.

Commonly the namespace uses the name of the design system or organisation in full or an abbreviated form.

--spectrum-color-primary--yds-typography-size-sm

Tier

If you choose to make multiple tiers available to your users, you may want to add the specific tier to the token name. This makes it obvious to the user what kind of token they are working with.

--yds-core-color-blue-600: #0070F4;--yds-semantic-color-primary: var(--yds-core-color-blue-600);--yds-component-primary-button-bg: var(--yds-semantic-color-primary);

Type prefix or suffix

Prefixing or suffixing is mostly done with the token type e.g. color or radius. This is mostly important for usage in code where developers may get a long list of suggested tokens.

Personally I prefer to prefix the type as a kind of top level categorisation, e.g. --color-background—subtle. This allows you to type --color and only get suggestions for color tokens in your IDE.

--yds-core-color-blue-600--yds-semantic-radius-default--yds-semantic-headline-1-size
--yds-semantic-headline-1-weight

Scales

Scales are great when representing multiple elements in one family. Typically we use either numeric or ordinal.

Numeric Scales

A numeric scale can be 1-5, 0-1000 or 0,0.1,0.2,.... In general it is expected that in a numeric scale the difference between one step to the next is either identical in size or follows a strict algorithm e.g. it doubles in size between each step.

Numeric scales are often used for color families like Blue-100 to Blue-1000 but can also work for things like z-index or shadows.

However you should never use scales that directly represent the value, like size-20 for a 20px size token. This nullifies the abstraction and other benefits you get from design tokens.

--yds-core-blue-100
--yds-core-blue-200
--yds-core-blue-300--yds-core-spacing-unit-1x
--yds-core-spacing-unit-2x
--yds-core-spacing-unit-3x

Ordinal scales

Ordinal scales have a direction e.g. items in the scale get bigger, but they don’t say anything about the difference between individual items.

A good example are commonly used t-shirt sizes: sm, md and lg. You can reason about this:

• md is larger than sm
• lg is larger than md
• this means lg must be larger than sm

However, the increase between sm and md could be 4px and between md and lg it could be 8px.

Ordinal scales are especially helpful for small scales with around five items. Common types of ordinal scales are:

• Importance: Primary, Secondary, Tertiary, ...
• Intensity: none, low, normal, medium, high, max
• Strength: Weak, Moderate, Strong, Extreme
• Level: Level-1, Level-2, ...
• Speed: instant, immediate, quick or fast, moderate, slow, deliberate

--yds-core-radius-sm
--yds-core-radius-md--yds-semantic-color-on-dark-low-emphasize
--yds-semantic-color-on-dark-normal-emphasize--yds-core-shadow-weak
--yds-core-shadow-moderate--yds-core-z-index-lvl-1
--yds-core-z-index-lvl-2--yds-semantic-animation-speed-instant
--yds-semantic-animation-speed-fast

Categories

Tokens can often be categorised depending on where or when they should be used. This is especially prominent in colors with categories like:

Situation:

• Informational
• Tip
• Warning
• Error
• Success
• New
• Updated

Intended element:

• text color
• on color
• icon color
• fill color
• border color
• Shadow color

Intended part of a UI:

• Background color
• Foreground color
• Canvas color
• Surface color
• Interaction color
• UI Color
• Link color

--yds-semantic-color-warning
--yds-semantic-color-success--yds-semantic-text-color-default
--yds-semantic-border-color-hover--yds-semantic-color-link-default
--yds-semantic-color-link-hover
--yds-semantic-color-link-visited
--yds-semantic-color-link-active

Shades, tints & more

There are some terms in visual design that have a defined meaning and can be used to denote a specific token like blue-tone

• tone added grey or a less vibrant
• shade added black or a darker
• tint added white or a lighter
• subtle a less intense or vibrant
• intense or vibrant more intense and colourful
• bold strong, more intense, louder
• prominent or pronounced more noticeable

--yds-semantic-color-background-subtle--yds-semantic-color-text-prominent--yds-core-color-primary-shade
--yds-core-color-primary-tint

States

States are especially useful for interactive elements. However there may be other stateful aspects of your UI to consider.

• default, standard or resting
• hovered
• pressed, active
• selected, highlighted
• visited
• disabled or inactive
• enabled
• focused or in-focus
• custom states like downloaded, completed, archived

--yds-semantic-shadow-floating-default
--yds-semantic-shadow-floating-hovered--yds-semantic-color-ui-disabled--yds-semantic-color-primary-pressed

Names

In some cases a descriptive name can be all you need.

For example for easing curves there are common names like: easeIn, easeOut or easeInOut. Those names provide enough abstraction to allow you to change the values. There are similar things like:

• font weight regular, medium, bold
• font families monospace, serif, sans-serif, display
• font styles like caption, body, headline

--yds-core-font-weight-regular--yds-core-font-family-display--yds-semantic-font-style-body-weight

Modes, Platforms, etc.

Depending on your needs there may be other groupings to consider. However make sure adding a grouping mechanism makes sense and is justified by enough different tokens per group. Common examples are:

Modes like:

• light, dark, high-contrast
• day and night

Platforms like:

• iOS
• Android
• Web
• Mac
• Windows

Device categories like:

• Mobile
• Desktop
• Big screen
• Watches

Common naming patterns

Core tokens

Core tokensstore raw values to make them reusable in your semantic tokens. Their names should reflect the values they store and represent.

But they should still provide a little abstraction so that values can be adjusted. This means you should not put the value directly in the name e.g. never name them size-4px, color-red is fine though. It allows you to adjust the the hex value as long as it stays some kind of red.

Common elements of core token names are:

• namespacing if you use it in your system, use it for your core tokens as well.
• token types prefixing or suffixing your tokens with the type
• numeric scales are helpful especially for color families or sizing units
• ordinal scales like t-shirt or levels work very well for things like radii, elevation, shadows, etc.
• categories are important to cluster tokens, especially colors.
• names can be used for things like font weights e.g. 400 or regular. Other values can be similarly named e.g. font-families with monospace or serif.

Semantic tokens

Semantic tokens reference core tokens and suggest an intended use for it. Because of this their names should never reference the value but only what the token is intended for. They have a high level of abstraction. A typical name could be color-background or shadow-floating-hovered.

Some semantic tokens are very specific, like color-link. Others are broader like color-background-surface. The important part is that the user can understand what the token should and should not be used for.

Common elements of semantic token names are:

• namespacing if you use it in your system, use it for your semantic tokens as well.
• token types prefixing or suffixing your tokens with the type
• numeric scales try to avoid them for semantic tokens. They don't communicate an intended use. However, sometimes you do have tokens without a specific use. For example color shades for illustrations.
• ordinal scales avoid for semantic tokens. Often names are more precise, e.g. radius-default instead of radius-md. Sometimes this does not work, e.g. for z-index in which case a scale like levels is fine.
• names are extremely important for semantic tokens. For example body, headline and title for font styles.
• shades, tints & more are very helpful to create variants of tokens
• states communicate when to use a specific token and are perfect for semantic tokens
• platform, modes, etc. are very helpful depending on your system, e.g. for light and dark modes.

Component tokens

Component tokens reference semantic tokens to use them within a specific component. This allows users to overwrite individual properties for all component of one type.

For example a button component can expose the component token button-radius. By default button-radius references the value of a semantic token e.g. radius-default. A user can change button-radius to anything, e.g. 10px. This changes all buttons without effecting anything else that uses radius-default.

Common elements of component token names are:

• namespacing if you use it in your system, use it for your component tokens as well.
• token types are added as a prefix or suffix to your component tokens
• states communicate when a component token is used, for example on hover
• names are always used for component tokens. Specifically the name of the component. This lets the user knows what component the token influences.
• platforms can be used as well. For example when a token uses different font sizes for mobile and desktop.

Summary

Naming design tokens is complicated and must be done with care. You can’t adjust names once the system is published without introducing breaking change (which you should try to avoid at all times).

When naming design tokens, keep the token’s purpose in mind:

• core tokens give a name to a raw value to enable theming and make improve maintainability
• semantic tokens define the specific cases in which a referenced value should be used
• component tokens allow overwriting specific values for all components of the type.

References & further reading

• Naming Tokens in Design Systems, a classic: https://medium.com/eightshapes-llc/naming-tokens-in-design-systems-9e86c7444676
• Danny Banks’ talk on theming with design tokens: https://www.youtube.com/watch?v=P7kR5dag8iw

Interesting design systems in regards to naming:

• https://primer.style/design/foundations/color
• https://atlassian.design/foundations/color/
• https://www.lightningdesignsystem.com/design-tokens/