The Design Tokens plugin for Figma allows you to export design tokens into a json format that can be used with the Amazon style dictionary package. This allows you to transform your tokens to different languages / platforms like web, iOS or Android.
- Installation
- Plugin usage
- FAQ
- Transforming tokens using Amazon style dictionary
- Creating design tokens
- Settings
- Contribution
- Go to the design tokens plugin page
- Click on install in the top right corner
The plugin has a couple options in the menu items:
This creates a .json
file with all design tokens from your Figma project. A dialog will open allowing you to save the file on your hard drive.
This triggers a request sending your tokens to a server. For this to work you must have configured a server to send your tokens to in the plugin settings.
Opens the settings view, which allows you to change all settings mentioned in the settings section below.
Resets all your settings to the default. This is helpful when you run into problems with corrupted settings (Plugin does not work as expected).
Opens the demo figma file. Note: You will not have permission to change or export tokens from this file but it will give you an idea of how to set up tokens.
Opens this documentation page.
You can find frequent questions and issues in the faq.
- Clone the design token transformer repositiory.
git clone https://github.com/lukasoppermann/design-token-transformer.git
- Export your tokens using the plugin and place the json file in the
tokens
folder within the transformer repositry - Run
npm run transform-tokens
from the commandline - 🎉 Your converted tokens should be in the
build
folder. For more customization options check out the design token transformer documentation
The package style-dictionary-utils provides a parsers and many filters and transformers that can be used with w3c design tokens
.
It is meant to help you set up a build process with the tokens exported from figma design tokens.
The plugin converts the styles you define in Figma into design tokens, this includes Text Styles
, Color Styles
, Grid Styles
and Effect Styles
.
Depending on the export format you get a different result. In the Original
format every property of a style will be converted to an individual token.
When using the Standard
format composite tokens are created, for example the properties of a text style are all exported as one composite token.
However for Text Styles
the Standard
format has a special typography
type that if enabled exports the individual tokens as well. This may result in the following tokens (show as transformed css custom properties for readability).
--font-headline-3-font-size: 20;
--font-headline-3-text-decoration: none;
--font-headline-3-font-family: Roboto;
--font-headline-3-font-style: italic;
--font-headline-3-font-weight: 500;
--font-headline-3-font-stretch: condensed;
--font-headline-3-font-style-old: Medium Italic Condensed; /* only to preserve original value */
--font-headline-3-letter-spacing: 2;
--font-headline-3-line-height: 160;
--font-headline-3-paragraph-indent: 5;
--font-headline-3-paragraph-spacing: 8;
--font-headline-3-text-case: uppercase;
Styles don't have to follow a specific naming convention. Any style will be exported into a design token, as long as it does not match the ignore pattern
.
This means you can name your styles Headline
or Foundation/Colors/Primary/Red/100
and either one works fine.
Styles you don't want to be exported as design tokens can be prefixed with an _
underscore. For example a color style called _readlining/line-color
will not be exported.
In the settings you can change the prefix for ignoring/including styles.
The plugin also supports custom tokens for borders
, radii
, sizes
, spacing
& motion
.
- Every custom design token must be within a top-level
Frame
with a name starting with_tokens
. This means you have a structure like this:page
>_tokens/sizes
>sizes/8
. - The token itself has to have a name starting with
sizes
,spacing
,borders
,radii
ormotion
and has to be aMain Component
orvariant
. This is so that the plugin can identify what is and what isn't a token.
Naming: The name for the design token will be created by combining the main name with the property value e.g. variant sizes
with the property size
with the values 8
and 16
will result in 2 tokens
sizes/8
sizes/16
Ignore properties: If you want a property to be ignored you can prefix it with an _
, e.g. the property _hidden
will be ignored.
To create a sizes token, do the following:
- Create a
Frame
and name it_tokens/sizes
- Create another
Main Component
and set the width property to your8
. - Name it
sizes/8
. Note, it is important to use thesizes/
prefix.
The token will be exported, if you convert it to css the output would be something like this:
--sizes-8: 8;
To create a spacing token, do the following:
- Create a
Frame
and name it_tokens/spacing
- Create another
Main Component
and set the padding properties to10
in theauto layout
. - Name it
spacing/10
. Note, it is important to use thespacing/
prefix.
The token will be exported, if you convert it to css the output would be something like this:
--spacing-10-top: 10;
--spacing-10-right: 10;
--spacing-10-bottom: 10;
--spacing-10-left: 10;
To create a breakpoint token, do the following:
- Create a
Frame
and name it_tokens/breakpoints
- Create another
Main Component
and set the width property to your desired values (example forlg
->1280
). - Name it
breakpoints/lg
. Note, it is important to use thebreakpoints/
prefix.
The token will be exported, if you convert it to css the output would be something like this:
--breakpoints-lg: 1280;
To create a border token, do the following:
- Create a
Frame
and name it_tokens/borders
- Create another
Main Component
and set the stroke property to your desired values. - Name it
borders/dashed-outside
. Note, it is important to use theborders/
prefix.
The token will be exported, if you convert it to css the output would be something like this:
--borders-dashed-outside-stroke-align: outside;
--borders-dashed-outside-dash-pattern: 5,5,3,3;
--borders-dashed-outside-stroke-cap: none;
--borders-dashed-outside-stroke-join: miter;
--borders-dashed-outside-stroke-miter-limit: 4;
--borders-dashed-outside-stroke-weight: 1;
--borders-dashed-outside-stroke: rgba(64, 255, 186, 1);
To create a radius token, do the following:
- Create a
Frame
and name it_tokens/radii
- Create another
Main Component
and set the radius properties to your desired values. - Name it
radii/same-with-smoothing
. Note, it is important to use theradii/
prefix.
The token will be exported, if you convert it to css the output would be something like this:
--radii-same-with-smoothing-radius: 5;
--radii-same-with-smoothing-radius-type: single;
--radii-same-with-smoothing-radii-top-left: 5;
--radii-same-with-smoothing-radii-top-right: 5;
--radii-same-with-smoothing-radii-bottom-right: 5;
--radii-same-with-smoothing-radii-bottom-left: 5;
--radii-same-with-smoothing-smoothing: 0.65;
Motion tokens are a combination of an easing curve
, a duration
and an animation type.
To create a motion token follow this flow:
- Create a new
Frame
called_tokens/motion
- Create a new
Main Component
- Name it
motion/move-in
. Note, it is important to use themotion/
prefix. - Enter
prototyping mode
and link the elementmotion/move-in
to any other element. - Choose an
animation type
,easing curve
and aduration
When exporting your tokens you will now get a set of properties for this motion set.
--motion-move-in-type: move_in;
--motion-move-in-duration: 0.5;
--motion-move-in-easing: ease-in;
--motion-move-in-easing-function-x-1: 0.41999998688697815;
--motion-move-in-easing-function-x-2: 1;
--motion-move-in-easing-function-y-1: 0;
--motion-move-in-easing-function-y-2: 1;
--motion-move-in-direction: left;
To create opacity tokens, do the following:
- Create a new
Frame
called_tokens/opacities
- Create a new
Main Component
- Set the desired
Pass through
value (ie. 30%) - Give it a fitting name, e.g.
opacity/input-disabled
After exporting it, if you convert it to CSS, the resulting token will look like this:
--opacity-input-disabled: 0.3;
To allow for maximum customizability I decided to provide all values that Figma provides. Many are not applicable to for example css
but may be usable in other languages.
Colors are provided in rgba
but can be converted using Amazon style dictionary.
When enabled, token names will be prefixed with the token type e.g. "color" or "font". This effectifly groups tokens by type.
This option allows you to define how the token names will be converted when they are store in the json file, the available options are:
Default
– spaces from the beginning and end are removed and the name is converted to lowercasecamelCase
- spaces from the beginning and end are removed and the name is converted to camelCasekebab-case
- spaces from the beginning and end are removed and the name is converted to kebab-case
This option defines the structure for the json output.
This format is based on the current spec draft of the Design Tokens W3C Community Group. It is much simpler and makes it easier to define custom transformers for amazon style dictionary.
Every token follows this structure (learn more):
type StandardTokenInterface = {
name: string,
description?: string,
value: StandardTokenValueType | StandardCompositeTokenValueType,
type: StandardTokenTypes,
extensions?: StandardTokenExtensionsInterface
}
This is the original format of the plugin. It is mainly in here to allow teams to slowly migrate to the standard format. This works better with amazon style dictionary for basics. However if you want to create custom transformers the Standard format is better.
By default the plugin ignores any style that is prefixed with _
or .
.
You can define any additional prefix via this option, e.g *
. This can be helpful when you want to have styles that are shared across files in figma, but that should not be exported to your design tokens.
Notes:
- This setting only applies to Figma styles (colors, typography, grids & effects). It does not apply to custom tokens.
- The prefix has to be in the beginning of the token name, e.g.
.My Colors/Internal/Red
will be ignored, whileMy Colors/.Internal/Red
will be exported.
The standard token format allows you to define an alias/reference for a color tokens via the description field.
For example if you want the color style danger-color
to reference the color style core-colors/red
you can add a ref:
line to the description field of the danger-color
:
Use this color for destructive actions only.
ref: core-colors.red
This will create an output in your json like this:
"danger-color": {
"description": "Use this color for destructive actions only.",
"type": "color",
"value": "{core-colors.red}"
}
The alias line is removed from the description field during export. If you active prefixing token types or token prefixes they will automatically be added.
In the settings you can defined the valid alias indentifiers like ref
. By default it is set to alias, ref, reference
.
When enabled this option keeps the token prefix in the name, e.g. for color/red
the token prefix is color
and the token name is red
.
For styles: Styles do not have a prefix so when enabled the plugin will add the prefix to the token name.
- Color style:
red
->color/red
- Gradient style:
black to white
->gradient/black to white
- Font style:
h1
->font/h1
- Grid style:
mobile
->grid/mobile
- Color style:
shadow 4dp
->effect/shadow 4dp
For custom tokens: Custom tokens use the prefix to identify the token e.g. radius/5px
, the prefix radius
is used by the plugin to indetify the token type. This means the name already includes the prefix and nothing will be added. However it this option is disabled the prefix will be removed.
layer name | option enabled | option disabled |
---|---|---|
radius/5px |
radius/5px |
5px |
size/8px |
size/8px |
8px |
breakpoint/md |
breakpoint/md |
md |
This option allows you to define custom prefixes for the tokens.
For styles: You can only define one prefix which will be added if the Include token prefixes in token name
is enabled.
For custom tokens: You can add multiple prefixes in a comma separated list e.g. radii,radius
. If Include token prefixes in token name
is enabled whichever prefix is used in the name of a token will be kept if you have radius/5px
and radii/sm
you will also get radius/5px
and radii/sm
in the json output.
This option allows you to toggle the json compression for file export. When enabled the json file will be minified meaning whitespace and linebreaks will be removed.
You can define the default filename that will be used when exporting the tokens to a json file.
You can choose which types of tokens to export to a file. This can be helpful when debugging your tokens. By default all types are selected and thus all tokens will be exported.
If you which to ignore specific styles, use the exclude prefix.
When a server url
is specified, the command Send Design Tokens to Url
will send a POST
request to the provided url.
The body of the request will look like the following:
"event_type": "update-tokens", // or any string you defined
"client_payload": {
"tokens": "{...}", // the stringified json object holding all your desing tokens
"filename": "Design Tokens", // the Figma file name from which the tokens were exported
"commitMessage": "Your commit message"
}
This option allows you to toggle the json compression for the export to a server. When enabled the json that is end to the server will be minified meaning whitespace and linebreaks will be removed.
This is the event_type
property that is send in the body of the request with the client_payload
.
The url the post request is send to. This must be SSL secured (using https
) as Figma is a secure environment and thus does not allow non-secure requests.
A limitation that comes with Figma is that the server must allow access from any origin and send the following header: Access-Control-Allow-Origin: *
Overrides the content type header for the final HTTP request. Defaults to "plain/text"
If you push to github the server url must be in the format
https://api.github.com/repos/:username/:repo/dispatches
For the repositiory lukasoppermann/design-token-transformer
this would be:
https://api.github.com/repos/lukasoppermann/design-token-transformer/dispatches
This defines the authentication method used with the access token. The current choices are:
token
(used for github)gitlab_token
(used for Gitlab requests)bearer
tokenbasic
auth
The token send using the authentication method defined above. Learn more about creating a personal access token for github.
You can use this feature to integrate tokens into your build pipeline. The ideal is to send tokens from Figma to a repository and automatically transform them. Depending on your setup you could either trigger a webhook on your product repos, create a new semversion on the tokens repo or notify the dev teams in another way.
To learn how to set this up using github
and actions
check out the documentation and code examples in the design token transformer repositry.
This will set up the plugin to trigger a Gitlab pipeline passing in the variables directly as environment variables. This data flow is documented in the section Pass CI/CD variables in the API call in the Gitlab "Triggers" documentation.
Once the pipeline is triggered the following values will be available as environment variables:
FIGMA_EVENT_TYPE
: The provided event type string.FIGMA_CLIENT_PAYLOAD_TOKENS
: The generated tokens JSON string.FIGMA_CLIENT_PAYLOAD_FILENAME
: The filename for the original Figma file.
⚠️ NOTE: It has been found that Gitlab has limitations on how much data can be passed via the environmental variables due to the limit on the size of the ConfigMap at 1048576 bytes. Depending on the system you are running on and any configurations already in place you may find you are able to pass more or less data than others. Developers and Designers should be aware of this limitation and plan accordingly. The below warning is an indication you have exceeded the data limit:ERROR: Error cleaning up configmap: resource name may not be empty ERROR: Job failed (system failure): prepare environment: setting up scripts configMap: generating scripts config map: ConfigMap "[[redacted image name]]" is invalid: []: Too long: must have at most 1048576 bytes. Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading for more information
This field is only used when the "gitlab_token" auth header has been selected. This field sets the reference for the Gitlab trigger. This can be a branch, or tag name.
There a different possible reasons for this to occur:
- Tokens are not placed inside a frame named
_tokens
- Tokens are nested in groups or frames (they must be the first level children of the
_tokens
frame) - You may have changed the
exclude prefix
setting tofalse
which means only styles that include the prefix e.g._colors/blue
are exported
You may be using a wrong access token or the access token is missing the correct permission (public_repo
).
You may be using a wrong server url
or auth type
.
Also assure your access token is valid.
The server may not have correct cors settings. If you send your tokens to github this probably means that you have a spelling mistake in the URL.
If you would like to see a specific feature implemented, please create an issue including a description of the feature and a use case.
If you can build the feature yourself and send a PR, this is even better. Please still create an issue first and mention that you want to implement it. I will get back to you asap to discuss the details of how to implement it.
If you are interested in helping please comment on any issue you would like to take on. I will get back to you to discuss how to implement it.