Design Tokens

Introduction

Tokens are used in our build system to allow us to define styles once. This way they can be consumed across all platforms and keep the design system consistent.

The Pyramid Design Token Structure

The Pyramid Design Token Structure layers and abstracts variables and design tokens so that we can keep foundational items (colors, etc.) separately from design decisions. The three layers consist of global tokens, alias tokens, and component tokens — each with more decisions and granularity built in; all referencing from each other.

1. Global Tokens

Global Tokens act as our base layer of property definitions. They are global tokens that will be called upon by the next layer. Reference tokens are first-level, meaning, they are directly tied to values (ex. HEX colour value #FFFFFF, or pixel value of 16px).

This layer define tokens to cover areas such as colors, shadows, borders, media-queries and typography.

wfp-blue-60: #2a4ff0;

2. Alias Tokens

These tokens reference the Reference Tokens directly to form the visual interpretation of our design system. This set of tokens make opinionated choices around base sizing, typography scales, main border radiuses, status colours, etc.

Alias Tokens act as the foundational layer individual building blocks are constructed upon.

primary-button-color: $wfp-blue-60;

TODO: Check this, shall we call it Component level instead or would this add unnecessary complexity? https://uxplanet.org/design-tokens-a-design-system-superpower-dab07a5f0035

Alias Tokens can also reference each other:

primary-button-color: $action-default-fill-primary-default;

TODO/CHANGE: Check with Mauro if this is correct. Using multiple values should avoided since it will make it harder to change the values and also make it harder for usage across platforms.

Usually they assign only one value, but they can also reference multiple tokens.

"XL": {
        "fontFamily": "{fontFamily.open-sans}",
        "fontWeight": "{fontWeight.regular}",
        "lineHeight": "{lineHeight.75}",
        "fontSize": "{fontSize.Desktop.300}",
        "letterSpacing": "{letterSpacing.75}"
    }

3. Components

Here we are referencing your Alias Tokens to define the bits and pieces that make up your component, such as a button or an input field.

We are using scss to define the css/styles of the components. This level is no longer platform-independent.

@mixin button {
  background: $primary-button-color;
  font-size: $font-size-05;
  padding: $spacing-300;
  &:hover {
    background: $primary-button-color-hover;
  }
}

@mixin page-title {
  color: $text-body-default;
  font-size: $font-size-02;
  @include breakpointUp("md") {
    font-size: $font-size-03;
  }
}

Token naming

TODO: Add token naming

Customizing the Theme

We are using Style Dictionary to generate the tokens. You can customize the theme by adding a theme.config.js file to your project.

npx @wfp/themes-core --config theme.config.js

TODO better text: Usually you always want to import the defaultTheme when starting a customization. This will give you a base to work with.

You can override or create new tokens on each level:

un-blue-30: #2a4ff0;
primary-button-color: $un-blue-30;

// or directly assign a colour to a purpose
primary-button-color: #2a4ff0;

Usage in Figma

TODO: Add content

Usage in JS

All tokens can be directly imported in to your project. Use the following code to access them:

import { defaultTheme } from "@un/theme";

const { colors } = defaultTheme;

const App = () => (
  <ul>
    {Object.entries(colors).map(([i, color]) => (
      <li key={i}>
        <span
          style={{
            backgroundColor: color.value,
          }}
        />
        {color.name}
      </li>
    ))}
  </ul>
);

Usage in CSS

@import "@un/theme/scss/variables";

body {
  background-color: $primary-background;
}

//TODO: Check code

Reference

• Design Tokens — a Design System Superpower!
• Design tokens cheatsheet