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.0 | Tokens 2.0 |
Autogenerated in zeroheight but you can’t customize or change them | Autogenerated in zeroheight but you can customize and change them |
Generates tokens from all styles linked to the styleguide | Can create tokens linked to existing styles synced from your design uploads |
Can be exported in the formats:
| 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 Dictionary | Requires Amazon Style Dictionary |
Cannot create new custom tokens | Can create new custom tokens |
Token names cannot be changed | Token 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:
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.
2) From here you can either create design tokens linked to your existing styles or create entirely new, custom ones.
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.
2) Choose the styles you want to sync from your design uploads and click Add.
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.
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.
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
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.
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=trueCan 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.