Tokens

✨What are Tokens?✨

[theme_name] > tokens > src

Tokens are JSON files that define the foundation of the design system. Each token is turned into a variable using Style Dictionary, and updated in _generated-variables.css. The tokens are also used to tell Tailwind how you want to define your base utility classes for the site.

Tokens include:

• spacer sizes (e.g., --spacer-sm): used for heights (h-sm), widths (w-sm), padding(p-sm) and margin (m-sm)
• colors (e.g., --color-black): used for text color (text-black) and background color (bg-black)
• screen sizes (e.g., md): This lets tailwind know at what breakpoints a style should be applied (md:text-black)

A sample tokens file:

{
  "color": {
    "black": { "value": "#000000" },
    "white": { "value": "#FFFFFF" },
    "gray": {
      "lt": { "value": "#ededed" },
      "dk": { "value": "#444" }
    }
  }
}

How do they work?

Tokens turn the most basic design pieces of the design system into data. Because tokens are defined in JSON, they can be passed easily between files and projects. Style Dictionary reads the token files, and translates them into CSS custom properties. Tailwind is passed the same token files, and uses them to configure classes for the project. Twig can also be passed token files to loop through styles.

For a larger scale system, the same tokens can be shared across teams to maintain multiple sites or apps. By using a consistent set of tokens we can spend less time in QA, and create more consistency for developers between projects.

Some tokens will never change, like font weights. Others will change on each project, like colors. But the idea that our foundational design pieces should be used in the same way will be the same no matter the tech stack.

Updating token values

For consistency between projects, please don't change the custom property names.

❗ Changing token values changes styles across the site. Avoid changing token values once a site is in production, and if you do, talk to your team and designer first.

1. Make the change in the json file in tokens/src.
2. run npm run format.tokens
3. Expect to see an updated CSS custom property (variable) in _generated-variables.css.