Skip to main content

Contributing to the Design Token Library

Design tokens are the smallest building blocks of the design system that can be translated into code as a named entity (sizes, spacings, colors, …). In this section, you will learn how to update or add design tokens and how to release a new version of the design tokens library.
note

Make sure that you have a running Atlas setup on your machine. You can find a setup guide here

Tech setup​

You can find the source code and build set up of design tokens in a dedicated yarn workspace.

Design tokens are available in multiple formats – as JS constants, SCSS variables and JSON. This allows users to easily integrate the design token library in their setup.

To generate design tokens we use Style Dictionary. Based on a list of JSON source files (organized by category) output files in various formats are generated.

  • The source files can be found here
  • The output files can be found on root in folders named after their format. For example, JSON tokens can be found here

Editing design tokens​

You can find the source files of the design tokens in the tokens folder – don't manually edit the generated output files! When adding a new set of design tokens place a new JSON file next to the existing ones. They will automatically be bundled together with the others.

The JSON structure may, but doesn't have to, follow this pattern:

{
  [category - variant]: {
    [state]: {
      [property]: {
        "value": [value]
      }
    }
  }
}

example:

{
  "button-primary": {
    "active": {
      "box-shadow": {
        "value": "none"
      }
    }
  }
}

The generated token names will be concatenated based on the nested property names (e.g. button-primary-active-box-shadow in SCSS or ButtonPrimaryActiveBoxShadow in JS).

tip

You can reference other design tokens within a design token value. Read more about this in the Style Dictionary documentation.

If you added a new design token category make sure that it appears in the Token overview page:

Building design tokens​

After editing the design token property files the new tokens need to be generated into the various output formats. To do this run yarn build.

note

After building design tokens make sure to commit all changed files – including generated files!