Design Tokens Guide

A new way of working to truly sync design and development, to bring design consistency throughout our platforms and to speed up our workflows.

What are Design Tokens?

Design tokens are design decisions that can be easily re-used throughout tools and platforms. A token can store values like color hex codes (#333333), font names (Arial), spacing with units (24px) and even values needed for timings in animations (20s). In a multi-brand and multi-theme setting we can overwrite values by keeping the names the same but have different value per brand or theme.

Example: “aero-color-text-default” can be #000 for Brand 1 but #222 for Brand 2. By applying the design token once to the body text we can then switch brands easily. In Brand 1 the customer sees a black text but going to Brand 2 will show a dark grey text.

Token Structure

To make it possible to switch between Brands, Themes and Sizes we need to work with a 2 or 3 Tier Tokens Structure. Tokens in a Tier can refer to or overwrite tokens in the previous Tier.

Tier 1	Tier 2	Tier 3
Core A palette of all numbers, colors and values that can be referred to or be overwritten by Brand or Theme/Size.	Brand Brand specific sizes, values and colors that can be referred to by Theme/Size.	Theme or Size The semantic layer that contains the tokens that are applied to the UI and components in our digital products.
Dimensions Space Global Colors Typography Shadows …	Size Space Brand Colors Font-Family Border-Radius …	Theme: Light and Dark color tokens Size: Small and Large size tokens
Example: aero-space-8 = [8px]	← aero-space-200	← aero-padding-xs

The component that works with a 8px padding for a specific Brand will use the aero-padding-xs token. Once a new decision comes to change that to 12px, the token stays unchanged (no breaking change is needed) but we refer to aero-space-400 now.

Caution: Only apply the tokens that are available in the Semantic Layer so in the Theme (Light/Dark) or Size (Small/Large) JSON files. This is a requirement to make the switch between brands, themes and sizes possible.

Token Naming

Tokens have names that are defined according to a certain structure. This helps us all identify the library but also what type of token it is and where to apply them. Most tokens are quite compact and look like this:

aero-color-surface-default

Library	Token Type	Category	Subcategory (if needed)	Hierarchy (if needed)	State
aero	-color	-surface	-action	-primary	-default

Applying Tokens

Principles
- Core and Brand tokens mostly define values
- Theme and Size Semantic tokens define meaning
- UI and components only consume Semantic tokens

Even-though there are the Core and Brand Tiers, we only apply semantic tokens to the UI and components. So the tokens found in Tier 3 (Theme: Light/Dark and Size: Small/Large) are applied via variables in Figma and in the value fields of our code.

The semantic tokens are named differently from the Core and Brand tokens. While those tokens are often named in a more technical manner (fe. aero-size-12 or aero-space-400) the semantic tokens have a natural tone where we use t-shirt sizing or a range between subtle and strong. (fe. aero-padding-xs or aero-borderRadius-strong).