TokensBrücke — Figma plugin

What is this plugin for?

The plugin converts Figma variables into design-tokens JSON that are compatible with the latest Design Tokens specification.

How to use

Install the plugin from the Figma Community.
Make sure you have variables in your Figma file.
Run the plugin.
Adjust the settings.
Then you can download the JSON file or push it to on of the supported services.

Export and Import

The plugin supports both exporting and importing design tokens:

Export (Variables → JSON)

Click "Download JSON" to export your Figma variables as a design tokens JSON file
The exported file is compatible with the Design Tokens specification
You can also push directly to supported services (JSONBin, GitHub, GitLab, etc.)
The exported tokens can be converted into CSS, JS, and other platform formats using tools like Terrazzo or Style Dictionary

Import (JSON → Variables)

Click "Import JSON" to import design tokens from a JSON file back into Figma
The plugin will create variable collections, modes, and variables based on the JSON structure
Supports both DTCG format ($value, $type) and standard format (value, type)
Handles alias references between variables
Creates new collections and variables as needed, or updates existing ones

Import Features:

✅ Creates variable collections from top-level objects
✅ Supports multiple modes (from $extensions.mode or extensions.mode)
✅ Handles all variable types (color, number, string, boolean)
✅ Resolves alias references between variables
✅ Supports various color formats (HEX, RGBA CSS, RGBA Object)
✅ Preserves variable descriptions and metadata

Warning

Styles Export Limitation: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles or variables. Figma's variable API currently only supports basic types: color, number, string, boolean, and dimension. Complex style types will be imported as STRING variables without proper value conversion. This is a temporary limitation until Figma supports these types natively in their API.

General settings

Color mode

Allows you to choose the color mode for the generated JSON. Default value is HEX. The plugin supports the following color modes:

HEX — HEX color format. Could be converted into HEXA if the color has an alpha channel.
RGBA CSS — RGBA color format in CSS syntax, e.g. rgba(0, 0, 0, 0.5). When alpha is 1, the output is rgb(r, g, b) (no alpha channel).
RGBA Object — RGBA color format in object syntax, e.g. { r: 0, g: 0, b: 0, a: 0.5 }.
HSLA CSS — HSLA color format in CSS syntax, e.g. hsla(0, 0%, 0%, 0.5).
HSLA Object — HSLA color format in object syntax, e.g. { h: 0, s: 0, l: 0, a: 0.5 }.

Include styles

Allows you to include styles into the generated JSON. See more about styles support in the Styles support section.

There is an option to rename each style's group and give it a custom name for better organization.

Add styles to

Allows you to choose where to put styles in the generated JSON. By default, the selected value is Keep separate. In this case styles will be added into the root of the JSON and will be treated as collections. There is also an option to add styles into the corresponding collection (fig.4).

Include variable scopes

Each Figma variable has a scope property. The plugin allows you to include scopes into the generated JSON. It will be included as an array of strings without any transformations.

{
  "button": {
    "background": {
      "type": "color",
      "value": "#000000",
      "scopes": ["ALL_SCOPES"]
    }
  }
}

Use percentage for opacity

Is off by default. When enabled, opacity values will be exported as percentages instead of normalized decimal values. This affects variables with the OPACITY scope.

// Without percentage format (default)
{
  "opacity": {
    "type": "number",
    "value": 0.1
  }
}

// With percentage format
{
  "opacity": {
    "type": "string",
    "value": "10%"
  }
}

Use DTCG keys format

Is off by default. Currently many design tokens tools doesn't support DTCG keys format. All DTCG keys are prefixed with $ symbol.

// Without DTCG keys format
{
  "button": {
    "background": {
      "type": "color",
      "value": "#000000"
    }
  }
}

// With DTCG keys format
{
  "button": {
    "background": {
      "$type": "color",
      "$value": "#000000",
    }
  }
}

Include `.value` string for aliases

