The zeroheight tokens manager currently works with design tokens that conform to the Design Token Community Group specification. The specification's goal is for all tools that interact with design tokens to have a shared way of communicating to be used in harmony.

The Tokens Studio Figma plugin does not yet conform to this. You will need to make changes to import them into zeroheight. Hopefully, these tips will clarify how to format your token set to align with the spec.

File requirements

• The file must be a valid JSON
• It must have the extension .json, .json5,.tokens, or .tokens.json
• Link to more details

Token set requirements

The token set in your file needs to match the expected structure. Here's a short breakdown of how it should look.

Token Group

• A group name is based on the key of the JSON entry.
• Groups can contain the attributes:
  • $type - a plain string that can be used to infer the purpose of a token
    • This will also be inherited by any nested groups/tokens that don’t have their own defined type
  • $description - a plain string that describes the group itself
• Groups can be nested any number of times
• Link to more details

Token

• A token name is based on the key of the JSON entry.
• Tokens can contain the attributes:
  • $value - the value of a token (Required)
    • The values zh currently fully support are:
      • Color
        • Defined as color
        • 24bit RGB or 24+8bit RGBA color in the sRGB color space (string)
      • Cubic bezier
        • Defined as cubicBezier
        • array containing 4 number [P1x, P1y, P2x, P2y] (array)
      • Dimension
        • Defined as dimension
        • Numerical value follow by px or rem (string)
      • Duration
        • Defined as duration
        • Numerical value followed by ms (string)
      • Font family
        • Defined as fontFamily (string)
      • Font weight
        • Defined as fontWeight (string)
  • $type - predefined categorization applied to the token's value
  • $description - which is a plain string that describes the group itself
• You can add custom types to a token; this will mean there is no validation on the token's value.
• You can alias a value by putting the full path of another token within curly braces ({}) as a token value. E.g. {Color.primary.60} (Link to more details)
• Tokens can be in a group, but not inside other tokens.
• Link to more details

Reserved words in the spec:

• All reserved words are prefixed with a $. This means token and group names cannot begin with a $ as future versions of the spec may introduce new properties.
• Current reserved words: type, description, value
• Due to token aliases a token/group name must not use a curly brace { , }, or period .

Token set example

Here's an example of how you can use the different tokens:

{
  "base": {
    "$description": "All the base color tokens",
    "$type": "color",
    "palette": {
      "primary30": {
        "$type": "color",
        "$value": "#4F378B"
      },
      "primary50": {
        "$type": "color",
        "$value": "#826BBB"
      },
      "primary70": {
        "$type": "color",
        "$value": "#B6A1E9"
      },
      "primary90": {
        "$type": "color",
        "$value": "#EADDFF"
      }
    },
    "backgrounds": {
      "light-primary": {
        "$type": "color",
        "$value": "{base.palette.primary90}"
      },
      "dark-primary": {
        "$type": "color",
        "$value": "{base.palette.primary30}"
      }
    }
  },
  "sizes": {
    "$type": "dimension",
    "base spacing": {
      "$value": "0.25rem"
    },
    "digital": {
      "web": {
        "$value": "4rem"
      },
      "devices": {
        "tablet": {
          "$value": "80px"
        },
        "mobile": {
          "$value": "{sizes.base spacing}"
        }
      }
    }
  },
  "typography": {
    "primary font": {
      "$value": "Comic Sans MS",
      "$type": "fontFamily"
    },
    "font-weight-default": {
      "$value": 350,
      "$type": "fontWeight"
    }
  },
  "animation": {
    "$description": "Random tokens",
    "basics": {
      "small": {
        "$type": "cubicBezier",
        "$description": "Basic animation coordinates",
        "$value": [0, 0, 0.5, 1]
      },
      "Duration-100": {
        "$value": "100ms",
        "$description": "Average durations of an animation",
        "$type": "duration"
      }
    }
  }
}