Theemo

Appearance

Figma Reader ​

Reads tokens from Figma and parses them into a unified format.

To start use figmaReader() from @theemo/figma. Here is a basic config as template:

theemo.config.js
js
import { figmaReader } from '@theemo/figma';
import { defineConfig } from '@theemo/cli';

const { FIGMA_SECRET } = process.env;

export default defineConfig({
  sync: {
    reader: {
      sources: figmaReader({
        secret: FIGMA_SECRET,

        files: ['<your-figma-file-id>'],

        parser: {
          // ...
        }
      })
    }
  }
});

Connecting to Figma ​

The figmaReader() is accessing your Figma file through their REST API, which requires an API Key. Go to your Figma settings and generate a new Personal Access Token.

Usage in Development ​

To use it in development, put your secret into a .env file:

sh
FIGMA_SECRET=

Theemo CLI will read from .env files.

Usage in Production ​

For production, add it as secure environment variable in your CI provider.

Enterprise Plan ​

For Figma users on an enterprise plan, you can request more information from the REST API over users with a lower tier plan, such as variables.

WARNING

At the time of Writing, I never had the chance to access such an endpoint, so support is not built-in.

Please refer to Issue #691

Files ​

It is possible to collect tokens across multiple files. Add all the file IDs you wish to sync from into the files array.

figmaReader will parse tokens from each file and then merge them together.

Plugins ​

As much as Figma supports plugins, the same applies to figmaReader(). Theemo in its basic usage does not rely on plugins. As Figma plugins are allowed to expose data through the Figma Rest API, you can write plugins, that consume this data to alter your tokens.

Theemo Plugin ​

When using the Theemo Plugin for Figma to export variables, you can use the Theemo plugin for figmaReader() as its counterpart to consume those variables.

js
import { figmaReader, theemoPlugin } from '@theemo/figma';
import { defineConfig } from '@theemo/cli';

export default defineConfig({
  sync: {
    reader: {
      sources: figmaReader({
        plugins: [
          theemoPlugin()
        ]
      })
    }
  }
});

Adding the plugin as shown above will make variables available in sync mode.

Write Your own Plugin ​

Whether you are a Figma Plugin author and want to provide the sync counterpart to your plugin or you are are in need to consume a third party Figma plugin, you can write your own plugin.

Parser ​

The heart of figmaReader() is the parser. The parser let's you read tokens from variables, styles and text nodes.

The flow for reading tokens from Figma is outlined here:

As per the flow graph above and in all others on this page. The green functions is where you can intersect the default behavior and apply custom logic.

That is all default behavior is exported (for those where it is available). So you can safely write your customizations and defer to the default implementation for all other situations. All examples in this page work follow this idea and showcase the default behavior.

Variables ​

Variables are the most atomic representation of design tokens in Figma. You can read them with the theemo plugin or enterprise plan. Here is the flow, how variables are parsed:

Customizations options:

API Reference

Styles ​

Styles are used for composite design tokens in Figma. Theemo reads every style through the Figma API, that exists in your files.

Customizations options:

API Reference

Text Nodes ​

Theemo is not only able to extract tokens from styles, but also from text nodes on the canvas itself.

WARNING

Theemo is older than Variables in Figma. Variables nowadays are a better fit and if you already use them, all good. Keep reading to support legacy systems.

Let's assume we use a modular scale system for our sizing, we only need base and ratio parameters for this.

Sizing in Figma

Figure 1 shows such a sizing configuration in Figma. Notice the [token] tags as suffix for the node names. This will serve as indicators to recognize such nodes as tokens in theemo.

Customizations options:

Reference

Classify Tokens ​

Variables, Styles and Text Nodes will create an internal FigmaToken. At the end of the process, FigmaTokens will be compiled into Tokens and the result of the reader is to return an array of Tokens which will be put into the lexer. In the last classification step, you have the chance to do some cleanup or pass any data along with the token that are relevant to your setup.

Customizations options: