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#

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"
      }
    }
  }
}