Using tokens
JSON schema

JSON Schema

Tokens are represented in JSON, as a list of objects. A valid JSON would look like this:

{
  "colors": {
    "red": {
      "value": "#FF0000",
      "type": "color"
    },
    "blue": {
      "value": "#0000ff",
      "type": "color"
    }
  }
}

which would define 2 tokens, red and blue.

Description

Tokens can have a description, and the plugin will forward this to Figma when creating styles.

{
  "colors": {
    "red": {
      "value": "#FF0000",
      "type": "color",
      "description": "A red color"
    },
    "blue": {
      "value": "#0000ff",
      "type": "color",
      "description": "A blue color"
    }
  }
}

References

Tokens can contain references to other tokens.

{
  "colors": {
    "red": {
      "value": "#FF0000",
      "type": "color",
    },
    "primary": {
      "value": "{colors.red}",
      "type": "color",
    }
  }
}

Complex Tokens

Tokens can also be more complex than that, typography, shadow or composition tokens consist of many different values.

{
  "typography": {
    "h1": {
      "Bold": {
        "value": {
          "fontFamily": "Helvetica",
          "fontSize": 24,
          "fontWeight": "bold",
          "textDecoration": "none",
          "textCase": "none"
        },
        "type": "typography"
      },
      }
    }
  },
  "shadows": {
    "default": {
      "value": {
        "x": 4,
        "y": 4,
        "blur": 4,
        "spread": 0,
        "color": "rgba(0, 0, 0, 0.5)"
        "type": "dropShadow" | "innerShadow"
      },
      "type": "boxShadow"
    }
  },
  }
}

Single file storage

If you're exporting your JSON from Tokens Studio for Figma to a single file, the first level of that JSON is a bit special as it's indicating the token sets that you have. Names of token sets are never part of the token name, however we required to follow that structure because we are bound to a single file.

{
  "global": {
    "colors": {
      "white": {
        "value": "#FFFFFF",
        "type": "color",
      },
      "black": {
        "value": "#000000",
        "type": "color",
      }
    }
  },
  "light": {
    "background": {
      "value": "{colors.white}",
      "type": "color",
    },
    "text": {
      "value": "{colors.black}",
      "type": "color",
    }
  },
  "dark": {
    "background": {
      "value": "{colors.black}",
      "type": "color",
    },
    "text": {
      "value": "{colors.white}",
      "type": "color",
    }
  }
}

In the example above, you might notice that references are type colors.black, and not global.colors.black. This is because that first level is the set name, and that is never part of the token name. Think of token sets as files.

Multiple files storage

If you're using multi-file sync (a Pro feature), your token files will not have that set name as its first level. This makes it compatible with other tools such as style dictionary.

global.json

{
  "colors": {
    "white": {
      "value": "#FFFFFF",
      "type": "color",
    },
    "black": {
      "value": "#000000",
      "type": "color",
    }
  }
}

light.json

{
  "background": {
    "value": "{colors.white}",
    "type": "color",
  },
  "text": {
    "value": "{colors.black}",
    "type": "color",
  }
}

dark.json

{
  "background": {
    "value": "{colors.black}",
    "type": "color",
  },
  "text": {
    "value": "{colors.white}",
    "type": "color",
  }
}

Allowed token values

⚠️

It is suggested against using Value or Type as parts of token naming as it will create conflict in the JSON. Both the aforementioned are by default a part of the JSON script.

Depending on the Type of a token, we allow different values. The following JSON is a simplified visualisation:

{
  set1: {
    group: {
      token: {
        value: string | number,
        type: "spacing"
      },
    },
    group2: {
      shadowToken: {
        value: ShadowToken | ShadowToken[],
        type: "boxShadow"
      }
    },
    group3: {
      typographyToken: {
        value: TypographyToken,
        type: "typography"
      }
    }
  },
  set2: {
    group4: {
      colorToken: {
        value: string,
        type: "color"
      }
    }
  }
}