Design Token-Based UI Architecture

What are design tokens?

Salesforce originally introduced design tokens to streamline design updates to multiple platforms.

The Design Tokens Community Group describes design tokens as “a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies

Let’s break this down:

• Cross-Disciplinary Collaboration: Design tokens act as a common language that aligns designers, developers, product managers, and other disciplines. By offering a single source of truth for design decisions, they ensure that everyone involved in the product life cycle is on the same page, leading to more efficient workflows.
• Tool integration: Design tokens can be integrated into various design and development tools, including UI design software, token editors, translation tools (code generators), and documentation systems. This enables design updates to be quickly reflected in the code base and are synchronized across teams.
• Technology adaptability: Design tokens can be translated into different technologies like CSS, SASS, and JavaScript for the web, and even used on native platforms like Android and iOS. This flexibility enables design consistency across a variety of platforms and devices.

Fully automated pipeline

The most straightforward way to design the pipeline would be a fully automated trunk-based workflow. In this setup, all changes pushed to the main branch will be immediately deployed as long as they pass the automated quality gates.

Such a pipeline might consist of the following jobs:

1. Check: Validate the design token files using a design token validator or a JSON validator.
2. Build: Use a translation tool like Style Dictionary to convert design token files into platform-specific formats. This job might also build the docs using the translation tool or by integrating a dedicated documentation tool.
3. Test: This job is highly dependent on the testing strategy. Although some tests can be done using the design token file directly (like checking the color contrast), a common approach is to test the generated code using a documentation tool such as Storybook. Storybook has excellent test support for visual regression tests, accessibility tests, interaction tests, and other test types.
4. Publish: Publish updated tokens to a package manager (for example, npm). The release process and versioning can be fully automated with a package publishing tool that is based on Conventional Commits like semantic-release. semantic-release also allows the deployment of packages to multiple platforms. The publish job might also deploy documentation for the design tokens.
5. Notify: Inform teams of the new token version via email or chat, so that they can update their dependencies.

Figure 3: Fully automated deployment pipeline

Pipeline including manual approval

Sometimes fully automated quality gates are not sufficient. If a manual review is required before publishing, a common approach is to deploy an updated version of the documentation with the latest design token to a preview environment (a temporary environment).

If a tool like Storybook is used, this preview might contain not only the design tokens but also show them integrated with the components used in the application.

An approval process can be implemented via a pull-request workflow. Or, it can be a manual approval / deployment step in the pipeline.

Figure 4: Deployment pipeline with manual approval

Option tokens: defining what design options are provided

Option tokens (also called primitive tokens, base tokens, core tokens, foundation tokens or reference tokens) define what styles can be used in the application. They define things like color palettes, spacing/sizing scales or font families. Not all of them are necessarily used in the application, but they present reasonable options.

Using our example, let’s assume we have a color palette with 9 shades for each color, ranging from very light to highly saturated. Below, we define the blue tones and grey tones as option-tokens:

{
  "color": {
    "$type": "color",
    "options": {
      "blue-100": {"$value": "#e0f2ff"},
      "blue-200": {"$value": "#cae8ff"},
      "blue-300": {"$value": "#b5deff"},
      "blue-400": {"$value": "#96cefd"},
      "blue-500": {"$value": "#78bbfa"},
      "blue-600": {"$value": "#59a7f6"},
      "blue-700": {"$value": "#3892f3"},
      "blue-800": {"$value": "#147af3"},
      "blue-900": {"$value": "#0265dc"},
      "grey-100": {"$value": "#f8f8f8"},
      "grey-200": {"$value": "#e6e6e6"},
      "grey-300": {"$value": "#d5d5d5"},
      "grey-400": {"$value": "#b1b1b1"},
      "grey-500": {"$value": "#909090"},
      "grey-600": {"$value": "#6d6d6d"},
      "grey-700": {"$value": "#464646"},
      "grey-800": {"$value": "#222222"},
      "grey-900": {"$value": "#000000"},
      "white": {"$value": "#ffffff"}
    }
  }
}

