Help Center

Design tokens 1.0 & 2.0 (legacy blocks)

Design tokens 1.0 & 2.0 (legacy blocks)

Tokens 1.0 and tokens 2.0 were the first iterations of supporting design tokens in zeroheight. As the concept of design tokens emerged and evolved in the industry, support for tokens in zeroheight has changed. It is now recommended to use zeroheight’s design token manager.

Tokens 1.0 and 2.0 are no longer being actively maintained and will be phased out over time.

Tokens 1.0 vs tokens 2.0

Tokens 1.0Tokens 2.0
Autogenerated in zeroheight but you can’t customize or change themAutogenerated in zeroheight but you can customize and change them
Generates tokens from all styles linked to the styleguideCan create tokens linked to existing styles  synced from your design uploads
Can be exported in the formats: 

  •  Sass
  • CSS
  • JSON
  • iOS/Swift
  • Android (XML)
Can export as JSON file or use a direct link to share tokens
Typography, color, and effect styles (shadow as an example)Typography, color, and effect styles
Does not require Amazon Style DictionaryRequires Amazon Style Dictionary
Cannot create new custom tokensCan create new custom tokens
Token names cannot be changedToken names can be changed
Can create token groups
Can create token aliases
Can create design tokens without design tools

 

Tokens 1.0

The tokens 1.0 block does not use Style Dictionary and can be exported in Sass, CSS, iOS and Android in addition to JSON.

Syncing design tokens

zeroheight creates and updates design tokens based on the typography and color style values in your team’s design tools, and makes them available to download using an API endpoint:

Red rectangle around download URL for your design tokens

Supported formats

The API supports the following export formats:

  • Sass
  • CSS
  • JSON
  • iOS / Swift
  • Android (XML)

By using this API, you can keep your codebase in sync with the latest design values automatically.

👉 Note: The only tokens synced are currently typography and color styles.

 

Tokens 2.0

In the Tokens 2.0 block, you are able to fully edit how your tokens are set up and which styles are included. You can also create completely custom tokens that are currently not supported by design tools.

Tokens 2.0 & Amazon Style Dictionary

We’ve designed Tokens 2.0 with Style Dictionary in mind. Style Dictionary is a powerful build system specifically designed for transforming tokens into whatever shape and form you require. With it you can export your design tokens into any format you need.

Adding tokens

1) You can add tokens to your styleguide from the toolbar.

Tokens 2.0 function hovered over in the zeroheight toolbar.

2) From here you can either create design tokens linked to your existing styles or create entirely new, custom ones.

Tokens 2.0 window

Creating tokens linked to styles

1) You can create new tokens which are linked to your existing styles via the Add styles button in the top right.

Cursor over the Add styles button in the tokens 2.0 window

2) Choose the styles you want to sync from your design uploads and click Add.

Sync styles from design uploads

3) Once you’ve added the styles, new tokens will be created which are directly linked with the styles from your design files. Whenever you update the styles in your design app, these changes will be reflected in the tokens.

Tokens 2.0 window with color styles

4) Hover over the token to see more detail about where the token is defined.

 

Share tokens 2.0

You can either download your design tokens as a JSON file or link to it via a direct link, accessible through the sharing popover in the top right.

Share tokens function hovered over in tokens window

 

Change a token’s name

By default all tokens which are linked to your styles will use the same name as the styles themselves, but should you wish to change them, simply rename them in the tokens editor

Gif showing how to rename tokens in the editor

This will rename how the tokens are referred to, but the values will always be linked to the styles in your design files.

 

Create custom tokens

To create a completely custom token, you simply need to create a new token definition and give it a value. First, let’s quickly look at how a token is defined:

{ 
  "token-name": {
    "value": "token-value"
  }
}

A token definition consists of a token-name and a token-value, which needs to be preceded by a value attribute; this is how Amazon Style Dictionary will know how to recognize it.

Now, to create a custom one, let’s say a base spacing unit of 8px, you change the token-name to whatever you want to call it and token-value to your desired value, like so:

{
  "spacing-unit": {
    "value": "8px"
  }
}

That’s it, you’ve just created a custom design token!

 

Create token groups

To make tokens easier to manage and read, you can create token groups which hold multiple tokens. Let’s say if you had multiple spacing tokens, you could go from this:

