Design Tokens JSON formats

Design tokens can be added to Interplay in JSON format. Interplay currently supports 2 formats for this JSON:

  • W3C Community Draft format
  • ThemeUI format

W3C Community Group - Draft Design Tokens 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 nested JSON structure, with objects containing groups of token values. For example:

{
  "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 and names of tokens
    • 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)

Token type

You can specify any type string for your tokens.

Currently the following type values are recognised as having special meaning in Interplay:

  • Tokens with the following types can be used to style Frames in Figma using the Interplay plugin:
    • color
    • border
    • borderRadius
    • shadow
    • size ( used for padding and gap when Frame in auto-layout )

  • Tokens with the following types can be used to style text in Figma using the Interplay plugin.
    • fontWeight
    • fontFamily
    • fontSize
    • lineHeight
    • color

Theme UI format

Theme UI format has a similar nested structure, but with certain keys expected at the top level of the JSON object.

You can find details of this spec here: https://theme-ui.com/theme-spec/

When importing the ThemeUI format the top-level keys are treated as groups of tokens, with the token values inside.