Although it’s highly useful to have reasonable options, option tokens fall short of being sufficient for guiding developers on how and where to apply them.

Decision tokens: defining how styles are applied

Decision tokens (also called semantic tokens or system tokens) specify how those style options should be applied contextually across the UI.

In the context of our color example, they might include decisions like the following:

• grey-100 is used as a surface color.
• grey-200 is used for the background of disabled elements.
• grey-400 is used for the text of disabled elements.
• grey-900 is used as a default color for text.
• blue-900 is used as an accent color.
• white is used for text on accent color backgrounds.

The corresponding decision token file would look like this:

{
  "color": {
    "$type": "color",
    "decisions": {
      "surface": {
        "$value": "{color.options.grey-100}",
        "description": "Used as a surface color."
      },
      "background-disabled": {
        "$value": "{color.options.grey-200}",
        "description":"Used for the background of disabled elements."
      },
      "text-disabled": {
        "$value": "{color.options.grey-400}",
        "description": "Used for the text of disabled elements."
      },
      "text": {
        "$value": "{color.options.grey-900}",
        "description": "Used as default text color."
      },
      "accent": {
        "$value": "{color.options.blue-900}",
        "description": "Used as an accent color."
      },
      "text-on-accent": {
        "$value": "{color.options.white}",
        "description": "Used for text on accent color backgrounds."
      }
    }
  }
}

As a developer, I would mostly be interested in the decisions, not the options. For example, color tokens typically contain a long list of options (a color palette), while very few of those options are actually used in the application. The tokens that are actually relevant when deciding which styles to apply, would be usually the decision tokens.

Decision tokens use references to the option tokens. I think of organizing tokens this way as a layered architecture. In other articles, I have often seen the term tier being used, but I think layer is the better word, as there is no physical separation implied. The diagram below visualizes the two layers we talked about so far:

Figure 5: 2-layer pattern

Component tokens: defining where styles are applied

Component tokens (or component-specific tokens) map the decision tokens to specific parts of the UI. They show where styles are applied.

The term component in the context of design tokens does not always map to the technical term component. For example, a button might be implemented as a UI component in some applications, while other applications just use the button HTML element instead. Component tokens could be used in both cases.

Component tokens can be organised in a group referencing multiple decision tokens. In our example, this references might include text- and background-colors for different variants of the button (primary, secondary) as well as disabled buttons. They might also include references to tokens of other types (spacing/sizing, borders etc.) which I'll omit in the following example:

{
  "button": {
    "primary": {
      "background": {
        "$value": "{color.decisions.accent}"
      },
      "text": {
        "$value": "{color.decisions.text-on-accent}"
      }
    },
    "secondary": {
      "background": {
        "$value": "{color.decisions.surface}"
      },
      "text": {
        "$value": "{color.decisions.text}"
      }
    },
    "background-disabled": {
      "$value": "{color.decisions.background-disabled}"
    },
    "text-disabled": {
      "$value": "{color.decisions.text-disabled}"
    }
  }
}

To some degree, component tokens are simply the result of applying decisions to specific components. However, as this example shows, this process isn’t always straightforward—especially for developers without design experience. While decision tokens can offer a general sense of which styles to use in a given context, component tokens provide additional clarity.

Figure 6: 3-layer pattern

Note: there may be “snowflake” situations where layers are skipped. For example, it might not be possible to define a general decision for every single component token, or those decisions might not have been made yet (for example at the beginning of a project).

How many layers shall I use?

Two or three layers are quite common amongst the bigger design systems.

However, even a single layer of design tokens already greatly limits the day-to-day decisions that need to be made. For example, just deciding what units to use for spacing and sizing became a somewhat nontrivial task with up to 43 units for length implemented in some browsers (if I counted correctly).

A three-layer architecture should offer the best developer experience. However, it also increases maintenance effort and token count, as new tokens are introduced with each new component. This can result in a larger code base and heavier package size.

Starting with two layers (option and decision tokens) can be a good idea for projects where the major design decisions are already in place and/or relatively stable. A third layer can still be added if there is a clear need.

