You can fully customize the structure of your tokens. You can change the hierarchies and rename the tokens to suit your needs, and the values will still always be synced with your design files.

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