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:

1. Create a Figma file with the tokens we’ll read from (both as Figma Styles and Tokens Studio).
2. Create a React App which will be using the tokens.
3. Install and configure the FTE.
4. 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:

Figmagic template on the Figma Community

This file already has a lot of Figma Styles defined on it, that we’ll be reading as our tokens.

Figma Styles on Figmagic template

In order for the styles to be available on the Figma API, we need to publish them as a library:

1. On the left side bar, click on Assets
2. Click on the Book icon just bellow the Tabs
3. On the modal that pops-up, click on Publish

Ordered steps to publish a library

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:

1. Install the plugin on Figma and open it. Click on “New empty file”.
2. On the left side of the plugin window, click on Styles > Import Styles
3. On the popup, make sure all the checkbox are selected and click “Import”
4. 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

React demo page

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 */
}

....

Using tokens imported with FTE

With this setup, we can update the color styles on Figma, republish them, run FTE again and our app will be updated automatically:

Live update of Figma Styles and tokens reimporting

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:

Tokens read and updated live from Token Studio

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