Design Tokens

🎉 Create CSS themes using Figma Variables. 🎉

• ✅ Export variables from Figma
• ✅ Build Style Dictionary compatible tokens
• ✅ Create CSS custom properties from tokens

Access to Figma's Variables REST API

Per Figma's developer documentation to use Figma's Variables REST API you must have a full seat in an Enterprise org, guests cannot use the API.

Install

pnpm install -D @crowdstrike/design-tokens

Exporting Variables from Figma

To export variables you will need a a personal access token and a file (or branch) id.

export FIGMA_TOKEN=<personalAccessToken>

pnpm dt export-variables <FILE_ID>

If it's more convenient, or you'd rather not have to pass in the file id to the command line everytime, the file id could instead be commited to a tokens.config.js file. For example:

// tokens.config.js (default export must be an object)

export default {
  fileId: <FILE_ID>
}

// then run
pnpm dt export-variables;

The tokens.config.js file should be placed in the same directory as package.json.

The Figma variables will be written to variables.json in the same directory as package.json.

Building Tokens

To build tokens, run:

pnpm dt build-tokens

This will parse the variable's json and write a style-dictionary compatible tokens.json file alongside the previously created variables.json.

Exclude collections or variables

To exclude collections or variables from the tokens build, add a tokens.config.js file alongside your package.json. For example:

// tokens.config.js (default export must be an object)

export default {
  excludeCollections(collectionName) {
    const collections = ['System', 'Theme'];

    // Return true to exclude a collection. You could also
    // return false if it's more practical to define the
    // collections you want to keep. In this example only
    // the collections named System and Theme will be included.
    return !collections.includes(collectionName);
  },
  excludeVariables(variableName) {
    const variables = ['color', 'component', 'data-viz'];

    for (const variable of variables) {
      if (variableName.includes(variable)) {
        return true;
      }
    }
  },
};

The excludeCollections and excludeVariables methods must return either true or false.

Creating Custom Properties, Stylesheets, and Themes

Let's walk through the files needed to create stylesheets. Create a tokens.config.js file in your project root alongside tokens.json, with the following content:

{
  themes: [
    {
      colorScheme: 'dark',
      name: 'dark',
      tokenKey: 'dark',
    },
    {
      colorScheme: 'light',
      name: 'dark',
      tokenKey: 'light',
    },
    {
      colorScheme: 'normal',
      name: 'system',
      tokenKey: 'system',
    },
  ];
}

Assuming our tokens.json only consisted of:

{
  "dark": {
    "background/lightest": {
      "value": "#2c2c30",
      "type": "color"
    }
  },
  "light": {
    "background/lightest": {
      "value": "#ffffff",
      "type": "color"
    }
  },
  "system": {
    "space/x0": {
      "value": 0,
      "type": "float"
    }
  }
}

and we run:

pnpm dt build-styles

a styles directory would be created with 3 stylesheets:

/* dark.css */
:host,
.theme-dark {
  color-scheme: dark;
  --background-lightest: #2c2c30;
}

/* light.css */
:root,
:host,
.theme-light {
  color-scheme: light;
  --background-lightest: #ffffff;
}

/* system.css */
:root,
:host {
  color-scheme: normal;
  --space-x0: 0;
}

A quick study of the created stylesheets shows how the tokens and theme config were used to create the stylesheets:

• colorScheme defined the value for the color-scheme property in the stylesheet.
• name defined the stylesheet file name and also the theme's CSS selector concatenated with .theme-.
• tokenKey referenced an object in the tokens json.

Note also the selectors at the top of each rule set. A colorScheme of light is scoped to :root, meaning this theme will be the default theme. A color scheme of normal means the styles will also be scoped to :root but no .theme-<name> selector will be added as it's assumed this is a global stylesheet that will be loaded regardless of theme.

If you'd prefer the stylesheets were output to a directory other than styles, add outputDirectoryForStyles to the tokens.config.js, e.g:

export default {
  outputDirectoryForStyles: 'src/css',
}

The stylesheets will now be written in the src/css directory.

CSS custom properties prefix

By default there is no prefix added to the CSS variable names. If you wish to add a prefix define cssPrefix in tokens.config.js e.g:

export default {
  cssPrefix: 'cs',
}

All variables created will now have the cs prefix, e.g a variable named --foo-bar will now be --cs-foo-bar.