{
  "spacing-unit-small": {
  	"value": "4px"
  },
  "spacing-unit-regular": {
  	"value": "8px"
  }
}

to this:

{
  "spacing-unit": {
  	"small": {
  		"value": "4px"
  	},
  	"regular": {
  		"value": "8px"
  	}
  }
}

The output for both examples above will be exactly the same, spacing-unit-small and spacing-unit-regular, but you can organize your tokens a little more efficiently with groups. This will prove more valuable as your token collection grows and the names get longer.

 

Create token aliases

It’s quite common and useful to build a separation between generic and semantic tokens and this is where token aliases come in handy. Let’s say that you have a base green color, which might be used both for primary action buttons and success messages.

{
  "green": {
    "value": "#27AE60"
  }
}

But to ensure your color choices are future proof, you might not want to use the core green color directly on your components. Instead, you could create separate semantic tokens, which will be used by the components.

{
  "green": {
    "value": "#27AE60"
  },
  "primary-button-color": {
    "value": "{green}"
  },
  "success-message-color" {
    "value" "{green}"
  }
}

Here we are directly referencing the base green color through a token alias, which uses a special syntax of wrapping the token name in curly brackets — {green}. This ensures that if you ever want to change the color of either the primary button or success message, you can do that separately.

Let’s say you want your success messages to be using a more minty color, you can simply change the alias for success-message-color:

{
  "green": {
    "value": "#27AE60"
  },
  "mint": {
    "value": "#1FE09B"
  },
  "primary-button-color": {
    "value": "{green}"
  },
  "success-message-color" {
    "value": "{mint}"
  }
}

This also works with token groups, you simply need to separate each level of grouping with a dot in the token alias, like such:

{
  "color": {
      "green": {
        "value": "#27AE60"
      },
      "mint": {
        "value": "#1FE09B"
      }
    },
    "primary-button-color": {
      "value": "{color.green}"
    },
    "success-message-color" {
      "value": "{color.mint}"
    }
}

 

Tokens 2.0 FAQs

Can I still use the format of the old token?

Yes, you can still use the format of the previous token, as described here.

How do I convert the JSON output?

We recommend using Amazon Style Dictionary for transforming the JSON tokens into a format you need because tokens in zeroheight are directly compatible with this build system. It’s very powerful and very thoroughly documented.

What type of tokens can I define?

We currently support all core styles from all of our supported design tools:

Figma

  • Color styles
  • Font styles
  • Effects styles (shadows)

Sketch

  • Color styles
  • Font styles
  • Layer styles
  • This will include background colors, borders, and shadows

Adobe XD

  • Color styles
  • Character styles

Zeplin

  • Color palette
  • Text style catalog

On top of that, you can define your own custom tokens as documented here.

How do tokens work with releases?

With any new release, all token blocks will be re-created with new share URLs. The styles that are linked to these tokens blocks will however still get the latest updated styles. Other than that they work just like normal.

If you want to have a design tokens URL that always goes to the default release,  you can add the query parameter use_latest_release to the share URL. For example, the full URL would look like this: https://xxx.zeroheight.com/api/token_file/0987654321/share?use_latest_release=true
This will pull information from the token file in your default release.

Can I go back to a previous version of my tokens?

Tokens don’t yet have their own versioning and are directly tied to your styleguide releases, so if you want to revert to a previous version of tokens, you could copy tokens from a previous release over to the latest.

Can I only sync styles from my styleguide?

No, you can sync any styles that are available in your design uploads.

Can I have multiple token blocks?

Yes, you can insert as many token blocks as you want on any page and each of them will have a unique URL. This is great for separating out different token types, whether it’s on a single page or multiple.

I just deleted my tokens block, can I get it back?

Please contact support@zeroheight.com, and we can restore your tokens block.

Can zeroheight generate a CSS or Sass file from design tokens?

Our design tokens output as a JSON file. We recommend using  Amazon Style Dictionary (ASD) to transform the JSON tokens into a CSS or Sass file. ASD is a powerful tool that allows teams to output tokens into any format they may need.

Can I create design tokens without using a design tool?

You can create design tokens from tools like Adobe Photoshop using tokens 2.0. You can add styles from your design uploads or your styleguide. You will need to update them manually.