Design System Tokens Package

This package is the single source of truth for our design tokens.

Defining Tokens

All tokens are defined in src/tokens/base.json. All changes to the design tokens should occur in this file.

Token Format

Tokens in src/tokens/base.json are defined using a modified version of the W3C Design Tokens Community Group Token Definition Standard.

The version we use is somewhat modified to be more compatible with the Tokens Studio for Figma plugin. We specifically use a subset of unofficial tokens-studio-specific types. This enables for better token definitions in figma.

When adding tokens, define them using the DTCG spec, then upload them into the Tokens Studio plugin in Figma to make sure that they are defined as expeced in the figma file.

This process will be documented better as we start contributing changes to tokens.

Building Tokens

Once tokens have been added to src/tokens/base.json in the correct format and successfully updated in Figma, it is necessary to update them for all supported platforms: Typescript, CSS, and Chakra-specific (internal).

To update all platforms, run the following script from this directory:

pnpm build

This will update all tokens in src/generated.

Token Build Process

Tokens are transformed from the tokens stored in src/tokens/base.json using style-dictionary.

Style dictionary is configured in src/style-dictionary.config.js. Update this config file in order to change the formatting of any tokens in src/generated/*. See comments in that file for more information.

This process will also be better documented as we start distributing the tokens package for use in the design system.