Is off by default. Allows you to include .value string to the end of the path for aliases. It will be added to the alias string.

{
  "button": {
    "background": {
      "type": "color",
      "value": "{colors.light.primary.10.value}"
    }
  }
}

If the format is DTCG:

{
  "button": {
    "background": {
      "$type": "color",
      "$value": "{colors.light.primary.10.$value}"
    }
  }
}

Include Figma metadata

Is off by default. Allows you to include Figma metadata like variableId, codeSyntax, etc. into the generated JSON. It is merged into the existing $extensions object alongside mode.

"button": {
  "background": {
    "type": "color",
    "value": "{colors.primary.10}",
    "$extensions": {
      "mode": {
        "light": "{colors.primary.10}",
        "dark": "{colors.primary.90}"
      },
      "figma": {
        "codeSyntax": {},
        "variableId": "VariableID:1:4",
        "collection": {
          "id": "VariableCollectionId:1:3",
          "name": "Primitives",
          "defaultModeId": "1:0"
        }
      }
    }
  }
}

Split collections into separate files

Is off by default. When enabled, each Figma variable collection is exported as its own file instead of a single merged JSON.

Download JSON — produces a design.tokens.zip archive containing one {CollectionName}.tokens.json per collection.
CLI — writes individual {CollectionName}.tokens.json files into the directory specified by --output.

This is useful when you want to keep component-level token files separate (e.g. button.tokens.json, card.tokens.json).

Omit collection names

Is off by default. When enabled, the plugin drops the top-level collection name from the output and merges all variables into a single flat namespace (variables are still grouped by the / separator in their names).

// Without "Omit collection names" (default)
{
  "Primitives": {
    "color": {
      "primary": { "type": "color", "value": "#000000" }
    }
  },
  "Semantic": {
    "button": {
      "background": { "type": "color", "value": "{color.primary}" }
    }
  }
}

// With "Omit collection names"
{
  "color": {
    "primary": { "type": "color", "value": "#000000" }
  },
  "button": {
    "background": { "type": "color", "value": "{color.primary}" }
  }
}

Alias references are also rewritten so they point to the flat path (the collection prefix is removed).

Warning

If two variables in different collections share the same name, the last one wins and a collision warning is logged to the console. Rename conflicting variables (or keep this option off) to avoid losing values.

Use as cli tool

Warning

⚠️ You need a Figma Enterprise plan to use the Figma REST API for variables.

Installation

To install the CLI globally, run:

pnpm add -g tokens-bruecke
#or npm install -g tokens-bruecke

This will make the tokens-bruecke command available globally on your system.

Usage

After installation, you can run the CLI tool using:

tokens-bruecke [options]

For example:

# Using a Personal Access Token (PAT)
tokens-bruecke --api-key $FIGMA_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json

# Using an OAuth token
tokens-bruecke --oauth-token $FIGMA_OAUTH_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json

This will fetch figma variables and export them in out/tokens.json

Options

Option	Alias	Description	Required
`--api-key`	`-a`	Figma personal access token (PAT)	One of `--api-key` or `--oauth-token` is required
`--oauth-token`	`-t`	Figma OAuth token	One of `--api-key` or `--oauth-token` is required
`--file-key`	`-f`	Figma file key	Yes
`--output`	`-o`	Path to output file, or output directory when `--split-by-collection`	Yes
`--config`	`-c`	Path to configuration file	No
`--split-by-collection`	`-s`	Write each collection as a separate `.tokens.json` file in `--output`	No
`--omit-collection-names`		Drop top-level collection names and merge all variables into one flat namespace	No

Tip

For automated pipelines, --oauth-token is preferred over --api-key. Personal Access Tokens expire every 90 days and require manual renewal, while OAuth tokens support programmatic refresh for indefinite access.

Other export settings are available through a JSON configuration file (see CLI Configuration File below).

CLI Configuration File

You can use a JSON configuration file to specify the export options for the CLI.

