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 workspace package.

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 bun run build in packages/design-tokens or bun run build:design-tokens from the repository root.

note

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