Figma Tokens Engine

Transform design tokens in Figma into usable styles

The Figma Token Engine is a project dependency that transforms design tokens (either as Figma Styles of from Token Studio into CSS styles using token-transformer and style-dictionary.

The Figma Token Engine (FTE) requires two files which can be created using npx figma-token-engine --init.

The two files helps the FTE to access the Figma API and to know where to find and save the files you need.

First, .tokens.config.json has the custom configuration of the FTE pipeline:

{
  "tokenFormat": "FigmaVariable",
  "inputFile": "./tokens-studio.json",
  "outputDir": "./src/styles/tokens",
  "platforms": [
    "css",
    "scss",
    "scssMap",
    "less",
    "js",
    "ts",
    "json",
    "compose"
  ]
}

Secondly, the .env exposes sensitive data we might not want to have in our repository such as the Figma API Key and the Figma file which we are pulling data from.

# Your personal Figma Personal Access token https://www.figma.com/developers/api#access-tokens
FIGMA_PERSONAL_ACCESS_TOKEN=""

# URL of the Figma file with the design tokens
FIGMA_FILE_URL=""

You can also check out the more practical Quick Guide at Medium

Install Figma Token Engine to your project:

npm i figma-token-engine

Generate .env anc config files:

npx figma-token-engine --init

Add your Figma API KEY, Document URL and configuration to the .env file and the .tokens.config.json files.

Run the token engine using npm scripts:

{
  ...
  "scripts": {
    "token-engine:fetch": "figma-token-engine",
  },
}

• figma-token-engine TOKEN_CONFIG_FILENAME A single flagless param will specify a custom .tokens.config.json file to read the FTE configuration from.

• --init: Create necessary environment files (.env, .tokens.config.json) to run the token engine with example content.

• --sd-config-file SD_CONFIG_FILENAME: Location of a StyleDictionary configuration file to merge with the one FTE uses. This can be used to extend platforms, filters, tokens location, etc.

  Example of a config file:

  As an js module

  module.exports = {
    "platforms": {
      "swift": {
        "transformGroup": "ios-swift",
        "buildPath": "./ios/",
        "files": [
          {
            "destination": "ios",
            "format": "ios-swift/enum.swift",
            "options": {
              "fileHeader": () => ["This is a custom header"]
            }
          }
        ]
      },
      "android": {
        "transformGroup": "android",
        "files": [
          {
            "destination": "android",
            "format": 'android/resources',
            "options": {
              "fileHeader": () => ["This is a custom header"]
            }
          }
        ]
      }
    }
  }

  As a JSON:

  {
    "platforms": {
      "swift": {
        "transformGroup": "ios-swift",
        "buildPath": "./ios/",
        "files": [
          {
            "destination": "ios",
            "format": "ios-swift/enum.swift",
            "options": {
              "fileHeader": "This is a custom header"
            }
          }
        ]
      },
      "android": {
        "transformGroup": "android",
        "files": [
          {
            "destination": "android",
            "format": "android/resources",
          }
        ]
      }
    }
  }

  The custom configuration file will have priority over FTE's configuration, however some fields will be appended, rather than overwritten:

  • Sources will be appended. StyleDictionary will still fetch the source specified in the .tokens.config.json
  • Parsers will be appended. StyleDictionary will still run FTE's parsers
  • Platforms will be appended and extended. FTE's premade platforms will still be configured. Custom configruation can add platforms or overwrite them, if specified. Also, FTE's buildPath (from the .tokens.config.json) and fileHeader will be added if not specified.
  • All other settings are added without modifications

TODO: Complete architecutre documentation of the pipeline

Go to architecture

First follow the instructions detailed in "How To Use". Then, we will create a fresh React app and will init the Figma Token Engine.

npx create-react-app@latest app-react
cd app-react
npx figma-token-engine --init

This will create or update two files: .tokens.config.json and .env, which are required for the tool to work. Add the required information in both files to continue.

If you added the FIGMA_PERSONAL_ACCESS_TOKEN and FIGMA_FILE_URL you can fetch the tokens into the inputFile file defined at the token file config .tokens.config.json.

npx figma-token-engine

More detailed guide: Quick Guide at Medium

To start development of this tool, you need to take into account two thigs: The shell interaction happens in the file bin/fte.js while the rest of the project is a Typescript Node Tool.

Simple development environment:

npm run dev

Development environment with API Fetch:

npm run dev:api

Development environment of the init option:

npm run dev:init

Contributions will open after the alpha release of this stack. Contact us if you have any questions.

• daniel.casado - GitHub (Sr. Design Technologist at frog)
• jose.lugo - GitHub (Associate Technology Director at frog)