An additional component layer makes it easier for designers to change decisions later or let them evolve over time. This flexibility could be a driving force for a three-layer architecture. In some cases, it might even make sense to start with component tokens and to add the other layers later on.

Ultimately, the number of layers depends on your project's needs and how much flexibility and scalability are required.

File-based scope

Using Style Dictionary, we can use a filter to expose only public tokens. The most straightforward approach would be to filter on the file ending. If we use different file endings for component, decision and option tokens, we can use a filter on the file path, for example, to make the option tokens layer private.

Style Dictionary config

  const styleDictionary = new StyleDictionary({
    "source": ["color.options.json", "color.decisions.json"],
    "platforms": {
      "css": {
        "transformGroup": "css",
        "files": [
          {
            "destination": "variables.css",
            "filter": token => !token.filePath.endsWith('options.json'),
            "format": "css/variables"
          }
        ]
      }
    }
  });

The resulting CSS variables would contain only these decision tokens, and not the option tokens.

Generated CSS variables

  :root {
    --color-decisions-surface: #f8f8f8;
    --color-decisions-background-disabled: #e6e6e6;
    --color-decisions-text-disabled: #b1b1b1;
    --color-decisions-text: #000000;
    --color-decisions-accent: #0265dc;
    --color-decisions-text-on-accent: #ffffff;
  }

A more flexible approach

If more flexibility is needed, it might be preferable to add a scope flag to each token and to filter based on this flag:

Style Dictionary config

  const styleDictionary = new StyleDictionary({
    "source": ["color.options.json", "color.decisions.json"],
    "platforms": {
      "css": {
        "transformGroup": "css",
        "files": [
          {
            "destination": "variables.css",
            "filter": {
              "public": true
            },
            "format": "css/variables"
          }
        ]
      }
    }
  });

If we then add the flag to the decision tokens, the resulting CSS would be the same as above:

Tokens with scope flag

  {
    "color": {
      "$type": "color",
      "decisions": {
        "surface": {
          "$value": "{color.options.grey-100}",
          "description": "Used as a surface color.",
          "public": true
        },
        "background-disabled": {
          "$value": "{color.options.grey-200}",
          "description":"Used for the background of disabled elements.",
          "public": true
        },
        "text-disabled": {
          "$value": "{color.options.grey-400}",
          "description": "Used for the text of disabled elements.",
          "public": true
        },
        "text": {
          "$value": "{color.options.grey-900}",
          "description": "Used as default text color.",
          "public": true
        },
        "accent": {
          "$value": "{color.options.blue-900}",
          "description": "Used as an accent color.",
          "public": true
        },
        "text-on-accent": {
          "$value": "{color.options.white}",
          "description": "Used for text on accent color backgrounds.",
          "public": true
        }
      }
    }
  }

Generated CSS variables

  :root {
    --color-decisions-surface: #f8f8f8;
    --color-decisions-background-disabled: #e6e6e6;
    --color-decisions-text-disabled: #b1b1b1;
    --color-decisions-text: #000000;
    --color-decisions-accent: #0265dc;
    --color-decisions-text-on-accent: #ffffff;
  }

Such flags can now also be set through the Figma UI (if using Figma variables as a source of truth for design tokens). It is available as hiddenFromPublishing flag via the Plugins API.

When to use design tokens

1. Multi-Platform or Multi-Application Environments: When working across multiple platforms (web, iOS, Android…) or maintaining several applications or frontends, design tokens ensure a consistent design language across all of them.
2. Frequent Design Changes: For environments with regular design updates, design tokens provide a structured way to manage and propagate changes efficiently.
3. Large Teams: For teams with many designers and developers, design tokens facilitate collaboration.
4. Automated Workflows: If you’re familiar with CI/CD pipelines, the effort to add a design token pipeline is relatively low. There are also commercial offerings.

When design tokens might not be necessary

1. Small projects: For smaller projects with limited scope and minimal design complexity, the overhead of managing design tokens might not be worth the effort.
2. No issue with design changes: If the speed of design changes, consistency and collaboration between design and engineering are not an issue, then you might also not need design tokens.