{
  "includedStyles": {
    "text": { "isIncluded": true, "customName": "typography" },
    "effects": { "isIncluded": false, "customName": "effects" },
    "grids": { "isIncluded": false, "customName": "grids" },
    "colors": { "isIncluded": false, "customName": "colors" }
  },
  "includeScopes": true,
  "useDTCGKeys": false,
  "includeValueStringKeyToAlias": true,
  "includeFigmaMetaData": false, // Include Figma metadata like styleId, variableId, etc.
  "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
  "colorMode": "hex", // "hex"  | "rgba-object"  | "rgba-css"  | "hsla-object"  | "hsla-css";
  "storeStyleInCollection": "none", // Name of one of your collection or "none" to keep them separated
  "splitByCollection": false, // Write each collection as a separate .tokens.json file
  "omitCollectionNames": false // Drop top-level collection names and merge all variables into one flat namespace
}

Save this JSON file and pass it to the CLI using the --config option:

Push to server

With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports JSONBin, GitHub and custom servers.

If you connected multiple servers, the plugin will try to push the tokens to all of them one by one. In ordere to test if your credentials are valid you can make a test request by clicking the Push to server button (fig.6).

JSONBin

Open JSONBin and create an account.
Generate a new API key.
If you want to use an existing bin, copy its ID. Otherwise just leave the ID field empty in the plugin settings.
Add a name for the bin.

GitHub

You need to create a personal access token with repo scope.
In the plugin settings paste the token into the Personal access token field.
Add an owner name, repository name and a branch name.
In the file name field you can specify a path to the file. If the file doesn't exist, it will be created. If the file exists, it will be overwritten. File name should include the file extension, e.g. tokens.json.
You can also specify a commit message.

GitHub PR

All the steps are the same as for the GitHub server, except the last two.

PR title. You can specify a title for the PR. If you leave it empty, the plugin will use chore(tokens): update tokens as a default title.
PR body. You can specify a body for the PR. If you leave it empty, the plugin won't add any body to the PR.

GitLab

You need to create a project access token with api scope.
In the plugin settings paste the token into the Project access token field.
Add an owner name, repository name and a branch name.
In the file name field you can specify a path to the file. If the file doesn't exist, it will be created. If the file exists, it will be overwritten. File name should include the file extension, e.g. tokens.json. 5. You can also specify a commit message.

Custom server

