Importing design tokens from your repo

This article shows you how to import design tokens from your repo using the CLI. 

In this article

Pre-requisites

Before starting these steps, make sure you have prepared your repo and initialized the CLI as outlined in Preparing to Import

1. Create design tokens JSON file(s)

To import tokens from your repo, you need to create one or more JSON token files containing your tokens, usually either as a common reference file or with a custom script that creates these JSON files from elsewhere in your repo.

The JSON files you create should be in the W3C Community Draft Design Tokens format. For more details about this format and the format names to provide, see Design Token JSON formats

You can create a single file containing all your tokens or multiple files with different top level token group keys.

(You can also upload tokens in theme object format through the UI but the W3C format is required for CLI import as it is a developing open standard that specifies controlled types which Interplay can automatically map to Figma).

2. Configure the CLI to process the file(s)

Once you have created your design tokens JSON file, you then tell the CLI to process those files using the designTokens setting in .interplay/interplay.config.js This settings file is created by the CLI init step and controls the CLI import. There are placeholder settings in the default file for both components and tokens. In this case we're only interested in the tokens setting.

The easiest way to understand how to use this setting is from an example:

//interplay.config.js

designTokens: [
      {
        paths: [".interplay/init/default.tokens.json"],
        format: "w3c@2022-04-05",
        name: "Default Theme",
      },
      {
        paths: [".interplay/init/dark.tokens.json"],
        format: "w3c@2022-04-05",
        name: "Dark Theme",
      },
    ],

The designTokens CLI setting is an array of objects containing information about each theme of tokens. In the example above, two themes are specified - Default Theme and Dark Theme. These themes will be created in Interplay if they don't exist already when the import is run.

Each theme takes the following settings:

paths - specifies a glob pattern which resolves to the JSON files to import.

format - a string identifying the format of the JSON provided. Currently the W3C community group draft format is supported, with date-based versioning for different formats e.g. w3c@2022-04-05. See file formats.

name - the display name of the theme that will be displayed in Interplay.

Note that the structure of the tokens for each theme is expected to be consistent, so that swapping themes in Interplay would display the same token structure but with potentially different values for the different themes.

Currently it is not yet possible to configure theme inheritance through these import settings. To configure inheritance, first create the themes in Interplay and then configure the import to use the same theme names to populate the tokens.

3. Run the CLI

Now that you have configured the CLI to process your design tokens JSON files, you can run the CLI to deploy your theme/token config to Interplay

interplay deploy

The CLI will:

  1. Expand the glob paths specified to resolve the files to import for each theme
  2. Merge the JSON found in the files into a single data object for each theme
  3. Call the Interplay API for each theme, deploying the token data to the themes in your design system. If the theme name already exists the token data will be set for that theme, if the theme name does not exist a new theme will be created and the token data populated. 

Next: Importing code components from your repo