Design Tokens

Definition

Design tokens are named entities that store visual design information. These are used in place of hard-coded values (such as hex values for color or pixels for spacing) in order to maintain a scalable, consistent system for UI development.

How does it works ?

Design tokens are defined in json files that are transpiled to multiple formats (scss, js, xml etc...) to be used on various platforms For example, with css, the tokens are transpiled from JSON to SCSS variables as well as SCSS maps.

We use style-dictionary, a solution developped by Amazon, to manage them.

We can define any transpilation template/format we need to acomodate our needs.

Why using design tokens ?

By compiling those tokens in multiple formats, we are able to keep things like colors in sync on all platforms and tech. Changing a color in the design tokens source file will update all projects using them, regardless of the underlying technology.

We use two "layers" of tokens

1 - the base, low level layer

To define all the basic values like colors, sizes etc. As an example, we define all the possible colors in the same place.

Most of the time, you should not have to use thoses variables directly, because a highter level of variable or a mixin should be available to provide authorized values for the type of property/element you are trying to define.

2 - an "elements" level layer

For example, we create a list of authorized values for text-colors or create some tokens to define buttons cosmetic styles. This layer make reference to the base layers values.

In the documentation you may read them expressed as js object keys selectors : color.button.solid.background when compiled to SCSS the dots are replaced with simple dashes - the scss variable will be $color-button-solid-background.

Tokens structure and conventions

Tokens are stored in ./packages/tokens/properties/...

They are organised by properties (colors, sizes, etc) in each directories and by pattern :

Example : ./packages/tokens/properties/color/button.json

Json naming conventions :

To create a component tokens file, you always start with the type of value, followed by the component name, the variation name, property name

[valuetype].[component].[variation].[property].value

You can reference the value another token by providing a string value : "{path.to.token.value}"

Example :

will generate (in scss) :

in packages/tokens/build/scss/_tokens.scss

What should you store into the design token files :

The way layout is handled inside component may differ from one platform to another. So we store only purely cosmetic value inside components design tokens. No paddings or margins for example. You should mainly use design tokens to store colors.