There is a possibilty to connect a custom server. In order to do that you need to specify a URL, a method (by default it's POST) and headers.

Show output

If you want to see the generated JSON, you can enable the Show output option. The plugin will show the JSON in the sidebar. The output doesn't update automatically, in order to optimize the performance. So, if you want to see the updated JSON, you need to click the Update button.

Plugin window height

The plugin window auto-fits the height of its content, but you can adjust it manually using the resizer handle at the bottom of the settings view.

Drag the handle up or down to set a custom height. The minimum is 360px and the maximum is the current content height — you can't grow the window beyond what's actually there.
Double-click the handle to reset back to auto-fit. The window snaps to match the content height again.
Your manual height is preserved while the output preview is open, so you can resize both with and without the preview showing.

Config autosaving

The plugin saves the config automatically. So, you don't need to set it up every time you run the plugin.

Styles support

The plugin can support some styles and effects too. Until Figma will support all the styles and effects, the plugin will convert them into the corresponding design tokens types. But it's not a backward compatibility, it's a temporary solution until Figma will support all the styles and effects as variables.

Supported styles:

Typography
Colors
Grids
Shadows (including inset shadows)
Blur (including background and layer blur)

Typography

"extralight": {
  "type": "typography",
  "value": {
    "fontFamily": "Inter",
    "fontWeight": 400,
    "fontSize": "18px",
    "lineHeight": "28px",
    "letterSpacing": "0%"
  },
  "description": "",
  "extensions": {
    "styleId": "S:0ffe98ad785a13839980113831d5fbaf21724594,"
  }
}

Colors

The plugin supports solid colors and gradients (linear, radial, angular, diamond). Color styles are converted to DTCG format with support for variable aliases.

// Solid color
"primary": {
  "type": "color",
  "value": "#ff0000"
}

// Solid color with variable alias
"secondary": {
  "type": "color",
  "value": "{colors.base.primary}"
}

// Gradient
"skeleton-ramp": {
  "type": "gradient",
  "value": [
    {
      "color": "{clr.scale.ntrl.80}",
      "position": 0
    },
    {
      "color": "{clr.scale.ntrl.95}",
      "position": 0.5
    },
    {
      "color": "#eae9e8",
      "position": 1
    }
  ]
}

Grids

In Figma you can add as many grids in the style as you want. But the plugin will take only first two grids and treat the first one as column grid and the second one as row grid.

// Column grid
"1024": {
  "type": "grid",
  "value": {
    "columnCount": 12,
    "columnGap": "20px",
    "columnMargin": "40px"
  }
}

// Row grid
"1024": {
  "type": "grid",
  "value": {
    "rowCount": 12,
    "rowGap": "20px",
    "rowMargin": "40px"
  }
}

// Both grids
"1024": {
  "type": "grid",
  "value": {
    "columnCount": 12,
    "columnGap": "20px",
    "columnMargin": "40px",
    "rowCount": 12,
    "rowGap": "20px",
    "rowMargin": "40px"
  }
}

Shadows

The plugin supports drop-shadow and inner-shadow effects. If the effect is inner-shadow, the plugin will set the inset property to true.

"xl": {
  "type": "shadow",
  "value": {
    "inset": false,
    "color": "#0000000a",
    "offsetX": "0px",
    "offsetY": "10px",
    "blur": "10px",
    "spread": "-5px"
  }
}

Blur

The plugin supports background and layer blur effects. In order to distinguish between them, the plugin adds the role property to the generated JSON.

// Background blur
"sm": {
  "type": "blur",
  "value": {
    "role": "background",
    "blur": "4px"
  }
}

// Layer blur
"md": {
  "type": "blur",
  "value": {
    "role": "layer",
    "blur": "12px"
  }
}

Multiple `Shadow` and `Blur` styles support

If the style has multiple Shadow or Blur styles, the plugin will add them into the array.

"new-sh": {
  "$type": "shadow",
  "$value": [
    {
      "inset": false,
      "color": "#e4505040",
      "offsetX": "0px",
      "offsetY": "4px",
      "blur": "54px",
      "spread": "0px"
    },
    {
      "inset": false,
      "color": "#5b75ff40",
      "offsetX": "0px",
      "offsetY": "4px",
      "blur": "24px",
      "spread": "0px"
    },
    {
      "inset": false,
      "color": "#00000040",
      "offsetX": "0px",
      "offsetY": "4px",
      "blur": "4px",
      "spread": "0px"
    }
  ]
}

Tokens structure

Plugin first takes the collection name, then the group and then the variable name (fig.1). Mode variables will be wrapped under the $extensions objects

For example, if you have a collection named clr-theme, mode named light and variable named dark, the plugin will generate the following JSON:

"clr-theme": {
  "container-outline/mid": {
    "type": "color",
    "value": "{clr-core.ntrl.40}",
    "description": "",
    "$extensions": {
      "mode": {
        "light": "{clr-core.ntrl.40}",
        "dark": "{clr-core.ntrl.55}"
      }
    }
  }
}
,

Figma automatically merges groups and their names into a single name, e.g. Base/Primary/10 (fig.2). In this case, the plugin will generate the following JSON:

{
  "base": {
    "primary": {
      "10": {
        "type": "color",
        "value": "#000000"
      }
    }
  }
}

Aliases handling

All aliases are converted into the alias string format from the Design Tokens specification.

{
  "button": {
    "background": {
      "type": "color",
      "value": "{colors.primary.10}"
    }
  }
}

Include `.value` string for aliases

You can switch on the Include .value string for aliases option in the plugin settings.

Handle variables from another file

Imagine you have a library from another file with "base" variables. And you use this variables in your current file.

The plugin will generate the alias name anyway, but it will be a path to the variable as if it was in the current file.

{
  "button": {
    "background": {
      "type": "color",
      "value": "{colors.primary.10}"
    }
  }
}

The plugin wouldn't include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files.

So you will need to merge the file with the base variables from one file with another where you use them. Otherwise tools like Style Dictionary wouldn't be able to resolve the aliases.

Handle modes

If there is only one mode — the plugin wouldn't include it in a generated JSON. If there are multiple modes, the plugin will place them under the $extensions objects.

It follows the same pattern as used by Cobalt

Variables types conversion

Unlike design tokens, Figma variables now support only 4 types — COLOR, BOOLEAN, FLOAT and STRING. So, the plugin converts them into the corresponding types from the Design Tokens specification.

Figma type	Scope condition	Design Tokens type
COLOR	—	color
BOOLEAN	—	boolean *
FLOAT	`FONT_WEIGHT` scope	string *
FLOAT	`OPACITY` scope (no %)	number *
FLOAT	`OPACITY` scope (with %)	string (e.g. `"10%"`) *
FLOAT	all other scopes	dimension **
STRING	—	string *

* native JSON types. The specification doesn't restrict the type of the value, so it could be any JSON type. Also see this issue.

** Figma currently supports only FLOAT for numeric values used as dimensions, which map to px units. The plugin appends px to produce a valid dimension token.

Design tokens types

In order to validate types, the plugin uses the Design Tokens types.

Scopes lemitations

In order to convert FONT-WEIGHT and OPACITY types into valid values you should specify thme as scopes in the Figma variables. The plugin will read the first scope and convert it into the valid value. If there are multiple scopes, the plugin will take the first one.

FONT_WEIGHT scope will be converted into string type.
OPACITY scope will be converted into number type (or string with % if "Use percentage for opacity" is enabled).

Feedback

If you have any questions or suggestions, feel free to create an issue

Name		Name	Last commit message	Last commit date
Latest commit History 242 Commits
.github/workflows		.github/workflows
examples		examples
readme-assets		readme-assets
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
.prettierrc.yml		.prettierrc.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
declaration.d.ts		declaration.d.ts
global.d.ts		global.d.ts
manifest.json		manifest.json
package.json		package.json
plugin-types.d.ts		plugin-types.d.ts
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.cli.json		tsconfig.cli.json
tsconfig.json		tsconfig.json
tsconfig.plugin.json		tsconfig.plugin.json
webpack.config.cli.js		webpack.config.cli.js
webpack.config.js		webpack.config.js

Folders and files

Latest commit

History

Repository files navigation

TokensBrücke — Figma plugin

What is this plugin for?

Table of contents

How to use

Export and Import

Export (Variables → JSON)

Import (JSON → Variables)

General settings

Color mode

Include styles

Add styles to

Include variable scopes

Use percentage for opacity

Use DTCG keys format

Include .value string for aliases

Include Figma metadata

Split collections into separate files

Omit collection names

Use as cli tool

Installation

Usage

Options

CLI Configuration File

Push to server

JSONBin

GitHub

GitHub PR

GitLab

Custom server

Show output

Plugin window height

Config autosaving

Styles support

Typography

Colors

Grids

Shadows

Blur

Multiple Shadow and Blur styles support

Tokens structure

Aliases handling

Include .value string for aliases

Handle variables from another file

Handle modes

Variables types conversion

Design tokens types

Scopes lemitations

Feedback

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 40

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Include `.value` string for aliases

Multiple `Shadow` and `Blur` styles support

Include `.value` string for aliases

Packages