Figma Token Engine: Quick Start
Practical guide to configure and use the FTE
At the end of February 2023, I finally made public a tool that has helped me and my team to develop and mantain components and Design System: the Figma Token Engine
I write this Quick Start to show how to install, configure and use the FTE. It will make it easier for you to include FTE on your workflow and help you boost your productivity and connectivity with tokens.
We’ll follow these steps:
- Create a Figma file with the tokens we’ll read from (both as Figma Styles and Tokens Studio).
- Create a React App which will be using the tokens.
- Install and configure the FTE.
- Run the FTE to import the tokens in both formats.
What is a Figma Token Engine (FTE) (and why?)
But before we get our hands dirty, a bit of context. FTE is a tool we developed to create an automatic communication channel between design decisions (represented as design tokens) and code. The main objective of the tool is to simplify the standarization and update of these decisions throughout all the digital products sharing a Design System.
On a high level, the FTE fetches design tokens from Figma through the Figma API (either represented as Figma Styles or as tokens on Jan Six’s Tokens Studio plugin) and transforms them to usable code (css, js, JSON, etc.) using Amazon’s StyleDictionary.
Tokens and app setup
Figma File (Styles)
To make things easier, let’s start with a template that already has a lot of the data and structure we’ll use. The Figmagic template is a good starting point, which actually was a big inspiration for the starting stages of FTE:
This file already has a lot of Figma Styles defined on it, that we’ll be reading as our tokens.
In order for the styles to be available on the Figma API, we need to publish them as a library:
- On the left side bar, click on Assets
- Click on the Book icon just bellow the Tabs
- On the modal that pops-up, click on Publish
4. And then select the styles and click on Publish Styles
Token File (Tokens Studio)
We’ll also configure tokens on Token Studio, using the same styles values:
- Install the plugin on Figma and open it. Click on “New empty file”.
- On the left side of the plugin window, click on Styles > Import Styles
- On the popup, make sure all the checkbox are selected and click “Import”
- And finally on “Create all” on the next popup
React app
Next, we’ll setup the “client” of the FTE, which will be using the tokens. Again, to mantain this setup simple I’ll use a fresh create-react-app as the “client” of FTE:
npx create-react-app fte-client
We’re going to style this page using tokens imported by the FTE.
How to install and configure
Now that we have all our pre requisites in order, we can start using the Figma Token Engine.
FTE is published as an npm script package and can be easily added as a package dev dependency on any npm project.
npm install --save-dev figma-token-engine
The FTE offers an option to create examples of all necessary configuration files:
npx figma-token-engine --init
This creates a .tokens.config.json file:
{
"tokenFormat": "TokensStudio",
"figmaFileId": "",
"inputFile": "./tokens.json",
"outputDir": "./src/styles/tokens",
"platforms": [
"css",
"cssAutocomplete",
"scss",
"scssMap",
"less",
"js",
"ts",
"json"
]
}
And a .env file:
# Added by Figma Token Engine
FIGMA_PERSONAL_ACCESS_TOKEN="" # Your personal Figma Personal Access token https://www.figma.com/developers/api#access-tokens
FIGMA_FILE_URL="" # URL of the Figma file with the tokens
On this .env file, we add our Figma Access Token (get one here) and the URL for our token file (you can get it from the Share button). Resulting in something like this:
# Added by Figma Token Engine
FIGMA_PERSONAL_ACCESS_TOKEN="figd_BRlmjAxL_s33r3phpZdrdsFAKejXK42n34fyAjUA" # Not my actual token ;)
FIGMA_FILE_URL="https://www.figma.com/file/iyeLeVwSzMBna7ix21E7i7/Figmagic-%E2%80%94-FTE-guide?node-id=2605%3A12&t=4mFCtwnYBsHU2w2D-1"
With this we are ready to use the FTE.
Running the FTE
Figma Styles
To set the FTE to read the Figma Styles, update the field tokenFormat on .tokens.config.json to “FigmaStyles”:
{
"tokenFormat": "FigmaStyles",
"figmaFileId": "",
"inputFile": "./tokens.json",
"outputDir": "./src/styles/tokens",
....
}
And we simply run the engine by calling:
npx figma-token-engine
This will fetch the styles from the Figma file, transform them to the specified formats (the platforms on the config file):
/$$$$$$$$ /$$
|__ $$__/ | $$
| $$ /$$$$$$ | $$ /$$ /$$$$$$ /$$$$$$$
| $$ /$$__ $$| $$ /$$/ /$$__ $$| $$__ $$
| $$ | $$ \ $$| $$$$$$/ | $$$$$$$$| $$ \ $$
| $$ | $$ | $$| $$_ $$ | $$_____/| $$ | $$
| $$ | $$$$$$/| $$ \ $$| $$$$$$$| $$ | $$
|__/ \______/ |__/ \__/ \_______/|__/ |__/
/$$$$$$$$ /$$
| $$_____/ |__/
| $$ /$$$$$$$ /$$$$$$ /$$ /$$$$$$$ /$$$$$$
| $$$$$ | $$__ $$ /$$__ $$| $$| $$__ $$ /$$__ $$
| $$__/ | $$ \ $$| $$ \ $$| $$| $$ \ $$| $$$$$$$$
| $$ | $$ | $$| $$ | $$| $$| $$ | $$| $$_____/
| $$$$$$$$| $$ | $$| $$$$$$$| $$| $$ | $$| $$$$$$$
|________/|__/ |__/ \____ $$|__/|__/ |__/ \_______/
/$$ \ $$
| $$$$$$/
\______/
______ __ ______
/ __ |/ | / __ |
_ _ ____ ____ | | //| /_/ || | //| |
| | | / _ )/ ___) | |// | | | || |// | |
\ V ( (/ /| |_ | /__| | | || /__| |
\_/ \____)_(_) \_____(_)|_(_)_____/
[13:27:48.485 - Event] Start Figma Token Engine
[13:27:48.485 - Event] Figma Styles
[13:27:48.486 - Event] Figma API - Get Figma API Credentials
✅ FIGMA_PERSONAL_ACCESS_TOKEN in .env
✅ FIGMA_FILE_URL in .env
[13:27:48.486 - Event] Figma API - Get Figma File Plugin Data
🌏 Fetch Figma API
[13:27:49.985 - Event] Figma API - Write Figma API Tokens Export
✅ Saved tokens at /Users/josedanielcasado/CompanyRestricted/dls-ops-offline/repos/fte-client/tokens-studio.json
[13:27:49.986 - Event] Style Dictionary
css
✔︎ ./src/styles/tokens/tokens.css
cssAutocomplete
✔︎ ./src/styles/tokens/tokens-autocomplete-config.json
scss
✔︎ ./src/styles/tokens/tokens.scss
scssMap
✔︎ ./src/styles/tokens/tokensMap.scss
less
✔︎ ./src/styles/tokens/tokens.less
js
✔︎ ./src/styles/tokens/tokens.js
ts
✔︎ ./src/styles/tokens/tokens.ts
json
✔︎ ./src/styles/tokens/tokens.json
Each of these files have the styles from the figma file as tokens on different languages and formats. For example, the scss contains:
// File generated by the Figma Token Engine
// Do not edit directly
$shadow-soft: (0rem 0rem 0.3125rem 0rem #c4c4c4ff);
$shadow-deep: (0.1875rem 0.1875rem 0.1875rem 0rem #c4c4c4bf);
$white: #ffffffff;
$yellow: #f2c94cff;
$shadow-medium: (0rem 0rem 0.3125rem 0rem #00000080);
$gray-1: #4f4f4fff;
$black: #333333ff;
$orange: #f2994aff;
....
The names of the variables are created from the names of the styles in Figma.
Reading Tokens Studio
To read this tokens just change the field tokenFormat on .tokens.config.json to “TokensStudio”:
{
"tokenFormat": "TokensStudio",
"figmaFileId": "",
"inputFile": "./tokens.json",
"outputDir": "./src/styles/tokens",
....
}
And run the engine again:
npx figma-token-engine
Because we imported the tokens from the styles, these will be the same tokens, but now managed from Tokens Studio. You can add border and dimension tokens to see how those are exported!
Using the tokens in the App
As we can see, the tokens got generated inside our src/ directory, and are ready to use on our React page.
We can go to App.css and import the generated css file and use its variables across our page:
@import "./styles/tokens/tokens.css";
...
.App-header {
background-color: var(--blue-1); /* token */
min-height: 100vh;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
font-size: calc(10px + 2vmin);
color: var(--white); /* token */
font-size: var(--heading-l-font-size); /* token */
font-family: var(--heading-l-font-family); /* token */
}
.App-link {
color: var(--yellow); /* token */
font-size: var(--heading-s-font-size); /* token */
}
....
With this setup, we can update the color styles on Figma, republish them, run FTE again and our app will be updated automatically:
If we are reading the tokens from Tokens Studio, we can also update the tokens live, rerun the engine and we’ll see those changes propagated to the code.
The next video showcases a more involved tokenized component using the a lil-bit more complex “example” tokens that Tokens Studio provides:
Additional notes
Because FTE is a npm script, you can add them to commands on your package.json and add them to more involved pipelines and other things:
{
"name": "fte-client",
"version": "1.0.0",
"scripts": {
"prestart": "figma-token-engine",
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}
Quick Guide written by Daniel Casado, Sr Frontend developer at frog.co MX studio