Design tokens file formats

Design tokens can be added to Interplay in JSON format. Interplay currently supports 2 formats for this JSON - W3C Community Draft format and ThemeUI format. This article describes how to use these formats with Interplay.

W3C Community Group - Draft Design Tokens file format

The W3C Working group for design tokens has specified a draft token file format that can be found here: Design Tokens Format

The format is a simple nested JSON structure, with token groups containing other token groups and the tokens themselves.

Versioning overview

This W3C tokens standard is an evolving draft, with rich discussion from many contributors. So the format does not yet have a formal semver versioning of releases. At Interplay we are keeping up with the published changes as closely as possible. In order to provide stability for your token imports we are using date-based version names for the standard at different points in time.

  • Manual file uploads through the Interplay browser UI need to be in the version shown as current below
  • Uploads from your repo using the CLI can use any format - specify the format you are using in the CLI settings. See importing tokens from your repo

The following sections summarise the currently supported versions of this standard, most recent first.

Current version: w3c@2022-04-05

This is the current version of the standard, required for file uploads through the Interplay UI in the browser. This format is very similar to the previous version, except reserved attribute names are now prefixed with $ to distinguish them, and composite values are now allowed.

Example file:

{
  "parentGroupX": {
    "$description": "Description of parentGroupX",
    "subgroup1": {
      "$description": "Description of subgroup1",
      "tokenA": {
        "$description": "Description of token A",
        "$type": "color",
        "$value": "#000000"
      },
      "tokenB": {
	"$description": "Description of token B",
        "$type": "color",
        "$value": "#FFFFFF"
      }
    }
  }
}

Summary of format:

  • A file containing a JSON object
  • Nodes in the JSON that have $value attribute are tokens. Other nodes are groups, which contain other nested groups or tokens
  • The node keys specify the name of the token or group e.g.
    • tokenA and tokenB are names of tokens in this example and
    • parentGroupX and subgroup1 are names of groups
  • Tokens and groups can optionally have $description, $type and $extensions attributes
  • Tokens can be cross-referenced by the path of name through the nesting structure, joining the names with dots e.g. parentGroupX.subgroup1.tokenB
  • Names are not allowed to contain special characters used in path references (dots and curly brackets)
  • Composite types are now allowed i.e.the token $value attribute can be an object containing multiple props

Version: w3c@2021-11-01

This was the initial version of the standard supported by Interplay. It is still supported for CLI imports to Interplay by specifying this as the format you are using in the CLI settings.

Example file:

{
  "parentGroupX": {
    "description": "Description of parentGroupX",
    "subgroup1": {
      "description": "Description of subgroup1",
      "tokenA": {
        "description": "Description of token A",
        "type": "color",
        "value": "#000000"
      },
      "tokenB": {
	"description": "Description of token B",
        "type": "color",
        "value": "#FFFFFF"
      }
    }
  }
}

Summary of format:

  • A file containing a JSON object
  • Nodes in the JSON that have value prop are tokens. Other nodes are groups, which contain other nested groups or tokens
  • The node keys specify the name of the token or group e.g.
    • tokenA and tokenB are names of tokens in this example and
    • parentGroupX and subgroup1 are names of groups
  • Tokens and groups can optionally have description, type and extensions attributes
  • Tokens can be cross-referenced by the path of name through the nesting structure, joining the names with dots e.g. parentGroupX.subgroup1.tokenB
  • Names are not allowed to contain special characters used in path references (dots and curly brackets)

Theme object format

As an alternative to the W3C format you add your tokens in Interplay you can add them as a theme object which will be converted into the current W3C format. This can be a useful way to get started when you already have a theme object.
You can add the theme object as follows:

  1. Write your theme object to a file as JSON data using JSON.stringify() or similar script.
  2. Navigate to the Tokens tab of your design system - you should see an empty state asking you to upload your tokens JSON
  3. Upload your JSON file

Interplay will iterate through the object creating a token group structure corresponding to the shape of your theme object, inferring types for the tokens based on common conventions e.g. type `color` for tokens contained a color group. Once in Interplay, we recommend curating the types to make sure they are what you expect.

For precise control of the token types imported from your repo, please use the W3C token format above.