Design Tokens

Background

Our design tokens are stored in JSON, the benefit of which is that they can be converted or translated into other languages or tools (e.g CSS, Swift, Kotlin, Figma).

For more information on how design tokens are named and organized, see the Acorn Design System docs.

Design token tiers

Design tokens are split into different levels: base, application, and component. The global tokens-shared.css, tokens-brand.css and tokens-platform.css files include the base, application and some component tokens. Component tokens that are generally used for styling outside of reusable moz- components like button, card, input, sidebar, panel, etc are included.

While there are many global tokens, some component tokens are stored next to their component and aren’t always imported by default. The moz- components keep their design token definitions next to their CSS/JS in toolkit/content/widgets/moz-*/, and the browser/themes/shared/ folder also has design tokens. This means design tokens for tabbrowser, urlbar, etc can be kept with the code that uses them.

Only design tokens in the toolkit/themes/shared/design-system/src/tokens/ folder are included in the global design tokens. Any other design tokens will be built next to their source component.tokens.json file and need to be manually included where they’re needed.

Quick start

src/tokens holds our source of truth for design tokens in mozilla-central under the design-system folder in toolkit/themes/shared. The CSS design token files in that folder come from the JSON files. If you need to modify a design token file, you should be editing the JSON.

The tokens are organized into files with the *.tokens.json suffix, where the first part of the filename defines the top-level category of token. For example, border.tokens.json outputs --border-* tokens.

In order for us to be able to define design tokens in one place (the JSON files) and allow all platforms to consume design tokens in their specific format, we use a build system called Style Dictionary.

Here’s how to build design tokens for desktop:

$ ./mach buildtokens

If successful, you should see Style Dictionary building all of our tokens files within the design-system/dist folder. Otherwise, Style Dictionary can also generate helpful errors to help you debug.

At the end, we’re capable of transforming JSON notation into CSS:

{
 "color": {
  "blue": {
    "0": {
      "value": "oklch(97% 0.05 260)"
    },
    "10": {
      "value": "oklch(90% 0.13 260)"
    },
    "20": {
      "value": "oklch(83% 0.17 260)"
    },
    "30": {
      "value": "oklch(76% 0.2 260)"
    },
    "40": {
      "value": "oklch(69% 0.22 260)"
    },
    "50": {
      "value": "oklch(62% 0.24 260)"
    },
    "60": {
      "value": "oklch(55% 0.24 260)"
    },
    "70": {
      "value": "oklch(48% 0.2 260)"
    },
    "80": {
      "value": "oklch(41% 0.17 260)"
    },
    "90": {
      "value": "oklch(34% 0.14 260)"
    },
    "100": {
      "value": "oklch(27% 0.1 260)"
    },
    "110"