This is the full developer documentation for TokensBruecke # TokensBrücke > Export Figma variables and styles as design tokens compatible with the DTCG 2025.10 specification, and import tokens back into Figma. ## How to use 1. Install the plugin from the [Figma Community](https://www.figma.com/community/plugin/1254538877056388290). 2. Run the plugin in any Figma file and adjust the [settings](/plugin/settings/). 3. Download the JSON file or [push it to a server](/plugin/push-to-server/). A file without variables opens on an empty screen, where you can [import tokens](/getting-started/export-and-import/#import-json--variables) or continue to export styles only. New in v3.23 Run the plugin in [Dev Mode](/plugin/dev-mode/), and [share a profile in the file](/plugin/profiles/#shared-profiles) so developers export with your settings, without your credentials. ## One converter, three ways to run it Figma plugin Pick a color format, include styles, preview the output and download it or push it to GitHub, GitLab, JSONBin or your own server. CLI Export from the Figma REST API or a local snapshot in CI. Pure JSON on stdout for scripts and agents. Library Call `fetchTokens` and `convertTokens` from your own build pipeline, with no child process and no files on disk. Import Bring DTCG tokens back into Figma as variable collections, modes and aliases. ## Start here [Export and import](./getting-started/export-and-import/)What gets exported, and what to know before importing. [Plugin settings](./plugin/settings/)Color modes, styles, scopes, DTCG format and splitting files. [Shared profiles](./plugin/profiles/#shared-profiles)Share your export settings in the Figma file, without credentials. [Dev Mode](./plugin/dev-mode/)Let developers export tokens from Dev Mode and VS Code. [CLI overview](./cli/overview/)Install the CLI and run your first export. [Token structure](./reference/token-structure/)How collections, groups and modes map to JSON. # Export and import > Export Figma variables as DTCG tokens, or import tokens back into Figma variables. 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 [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/) * 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](https://terrazzo.app/docs/) or [Style Dictionary](https://amzn.github.io/style-dictionary/) ## Import (JSON → Variables) * Click **“Import tokens (Beta)”** to import design tokens from a JSON file back into Figma. The button is in the settings and on the “No variables found” screen. The import runs in Figma Design only, not in [Dev Mode](/plugin/dev-mode/) * 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 A file without variables opens on this screen, with the import button: **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, timing, easing) * ✅ Resolves alias references between variables * ✅ Supports these color formats: HEX, RGBA CSS, RGBA Object, DTCG color objects (`srgb-dtcg`, `hsl-dtcg`, `oklch-dtcg`, through their `hex` fallback) and [color aliases with opacity](/reference/aliases/#color-aliases-with-opacity). HSLA CSS and HSLA Object can’t be imported yet * ✅ Imports variable descriptions and `scopes`. Invalid scopes are reported, and scopes are skipped on `duration` and `cubicBezier` tokens. `$extensions.figma` (code syntax, variable IDs) is ignored * ✅ Imports `duration` and `cubicBezier` tokens as Figma motion variables (see [Motion variables](/reference/types/#motion-variables)) * ✅ Imports `fontFamily` and `fontWeight` tokens without `scopes` as new variables scoped to “Font family” and “Font weight”, so they keep their type on the next export. Existing variables keep their scopes. A `fontFamily` list keeps only its first family, since a string variable holds one **What to know before importing:** * Tokens without their own `$type` take it from the closest group, as DTCG allows; an alias without a type takes the type of the token it references. * Every top-level key becomes a collection. Files exported with [Omit collection names](/plugin/advanced-settings/#omit-collection-names) don’t map back to the original collections. * A file of a [split-by-mode export](/plugin/advanced-settings/#split-modes-into-separate-files) carries its mode in the meta, so its values go into that mode of the collection, which is added if it’s missing. Import the files one by one; the first one imported into a new collection becomes its default mode. * An existing collection’s first mode is renamed to the first mode in the tokens. * Units are dropped from dimensions, since Figma number variables have no unit: `1rem` imports as `1`. * Extended collections are imported as regular collections when they don’t exist in the file yet. If the extended collection exists, its tokens update the variables it inherits: the values become overrides for its modes. New variables and modes can’t be added to an extended collection, so those tokens are reported as errors. * An existing variable keeps its type. A token of another type, for example a `dimension` token for a color variable, is skipped and listed in the import result. Caution **Styles Export Limitation**: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles. Figma variables only have color, number, string and boolean types, plus timing and easing for motion. Solid color styles import as color variables. Typography, grid, shadow and blur tokens fall back to `STRING` variables, but their object values can’t be written, so they are reported as errors in the import result. # Settings > The settings in the main view of the plugin: color mode, styles and the DTCG format. The main view of the plugin holds the settings most exports need. Everything else is under [Advanced settings](https://github.com/tokens-bruecke/figma-plugin/blob/main/../advanced-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 }`. * `sRGB DTCG` — sRGB color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#srgb) * `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 }`. * `HSL DTCG` — HSL color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#hsl) * `OKLCH DTCG` — OKLCH color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#oklch) The DTCG color objects carry the opacity in `alpha` and a 6-digit `hex` fallback, as the specification requires. Older exports wrote an 8-digit `hex` for translucent colors; the import reads both. ## Include styles Allows you to include styles into the generated JSON. Text, effect, grid and color styles each have their own toggle, and all of them are `off` by default. See more about styles support in the [Styles support](/reference/styles/) section. There is an option to rename each style’s group and give it a custom name for better organization. ## Add styles to Shown once at least one style type is included. 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. If that collection isn’t in the export (for example in another file, or with [Omit collection names](/plugin/advanced-settings/#omit-collection-names)), the styles are kept separate. ## DTCG 2025.10 format Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/): * All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`). * Dimensions are exported as objects per [§8.2 Dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) — `{ "value": 6, "unit": "px" }` instead of `"6px"`. This also applies to sub-values in shadows, typography, and grids. * The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect. * A variable named like a group of other variables (`border/brand` next to `border/brand/subtle`) becomes the group’s root token per DTCG 2025.10 §6.2: `border.brand.$root`. References to it point at `{….border.brand.$root}`. With the format off, the token and the group share one object, as before. The import reads both shapes. ```json // Off — native Figma format { "button": { "background": { "type": "color", "value": "#000000" }, "height": { "type": "dimension", "value": "32px" } } } // On — DTCG 2025.10 format { "button": { "background": { "$type": "color", "$value": "#000000" }, "height": { "$type": "dimension", "$value": { "value": 32, "unit": "px" } } } } ``` Note Values that have no valid DTCG representation stay as strings even with this setting on: percentage-based `lineHeight`/`letterSpacing` (e.g. `"150%"`) and `"auto"` line height. `blur` and `grid` style tokens are exported with non-spec `$type` values as documented in [Styles support](/reference/styles/). # Advanced settings > Split files, omit collection names, scopes, opacity, easing, aliases and Figma metadata. Open **Advanced settings** in the main view for the settings that change the shape of the output. ## 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`. * **Push to a server** — the GitHub, GitHub PR, GitLab and GitLab MR servers commit one `{CollectionName}.tokens.json` per collection in a single commit. The `File name` field of the server becomes the folder they are written into, e.g. `tokens` → `tokens/{CollectionName}.tokens.json`. This is useful when you want to keep component-level token files separate (e.g. `button.tokens.json`, `card.tokens.json`). To push only some of the collections to a Git server, see [Collections to push](/plugin/push-to-server/#collections-to-push). ## Split modes into separate files Is `off` by default. When enabled, each mode of a variable collection is exported as its own file. The top-level key in each file is the collection name, and every token’s value is resolved for that mode. * **Download JSON** — produces a `design.tokens.zip` archive containing one `{CollectionName}/{ModeName}.tokens.json` per mode. * **CLI** — writes individual `{CollectionName}/{ModeName}.tokens.json` files into the directory specified by `--output`. * **Push to a server** — the GitHub, GitHub PR, GitLab and GitLab MR servers commit one `{CollectionName}/{ModeName}.tokens.json` per mode in a single commit, inside the folder set in the server’s `File name` field. Collections with a single mode are exported as a single `{CollectionName}.tokens.json` file. Splitting by mode needs the [DTCG 2025.10 format](/plugin/settings/#dtcg-202510-format) setting on. With it off, each collection is exported as a single file. For example, a collection `color` with modes `light` and `dark` produces `color/light.tokens.json` and `color/dark.tokens.json`: color/light.tokens.json ```json { "color": { "primary": { "$type": "color", "$value": "#ffffff" } } } // color/dark.tokens.json { "color": { "primary": { "$type": "color", "$value": "#000000" } } } ``` This is useful for generating a [resolver.json](https://www.designtokens.org/tr/drafts/resolver/) file that references per-mode token files. ## 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). ```json // 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, including the ones in styles, are also rewritten so they point to the flat path (the collection prefix is removed). Caution 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. ## Include variable scopes Is `off` by default. Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api/VariableScope). The plugin allows you to include scopes into the generated JSON. It will be included as an array of strings without any transformations. ```json { "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 number variables whose scopes are all `OPACITY` or `COLOR_OPACITY` (see [Scopes limitations](/reference/types/#scopes-limitations)). ```json // Without percentage format (default) { "opacity": { "type": "number", "value": 0.1 } } // With percentage format { "opacity": { "type": "string", "value": "10%" } } ``` ## Expand easing presets to cubic-bezier Is `on` by default. Figma’s `EASING` variables hold either a custom curve or one of Figma’s named presets, and the API only returns numbers for the custom ones — a preset arrives as just its name. When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and out and the three “back” variants) are expanded into their curve, so every bezier easing exports as a spec-valid `cubicBezier` token. When disabled, they keep the name Figma gave them. ```json // Expanded (default) { "easing": { "$type": "cubicBezier", "$value": [0.42, 0, 1, 1] } } // Not expanded { "easing": { "$type": "string", "$value": "ease-in", "$extensions": { "figmaType": "EASING" } } } ``` Custom beziers always export as `cubicBezier` and are unaffected by this setting. Spring presets (Gentle, Quick, Bouncy, Slow), custom springs and Hold are always exported as strings regardless of the setting — DTCG has no spring type, and Figma exposes no curve to expand a spring into. See [Motion variables](/reference/types/#motion-variables) for the full mapping. ## 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. ```json { "button": { "background": { "type": "color", "value": "{colors.light.primary.10.value}" } } } ``` If the format is `DTCG`: ```json { "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`. Exported styles get their `styleId` in `$extensions.figma`. Color styles also get every paint of the style in `$extensions.figma.paints`, see [color styles with several paints](/reference/styles/#color-styles-with-several-paints). Text styles keep their `$extensions.styleId` too, for compatibility. ```json "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" } } } } } ``` # Push to server > Push the generated tokens to JSONBin, GitHub, a GitHub pull request, GitLab, a GitLab merge request or your own server. With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports [JSONBin](https://jsonbin.io), [GitHub](https://github.com) (direct commit or pull request), [GitLab](https://gitlab.com) (direct commit or merge request) and custom servers. If you connected multiple servers, the plugin will try to push the tokens to all of them one by one. The server list shows where each one pushes to, e.g. `acme/tokens · main`; click a server to change its settings. Every field in a server form has a visible label. The ⓘ next to a label explains the field when you hover or focus it. Tokens and keys are masked; the eye in the field shows them. Optional fields such as the commit message are under **More options**. If you go back with unsaved changes, the form asks whether to save or discard them, and **Remove** at the bottom deletes the server’s settings and token from the profile after a confirmation. For GitHub, GitHub PR, GitLab and GitLab MR, **Test connection** checks the token, the repository and the branch with read-only requests, so you find a typo before the first push. A problem is shown at the field it belongs to. Otherwise, `Push to server` reports the result of each server in a toast. ## JSONBin 1. Open [JSONBin](https://jsonbin.io) and create an account. 2. Copy your **Master key** from the [API keys](https://jsonbin.io/app/app/api-keys) page into the `Master key` field. The plugin sends it as `X-Master-Key`, so an access key doesn’t work here. 3. Add a name for the bin. 4. Leave `Bin ID` empty to create a new bin on the first push. The plugin saves the new bin’s ID, so later pushes update the same bin. To use an existing bin, paste its ID. ## GitHub 1. Create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) with **Contents: Read and write** for the repository (a classic token with `repo` scope works too). The `Create token ↗` link in the form opens that page. 2. **Repository:** `owner/repository`, or paste the repository URL from your browser. A URL that points at a branch (`…/tree/develop`) fills in the branch too. 3. **Branch:** it must already exist. 4. **File path:** the path of the file in the repository, e.g. `tokens/design.tokens.json`. If the file doesn’t exist, it will be created. If the file exists, it will be overwritten. 5. **Personal access token:** paste the token. 6. Under **More options** you can set a commit message. It defaults to `Update tokens`. > **Splitting into several files.** If *Split collections into separate files* or *Split modes into separate files* is enabled in the advanced settings, the file path field is labelled **Folder** and every file is written into it in a single commit — e.g. `tokens` → `tokens/Colors.tokens.json`, or `tokens/Colors/Light.tokens.json` when splitting by mode. The ⓘ shows an example path. To leave some collections out of the push, see [Collections to push](#collections-to-push). ## GitHub PR Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a pull request. Repository, file path and token work the same as for the [GitHub](#github) server; the token also needs **Pull requests: Read and write**. The other fields: * **Base branch** (required). The branch the pull request targets, e.g. `main`. * **Pull request branch** (optional, under More options). The branch the tokens are committed to. Defaults to `tokens-bruecke/update-tokens`. It is reset to a new commit on top of the base branch on every push, so don’t commit anything else to it. The form doesn’t accept the base branch here. * **Pull request title** (optional). Defaults to `chore(tokens): update tokens`. * **Pull request description** (optional). If you leave it empty, the plugin won’t add a body to the PR. If a pull request from that branch is already open, the plugin updates it instead of opening a new one. After a push, the toast shows an **Open Pull Request** link. ## GitLab 1. You need a [project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/) with `api` scope. To push to a protected branch such as `main`, the token needs the Maintainer role; otherwise use the [GitLab MR](#gitlab-mr) server, which opens a merge request instead. Once the project is filled in, the `Create token ↗` link opens the project’s token settings. 2. **Project:** paste the project URL from your browser, e.g. `https://gitlab.acme.com/acme/frontend/design-system` for a self-managed GitLab, or write `group/project` for gitlab.com. Subgroups and the SSH clone URL work too, and a URL that points at a branch (`…/-/tree/develop`) fills in the branch. The ⓘ next to the label shows how the plugin read host and project. 3. **Branch:** it must already exist. 4. **File path:** the path of the file in the repository, e.g. `tokens/design.tokens.json`. If the file doesn’t exist, it will be created. If the file exists, it will be overwritten. 5. **Project access token:** paste the token. 6. Under **More options** you can set a commit message. It defaults to `Update tokens`. > **Splitting into several files.** If *Split collections into separate files* or *Split modes into separate files* is enabled in the advanced settings, the file path field is labelled **Folder** and every file is written into it in a single commit — e.g. `tokens` → `tokens/Colors.tokens.json`, or `tokens/Colors/Light.tokens.json` when splitting by mode. The ⓘ shows an example path. To leave some collections out of the push, see [Collections to push](#collections-to-push). ## GitLab MR Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a merge request. Use it when the target branch is protected or changes should be reviewed. Project and file path work the same as for the [GitLab](#gitlab) server. The other fields: * **Target branch** (required). The branch the merge request targets, e.g. `main`. It must already exist; it can stay protected. * **Project access token** (required). A token with `api` scope and at least the Developer role, which may push to the merge request branch and open merge requests. * **Merge request branch** (optional, under More options). The branch the tokens are committed to. Defaults to `tokens-bruecke/update-tokens`. It is created on the first push and reset to a new commit on top of the target branch on every push, so don’t commit anything else to it, and don’t protect it. The form doesn’t accept the target branch here. * **Commit message** (optional). Defaults to `Update tokens`. * **Merge request title** (optional). Defaults to `chore(tokens): update tokens`. * **Merge request description** (optional). If you leave it empty, the merge request has no description. If a merge request from that branch into the target branch is already open, the plugin updates it instead of opening a new one. After a push, the toast shows an **Open Merge Request** link. ## Collections to push While the tokens are [split into separate files](/plugin/advanced-settings/#split-collections-into-separate-files) and a GitHub, GitHub PR, GitLab or GitLab MR server is set up, a **Collections** row appears under the servers when the file has more than one collection. It lists the collections that are pushed; click it to check or uncheck them. All collections are checked by default, and a collection added to the file later is checked too. These servers only commit the files of the checked collections. The files of unchecked collections are not deleted: they stay in the repository as they are. This keeps a commit, pull request or merge request to the collections you changed. When some collections are unchecked, the push button says how many are pushed, e.g. **Push 2 of 3 collections**. The selection is saved in the profile. **Download JSON**, JSONBin, custom servers and the CLI always include every collection. With [Omit collection names](/plugin/advanced-settings/#omit-collection-names) on, the output has no collection groups, so the row is hidden and every file is pushed. ## Custom server There is a possibility to connect a custom server. In order to do that you need to specify an **Endpoint URL** starting with `https://` (or `http://`), a **Method** (`POST` or `PUT`, by default it’s `POST`) and optional **Headers**, written as a JSON object, e.g. `{"Authorization": "Bearer "}`. The form checks the URL and the headers when you leave the field. JSONBin and custom servers always receive the whole JSON in one request: the [split into separate files](/plugin/advanced-settings/#split-collections-into-separate-files) settings only apply to downloads, the CLI and the Git servers. # Profiles > Keep several export setups, and share a profile in the Figma file so everyone exports with the same settings. A profile holds a complete set of export settings and server configurations. Keep one per platform or repository, and share one in the Figma file so designers and developers export the same tokens. ## Multiple profiles Each profile stores its own settings, so you can switch between different setups without reconfiguring every time. The profile controls are in the header of the settings view: * **Profile dropdown** — shows the active profile. Click it to switch to another profile. * **`+` button** — creates a new profile. Enter a name and click **Create**. The new profile starts with default settings. * **`⋮` button** — opens the active profile, where you can rename, share or delete it. Switching profiles applies that profile’s export options and server credentials right away. The last remaining profile can’t be deleted. ## Shared profiles Profiles are stored on your machine. To hand your settings to others, for example developers in [Dev Mode](/plugin/dev-mode/), share the profile in the Figma file. 1. Open the profile with `⋮` and click **Share in this file**. 2. Everyone who runs the plugin on the file sees it in the profile dropdown under **Shared in this file**. Picking it creates a local copy. 3. Each person adds their own token in the [server settings](/plugin/push-to-server/) before they push. ### What is shared The profile is saved in the Figma file without any credentials: tokens, access keys, the Custom URL and its headers are removed, because webhook URLs often carry their secret in the URL. Everything else is shared, including repository, branch, file name and the Custom URL method. Each developer enters the Custom URL themselves; until then that server stays off. A server that only a newer plugin version knows is never shared. An older version doesn’t show it, and keeps it in your profile untouched. ### Keeping copies up to date When the shared profile changes, the local copy shows **Update**. Updating takes the settings from the file and keeps your credentials and profile name. Caution If an update points GitLab or GitLab MR to another host, its GitLab token is removed and the server is turned off, so a changed file can’t send your token somewhere else. Check the host and add the credential again. ### Changing or stopping a shared profile Open a shared profile with `⋮` to change it for everyone who uses the file: **Update shared profile** writes your current settings to the file, and **Stop sharing** removes it from the file. Local copies stay as they are. ## Config autosaving The plugin saves the config automatically, so you don’t need to set it up every time you run the plugin. # Output and window > Preview the generated JSON next to the settings, and set the height of the plugin window. ## Show output If you want to see the generated JSON, you can enable the `Show output` option. The plugin will show the JSON in a code preview sidebar with: * Syntax highlighting that matches the Figma theme * Line numbers and code folding for collapsing groups * Search with match highlighting * A `Copy` button to copy the whole JSON to the clipboard * A stats bar showing the number of tokens, groups, lines, and the file size 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. In [Dev Mode](/plugin/dev-mode/) the plugin fills the Inspect panel instead, so there is no resizer. # Dev Mode > Export tokens from Dev Mode and Figma for VS Code, and what works differently there. The plugin also runs in Dev Mode and in [Figma for VS Code](https://help.figma.com/hc/en-us/articles/15023121296151), so developers with a Dev seat can export tokens themselves. Open a file in Dev Mode, go to **Plugins** in the right sidebar and run TokensBruecke. The plugin fills the Inspect panel. Everything for exporting is there; **Import tokens** is not, because Dev Mode is read-only. | Feature | Figma Design | Dev Mode | | ------------------------------------------ | ------------ | --------------------------------------------------------------- | | Export: settings, download, push, profiles | ✅ | ✅ | | Show output | ✅ sidebar | ✅ fills the panel, with a back button | | Import tokens into variables | ✅ | ❌ Dev Mode is read-only for every plugin, even with edit access | | Window resizing | ✅ | the panel is resized by you, not the plugin | **Show output** opens the generated JSON in the panel, in place of the settings. The back button returns to them. ## Import and seats To import tokens, someone with a Full seat and edit access to the file runs the plugin in Figma Design. Which seats can run plugins where is listed in Figma’s [plugin help article](https://help.figma.com/hc/en-us/articles/360042532714): a Dev seat runs plugins in Dev Mode only, and Dev Mode needs a paid plan. ## Giving developers your settings Set-up is personal: profiles and server credentials are stored per user. To give developers the same settings, [share a profile in the file](/plugin/profiles/#shared-profiles). They pick it from the profile dropdown and add their own token. # CLI overview > Export tokens from the Figma REST API or a local snapshot with the tokens-bruecke CLI. The CLI is published on npm: [tokens-bruecke](https://www.npmjs.com/package/tokens-bruecke) The CLI can get its data two ways: * **From the Figma REST API** — pass `--file-key` and a token. Requires a Figma Enterprise plan. * **From a local snapshot** — pass `--input`. No token, no Enterprise plan; see [Snapshot input](/cli/options/#snapshot-input). Both modes produce identical output and share every other flag. Caution You need a Figma Enterprise plan to use the Figma REST API for variables. Use `--input` if you don’t have one. ## Installation To install the CLI globally, run: ```bash 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: ```bash tokens-bruecke [options] ``` For example: ```bash # 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 # From a local snapshot — no token required tokens-bruecke --input snapshot.json --output out/tokens.json ``` This will fetch figma variables and export them in `out/tokens.json` ## Quick setup `tokens-bruecke init` asks a few questions and writes a config file you can commit: ```bash tokens-bruecke init ``` ```plaintext ? Color mode (↑↓ to move, enter to select) ❯ HEX "#3366ff" RGBA CSS "rgba(51, 102, 255, 1)" RGBA Object { r, g, b, a } sRGB DTCG DTCG color object HSLA CSS "hsla(225, 100%, 60%, 1)" HSLA Object { h, s, l, a } HSL DTCG DTCG color object OKLCH DTCG DTCG color object ? Styles to include (space to toggle, a for all, enter to confirm) ❯ ◉ Color styles ◯ Typography styles ◉ Effect styles ◯ Grid styles ``` Each answered question collapses to a single line, so you end up with a short summary rather than a wall of text: ```plaintext ? Color mode › OKLCH DTCG ? Styles to include › Color styles, Effect styles ? Use DTCG 2025.10 format? › No ? Output layout › One file per collection ✨ Created tokens-bruecke.config.json ``` **Keys:** `↑`/`↓` (or `j`/`k`, or `Tab`) to move, `1`–`9` to jump straight to a row, `Space` to toggle in multi-select, `a` to toggle all, `Enter` to confirm, `Ctrl+C` / `Esc` to cancel without writing anything. Selection wraps at both ends. Set `NO_COLOR=1` to drop the colour codes. The four questions cover the settings people change most often, but the generated file contains **every** option with its default, plus a `$schema` link — so your editor autocompletes and documents the rest as you edit it. | Option | Alias | Description | | --------- | ----- | --------------------------------------------------------- | | `--yes` | `-y` | Skip the questions and write the default config | | `--force` | | Overwrite an existing config file | | `--path` | `-p` | Where to write it (default: `tokens-bruecke.config.json`) | When stdin or stdout is not a terminal — CI, a pipe, an agent — `init` skips the questions and writes the defaults instead of hanging. It refuses to overwrite an existing config (exit `1`) unless you pass `--force`, and cancelling the questions exits `130` without writing anything. The export never picks up `tokens-bruecke.config.json` on its own: pass it with `-c`. # Options and configuration > CLI flags, snapshot input, the configuration file and the update notice. ## Options | Option | Alias | Description | Required | | ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` | | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` | | `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used | | `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No | | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used | | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split options) | No | | `--config` | `-c` | Path to configuration file | No | | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No | | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No | | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No | | `--omit-created-at` | | Leave the `createdAt` timestamp out of the metadata, so an unchanged file exports to identical output | No | | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No | | `--help` | `-h` | Show usage help | No | | `--version` | | Show the CLI version | No | Progress logs are printed to **stderr**, so stdout stays clean for piping: ```bash tokens-bruecke -a $FIGMA_TOKEN -f $FIGMA_FILE --stdout --quiet | jq . ``` Every option can also be set via a `FIGMA_`-prefixed environment variable — `FIGMA_API_KEY`, `FIGMA_OAUTH_TOKEN`, `FIGMA_FILE_KEY`, `FIGMA_OUTPUT`, etc. Explicit flags override environment variables: ```bash export FIGMA_API_KEY= tokens-bruecke -f $FIGMA_FILE -o out/tokens.json ``` 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](#cli-configuration-file) below). The REST API returns variables, collections and styles in no fixed order, so the CLI sorts them by name in REST mode. Exporting an unchanged file then gives the same output every time, as long as you also pass `--omit-created-at`. This order is alphabetical rather than the order of Figma’s Variables panel, which the plugin and snapshot mode keep. In REST mode the CLI exports the file’s own styles, published or not, the same set the plugin exports. This also works for a branch, which can’t publish styles. Styles that come from a library are left out, as in the plugin. The REST API reports letter spacing in pixels only, so a text style with percentage letter spacing exports as `{ "value": -0.32, "unit": "px" }` in REST mode, where the plugin writes `"-2%"`. Snapshot mode keeps the plugin’s unit. ## Snapshot input `--input ` transforms a local JSON snapshot of a Figma file’s variables and styles instead of calling the REST API. `--input -` reads stdin, so it composes with anything that can dump the data: ```bash # From a file tokens-bruecke --input snapshot.json --output out/tokens.json # From a pipe my-figma-dumper | tokens-bruecke --input - --stdout --quiet > tokens.json ``` This is the path for **agents and plugins running inside Figma**: they already have Plugin API access to the open file, so they can dump the local variables and styles and pipe them straight through — no personal access token, and no Enterprise plan. Snapshot mode ignores the `FIGMA_API_KEY` / `FIGMA_FILE_KEY` environment variables. Passing `--api-key`, `--oauth-token` or `--file-key` explicitly alongside `--input` is an error. Everything else — `--config`, `--split-by-collection`, `--split-by-mode`, `--omit-collection-names`, `--stdout` — behaves exactly as it does in REST mode. ### Snapshot shape Objects use the **raw Figma Plugin API shapes, verbatim** — serialize what the API returns rather than reshaping it, so nothing is lost in translation: ```js const snapshot = { variableCollections: await figma.variables.getLocalVariableCollectionsAsync(), variables: await figma.variables.getLocalVariablesAsync(), paintStyles: await figma.getLocalPaintStylesAsync(), textStyles: await figma.getLocalTextStylesAsync(), effectStyles: await figma.getLocalEffectStylesAsync(), gridStyles: await figma.getLocalGridStylesAsync(), }; ``` Only `variables` and `variableCollections` are required; the style arrays are optional and read only when the matching `includedStyles.*` config flag is on. The full contract is in [schemas/tokens-snapshot.schema.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/schemas/tokens-snapshot.schema.json), with a ready-to-copy example in [examples/tokens-snapshot.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/examples/tokens-snapshot.json). Things worth knowing when building a snapshot: * `valuesByMode` is keyed by **`modeId`**, not mode name — names come from the collection’s `modes` array. * Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them. * `collection.variableIds` preserves the ordering shown in Figma’s Variables panel. * [Extended collections](/reference/token-structure/#extended-collections) need `isExtension`, `parentVariableCollectionId`, `variableOverrides`, `modes[].parentModeId` and `variableIds`. Their variables belong to the root collection, so `variableIds` is the only list of what they contain: without it the extension exports as an empty group. * Aliases are `{ "type": "VARIABLE_ALIAS", "id": "…" }` and must point at a variable present in the snapshot; otherwise the value exports as `"#missing#"`, matching the REST behaviour for unresolvable references. * Color aliases with their own opacity come back from the Plugin API as `{ "color": , "opacity": <0..100 or alias> }` (older Figma Desktop builds used `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [, <0..100 or alias>] }`) — pass either through as-is, see [Color aliases with opacity](/reference/aliases/#color-aliases-with-opacity). Note Plugin API objects are live proxies, so `JSON.stringify` may not enumerate their properties. Copy the fields listed in the schema onto plain objects before serializing. ## CLI Configuration File You can use a JSON configuration file to specify the export options for the CLI. Run [`tokens-bruecke init`](/cli/overview/#quick-setup) to generate one, or write it by hand: ```json { "includedStyles": { "text": { "isIncluded": true, "customName": "typography" }, "effects": { "isIncluded": false, "customName": "effects" }, "grids": { "isIncluded": false, "customName": "grids" }, "colors": { "isIncluded": false, "customName": "colors" } }, "includeScopes": true, "useDTCG": true, // DTCG 2025.10 format: $-prefixed keys, dimension objects, spec-valid types "includeValueStringKeyToAlias": true, "includeFigmaMetaData": false, // Add $extensions.figma to variables (variableId, codeSyntax, collection) and styles (styleId, color style paints) "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1) "expandEasingPresets": true, // Expand Figma's named easing presets into cubicBezier values "colorMode": "hex", // "hex" | "rgba-object" | "srgb-dtcg" | "rgba-css" | "hsla-object" | "hsl-dtcg" | "hsla-css" | "oklch-dtcg"; "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 "splitByMode": false, // Write each mode as a separate .tokens.json file under its collection directory "omitCollectionNames": false, // Drop top-level collection names and merge all variables into one flat namespace "omitCreatedAt": false // Leave the createdAt timestamp out of the metadata } ``` Save this JSON file and pass it to the CLI using the `--config` option. A JSON schema with all options, types and defaults is available at [schemas/cli-options.schema.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/schemas/cli-options.schema.json) — reference it via a `$schema` key for editor validation and autocompletion (see [examples/cli-options.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/examples/cli-options.json)). Note Explicit CLI flags (e.g. `--split-by-collection`) override values from the config file, which override the defaults. Each style type in `includedStyles` is merged with its default, so `"text": { "isIncluded": true }` is enough: the group keeps its default name (`Typography-styles`) and the other style types stay excluded. ## Update notice The CLI checks npm at most once a day for a newer version. When there is one, it prints a single line to stderr after the export, even with `--quiet`: ```plaintext ℹ️ tokens-bruecke 3.20.0 is available (you ran 3.19.0). Use the latest version with: npx tokens-bruecke@latest ``` It only asks npm for the version number — no tokens, file keys or config are sent — and it never installs anything. The check runs alongside the export with a 1.5s timeout, says nothing when offline, and caches the result in `~/.cache/tokens-bruecke` (or `$XDG_CACHE_HOME`). It is skipped when `CI` is set; set `TOKENS_BRUECKE_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` to turn it off elsewhere. # For AI agents > Agent-friendly docs, schemas and how agents can export tokens without the REST API. This documentation is also published as Markdown for LLMs, generated from these pages on every deploy: * [llms.txt](https://tokensbruecke.com/llms.txt) — index of the documentation * [llms-full.txt](https://tokensbruecke.com/llms-full.txt) — every page in one file * [llms-small.txt](https://tokensbruecke.com/llms-small.txt) — a compact version for small context windows This repository and the npm package ship agent-friendly docs: * [llms.txt](https://github.com/tokens-bruecke/figma-plugin/blob/main/llms.txt) — entry point for LLM-based tools * [skills/tokens-bruecke/SKILL.md](https://github.com/tokens-bruecke/figma-plugin/blob/main/skills/tokens-bruecke/SKILL.md) — an [agent skill](https://code.visualstudio.com/docs/copilot/customization/agent-skills) covering CLI usage, auth, config and exit codes; copy the `skills/tokens-bruecke` folder into your project’s skills directory to teach your agent the CLI * [schemas/cli-options.schema.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/schemas/cli-options.schema.json) — machine-readable config schema * [schemas/tokens-snapshot.schema.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/schemas/tokens-snapshot.schema.json) — machine-readable input schema for `--input` For scripted/agent usage prefer `--stdout --quiet` (pure JSON on stdout, logs on stderr) and pass tokens via environment variables. Run it as `npx tokens-bruecke@latest` so the agent always gets the newest release: plain `npx tokens-bruecke` can reuse an old cached copy. See [Update notice](/cli/options/#update-notice). ## Agentic usage without the REST API If your agent can run code inside Figma — a Figma agent, an MCP server with `evaluate_script`, or your own plugin — it already has Plugin API access to the open file. In that case it should **not** go through the REST API at all: | | REST API (`--file-key`) | Snapshot (`--input`) | | ---------------------------------------------- | ----------------------- | ----------------------------------- | | Figma Enterprise plan | Required | Not required | | Personal access / OAuth token | Required | Not required | | File must be published / shared with the token | Yes | No — works on whatever file is open | | Network calls to Figma | Several per export | None | The agent’s job is only to dump data; the CLI still owns every transform, so aliases, modes, scopes and DTCG formatting behave exactly as they do in REST mode. **1. Extract the snapshot from inside Figma.** Plugin API objects are live proxies, so `JSON.stringify` on them may serialize as empty — copy the fields onto plain objects first: ```js const snapshot = { variableCollections: ( await figma.variables.getLocalVariableCollectionsAsync() ).map((c) => ({ id: c.id, name: c.name, defaultModeId: c.defaultModeId, modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name, parentModeId: m.parentModeId, })), variableIds: c.variableIds, // Extended collections only (undefined otherwise) isExtension: c.isExtension, parentVariableCollectionId: c.parentVariableCollectionId, rootVariableCollectionId: c.rootVariableCollectionId, variableOverrides: c.variableOverrides, })), variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({ id: v.id, name: v.name, variableCollectionId: v.variableCollectionId, resolvedType: v.resolvedType, description: v.description, scopes: v.scopes, codeSyntax: v.codeSyntax, valuesByMode: v.valuesByMode, })), // Optional — only needed if the config enables the matching style type paintStyles: (await figma.getLocalPaintStylesAsync()).map((s) => ({ id: s.id, name: s.name, description: s.description, paints: s.paints, boundVariables: s.boundVariables, })), }; const json = JSON.stringify(snapshot, null, 2); ``` Text, effect and grid styles follow the same pattern — see [schemas/tokens-snapshot.schema.json](https://github.com/tokens-bruecke/figma-plugin/blob/main/schemas/tokens-snapshot.schema.json) for the fields each one needs. **2. Pipe it through the CLI.** ```bash # From a file the agent wrote npx tokens-bruecke@latest --input snapshot.json --output tokens.json # Or straight from stdin, no temp file my-figma-agent dump-tokens | npx tokens-bruecke@latest --input - --stdout --quiet > tokens.json # All the usual options still apply npx tokens-bruecke@latest --input snapshot.json --config config.json --split-by-mode --output ./tokens ``` Snapshot mode ignores `FIGMA_API_KEY` / `FIGMA_FILE_KEY`, so a token exported in the environment won’t get in the way. Passing `--api-key`, `--oauth-token` or `--file-key` explicitly alongside `--input` is rejected as a conflict. On a bad snapshot the CLI exits `1` and names the offending key — for example `variables[3] is missing a string "variableCollectionId"` — so an agent can correct its dump and retry without guesswork. Note Aliases pointing at variables outside the snapshot export as `"#missing#"`. To resolve aliases to library variables from another file, include those variables in the `variables` array and their collections in `variableCollections`, with `"remote": true`: they resolve the aliases, as in the plugin and in REST mode, but aren’t exported. # Use as a library > Call the converter from your own build pipeline with fetchTokens and convertTokens. The converter is also available as a module, for build pipelines that want tokens in the same process: no child process, no files on disk, and the token is passed as an argument instead of an environment variable. ```ts import { fetchTokens, convertTokens } from 'tokens-bruecke/api'; import type { ExportOptions, TokensSnapshot } from 'tokens-bruecke/api'; // 1. Fetch from the Figma REST API const tokens = await fetchTokens({ fileKey: 'abc123', personalAccessToken: myToken, // or oauthToken options: { colorMode: 'hex', splitByMode: true }, }); // 2. Convert data you already have const fromSnapshot = await convertTokens(snapshot, { splitByCollection: true }); const fromRest = await convertTokens(restResponse); // GET /v1/files/:key/variables/local ``` * **`options`** takes the same fields as the [CLI configuration file](/cli/options/#cli-configuration-file) and the same defaults, so the API and the CLI give identical output for the same settings. * **Result:** one DTCG token tree when nothing is split. With `splitByCollection` it is keyed by collection name, and with `splitByMode` by `collection/mode`. See [Split results](#split-results) below for how these relate to the files the CLI writes. * **`convertTokens`** accepts a [snapshot](/cli/options/#snapshot-input), or the raw response of the Figma REST variables endpoint (detected by its `meta` key). That response has no styles, so enabling any `includedStyles` with it throws `INVALID_ARGUMENT`. * **Module formats:** the package ships an ESM and a CommonJS build of `tokens-bruecke/api`, so both `import` and `require` work. Each build has its own `TokensBrueckeError` class, so check `error.code` rather than `instanceof` if your code mixes the two. * **No side effects:** the API does not write files, read environment variables, log or exit the process. * **Warnings** (skipped variables and styles, aliases to variables missing from the data, name collisions) are not printed. Pass `onWarning` to receive them: `fetchTokens({ …, onWarning })` or `convertTokens(input, options, { onWarning })`. * **Errors** are `TokensBrueckeError`s with a `code` (`INVALID_ARGUMENT`, `INVALID_SNAPSHOT`, `FIGMA_FORBIDDEN`, `FIGMA_NOT_FOUND`, `FIGMA_RATE_LIMITED`, `FIGMA_REQUEST_FAILED`, `CONVERSION_FAILED`) and the original error as `cause`. `FIGMA_FORBIDDEN` usually means the file is not on an Enterprise plan, or the token lacks the `file_variables:read` scope. ## Split results For a split key, the API returns the bare token tree. The CLI writes the file as `{ "": }`, so the tree sits in a group named after the collection. To get the same contents as a CLI file, wrap it again: ```ts for (const [key, tree] of Object.entries(tokens)) { const collection = key.split('/')[0]; // simple names only, see below const file = JSON.stringify({ [collection]: tree }, null, 2); } ``` * **Aliases** inside a tree are qualified with the collection name (for example `{Semantic.spacing.md}`), so the tree has to be wrapped in `{ [collection]: tree }` for references to resolve. * **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are, except that `.`, `{` and `}` in a collection name become `-` (`1. Primitives` is keyed as `1- Primitives`), because references use them. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names. Match the key against the collection names in `$extensions["tokens-bruecke-meta"].variableCollections`, with those characters replaced, instead, as the CLI does. # Token structure > How collections, groups, variables and modes map to the JSON output, including extended collections. Plugin first takes the `collection` name, then the `group` and then the `variable` name. Mode variables will be wrapped under the `$extensions` objects ```text Collection └─ Group └─ Variable ├─ $value value of the default mode └─ $extensions └─ mode ├─ Light value in this mode └─ Dark value in this mode ``` For example, if you have a collection named `clr-theme`, mode named `light` and variable named `dark`, the plugin will generate the following JSON: ```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`. In this case, the plugin will generate the following JSON: ```json { "base": { "primary": { "10": { "type": "color", "value": "#000000" } } } } ``` ### Extended collections Collections created with [Extend a variable collection](https://help.figma.com/hc/en-us/articles/36346281624471-Extend-a-variable-collection) are exported as collections of their own. Figma stores only what an extension changes, so the export writes all the variables it inherits, with the overrides of its chain applied, which keeps every collection complete. * The value of a variable is the closest override in the chain of extensions, or the value of the root collection when nothing overrides it. An override that was cleared falls through to the parent. Each mode follows the parent mode it inherits from, even when the extension renames it. * Aliases to variables of the root collection point to the extension’s own variable, so `{Core.color.brand}` becomes `{Regional.color.brand}` inside `Regional`. Aliases to other collections stay as they are. * Extensions of a library collection are exported without the variables they inherit, because those live in the library file, not in yours. The export warns about them. * With [Omit collection names](/plugin/advanced-settings/#omit-collection-names) the extended collections are skipped with a warning, because they repeat the variables of their root collection and would collide in a single namespace. ```json // "Regional" extends "Core" and overrides color/brand { "Core": { "color": { "brand": { "type": "color", "value": "#ff0000" }, "text": { "type": "color", "value": "{Core.color.brand}" } } }, "Regional": { "color": { "brand": { "type": "color", "value": "#00ff00" }, "text": { "type": "color", "value": "{Regional.color.brand}" } } } } ``` # Aliases > How aliases, color aliases with opacity, library variables and modes are handled. All aliases are converted into the alias string format from the [Design Tokens specification](https://design-tokens.github.io/community-group/format/#aliases-references). ```json { "button": { "background": { "type": "color", "value": "{colors.primary.10}" } } } ``` References use `.` as separator, so DTCG forbids `.`, `{` and `}` in token and group names. A collection whose name contains them, like `1. Primitives`, is exported as `1- Primitives`, with a warning; the meta keeps the original name, and the [import](/getting-started/export-and-import/#import-json--variables) uses it to recreate the collection under its Figma name. ## Include `.value` string for aliases You can switch on the `Include .value string for aliases` option in [the plugin settings](/plugin/advanced-settings/#include-value-string-for-aliases). ## Color aliases with opacity Since September 2026 Figma lets a color variable alias another color and apply its own opacity on top (“Control opacity at scale”). The opacity can be a plain percentage or a number variable with the `COLOR_OPACITY` scope. The [DTCG color type](https://www.designtokens.org/tr/2025.10/color/#format) has no way to express “this color, with that opacity” while keeping the reference, so the plugin exports these variables as a composite value: `components` holds the reference to the base color and `alpha` holds the opacity, as a `0..1` number (or `"50%"` with [Use percentage for opacity](/plugin/advanced-settings/#use-percentage-for-opacity)) or a reference to the number variable driving it. ```json { "opacity": { "50": { "$type": "number", "$value": 0.5, "scopes": ["COLOR_OPACITY"] } }, "color": { "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0.2, 0.4, 0.8], "alpha": 1, "hex": "#3366cc" } }, "brand-translucent": { "$type": "color", "$value": { "components": "{color.brand}", "alpha": 0.5 } }, "brand-muted": { "$type": "color", "$value": { "components": "{color.brand}", "alpha": "{opacity.50}" } } } } ``` The `alpha` is the opacity Figma applies on top of the referenced color. If the base color is a literal rather than an alias, the opacity is baked into the regular color value for the chosen [color mode](/plugin/settings/#color-mode); only when the opacity itself is a reference does the color value keep an `alpha` (or `a`) reference in place of the number. [Importing](/getting-started/export-and-import/#import-json--variables) these tokens recreates the composed color variable in Figma: `components` becomes the alias, `alpha` the opacity (a plain percentage or an alias to the number variable). References to variables in other collections are resolved once every collection has been imported. Figma has exposed these variables to plugins in two shapes so far: current runtimes (the Figma web app, and what `setValueForMode` accepts) use `{ "color": , "opacity": <0..100 or alias> }`, while Figma Desktop 126.x returned a `COMPOSE_COLOR` expression. The export reads both. The import writes the current shape and falls back to the expression for runtimes that only accept that one. Caution Older Figma clients, including Figma Desktop 126.x, can read these variables but refuse to write them in either shape (“Composed color variable values are not supported”). Figma has since enabled writing them through the Plugin API ([figma/plugin-typings#375](https://github.com/figma/plugin-typings/issues/375)), so update Figma if the import skips them. On an outdated client the plugin leaves those values untouched, reports how many were skipped and asks you to update Figma. Other tokens in the same import are not affected. Note Figma is still changing how these values are exposed to plugins. If a color variable comes back in a shape the plugin does not recognise, the export leaves that variable out and logs a `[tokens-bruecke] Skipped variable …` warning with the raw value to the Figma console (`Plugins → Development → Open console`) instead of failing. Please paste that warning into [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91). Note This shape is an extension of the DTCG format, so a consumer needs a small custom transform: resolve the `components` reference, then apply `alpha`. ## 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. ```json { "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. The CLI and the library API do the same in REST mode. In snapshot mode, add the library variables and their collections with `"remote": true`: they resolve aliases but aren’t exported. 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 mode values are left out: `$extensions.mode` is an empty object. If there are multiple modes, the plugin will place them under the `$extensions` objects. It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guides/modes#with-modes) # Styles support > How typography, color, grid, shadow and blur styles are exported. 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) A style the plugin can’t export, such as a color style with only image fills, is left out and the rest of the export continues. The plugin logs a `[tokens-bruecke] Skipped style …` warning to the console (`Plugins → Development → Open console`, or stderr for the CLI). ## Typography ```json "extralight": { "type": "typography", "value": { "fontFamily": "Inter", "fontWeight": 400, "fontSize": "18px", "fontStyle": "normal", "lineHeight": "28px", "letterSpacing": "0%", "paragraphSpacing": "0", "paragraphIndent": "0", "textDecoration": "NONE", "textCase": "ORIGINAL" }, "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. A solid style bound to a color variable with its own opacity below 100% is exported like a [color alias with opacity](/reference/aliases/#color-aliases-with-opacity): `{ "components": "{color.brand}", "alpha": 0.5 }`. ```json // 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 } ], "$extensions": { "gradient": { "type": "linear", "angle": 180 } } } ``` DTCG has no direction or type for a gradient, only the stops, so they are exported in `$extensions.gradient`. `type` is `linear`, `radial`, `angular` or `diamond`. `angle` is only there for a linear gradient, in CSS degrees: `0` is to the top, `90` to the right and `180` to the bottom. It is taken from the handles of the gradient, which are relative to the layer, so it is exact for a gradient along an axis and an approximation for a diagonal one on a layer that is not square. ### Color styles with several paints A token has a single value, so a color style with several paints takes its value from the top visible solid paint or gradient. The other paints are left out with a warning. With [Include Figma metadata](/plugin/advanced-settings/#include-figma-metadata) on, every paint of the style is also exported in `$extensions.figma.paints`, in Figma’s order: from the bottom paint to the top one. Each paint has its `type`, `visible`, `opacity` and `blendMode`. A solid paint adds its `color`, without the paint’s opacity, or the alias of its variable. A gradient adds its `stops`, its `gradient` type and angle, and the raw `gradientTransform`. An image adds its `imageHash` and `scaleMode`. ```json "overlay": { "$type": "color", "$value": "#ff000080", "$extensions": { "figma": { "styleId": "S:4d3c…", "paints": [ { "type": "GRADIENT_LINEAR", "visible": true, "opacity": 1, "blendMode": "NORMAL", "stops": [ { "color": "#000000", "position": 0 }, { "color": "#ffffff", "position": 1 } ], "gradient": { "type": "linear", "angle": 180 }, "gradientTransform": [[0, 1, 0], [-1, 0, 1]] }, { "type": "SOLID", "visible": true, "opacity": 0.5, "blendMode": "MULTIPLY", "color": "#ff0000" } ] } } } ``` ## Grids In Figma you can add as many grids in the style as you want. The plugin exports the first `Columns` grid as `column*` values and the first `Rows` grid as `row*` values; further grids of the same kind are left out. A square `Grid` only has a cell size, which is exported as `columnWidth` when the style has no columns. Sizes of `0` are kept, and an `Auto` count is left out. ```json // 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`. The value is always an array, even when the style has a single shadow. The first effect of a style decides its type: a style that starts with a shadow is exported as a `shadow` token, and blur effects in it are left out with a warning. A style that starts with a blur is exported as a `blur` token. ```json "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. Only the first effect of a blur style is exported. Like all other tokens, blur tokens use the `$type` / `$value` keys with the [DTCG 2025.10 format](/plugin/settings/#dtcg-202510-format) setting on, and `type` / `value` with it off. ```json // Background blur "sm": { "$type": "blur", "$value": { "role": "background", "blur": "4px" } } // Layer blur "md": { "$type": "blur", "$value": { "role": "layer", "blur": "12px" } } ``` ## Multiple shadows support If a shadow style has several shadows, the plugin exports all of them in the array. ```json "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" } ] } ``` # Types and scopes > How Figma variable types, motion variables and scopes map to design token types. ## Variables types conversion Unlike design tokens, Figma variables [support only 6 types](https://www.figma.com/plugin-docs/api/VariableResolvedDataType) — `COLOR`, `BOOLEAN`, `FLOAT`, `STRING`, `TIMING` and `EASING`. So, the plugin converts them into the corresponding types from the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/#types). | Figma type | Scope condition | Design Tokens type | | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------ | | COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) | | BOOLEAN | — | *boolean* \* | | FLOAT | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) | | FLOAT | opacity scopes (no %) | *number* \* | | FLOAT | opacity scopes (with %) | *string* (e.g. `"10%"`) \* | | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* | | STRING | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) | | STRING | only `FONT_FAMILY` | [fontFamily](https://www.designtokens.org/tr/2025.10/format/#font-family) | | STRING | all other scopes | *string* \* | | TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* | | EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or *string* \*\*\*\* | \* native JSON types — not part of the closed DTCG 2025.10 type set. The plugin still writes them as the token’s `$type`. “Opacity scopes” means every scope of the variable is `OPACITY` or `COLOR_OPACITY`, see [Scopes limitations](#scopes-limitations). Also see [this issue](https://github.com/design-tokens/community-group/issues/120#issuecomment-1279527414). \*\* Figma currently supports only `FLOAT` for numeric values used as dimensions, which map to `px` units. With the DTCG 2025.10 format on, dimensions are exported as `{ "value": 6, "unit": "px" }` objects; otherwise the plugin appends `px` to the number. \*\*\* Figma stores timings in seconds; the plugin converts them to milliseconds. With the DTCG 2025.10 format on, durations are exported as `{ "value": 300, "unit": "ms" }` objects; otherwise the plugin appends `ms` to the number. \*\*\*\* See [Motion variables](#motion-variables) below. ## Motion variables Figma’s `EASING` variables hold either a custom curve or one of Figma’s presets. DTCG only has a `cubicBezier` type, so the plugin maps them like this: | Figma easing | Token type | Example value | | ----------------------------------------------------------------------------------- | ------------- | ----------------------- | | Custom bezier | `cubicBezier` | `[0, 0, 0.58, 1]` | | Linear, Ease in / out / in and out, Ease in / out / in and out back | `cubicBezier` | `[0.42, 0, 1, 1]` | | Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off | `string` | `"ease-in"` | | Gentle, Quick, Bouncy, Slow | `string` | `"gentle"` | | Custom spring | `string` | `"spring(bounce 0.35)"` | | Hold | `string` | `"hold"` | Named bezier presets are expanded into curves unless [Expand easing presets to cubic-bezier](/plugin/advanced-settings/#expand-easing-presets-to-cubic-bezier) is turned off. Springs and Hold are always names: DTCG has no spring type, and Figma exposes no numbers for them. All of these forms are read back on import, so a round trip through the plugin preserves the original preset. Expanded curves are matched back to the preset they came from, and easings exported as strings carry an `$extensions.figmaType: "EASING"` marker so they are recreated as `EASING` variables rather than `STRING` ones. Note The curves of the named bezier presets are the ones Figma attaches to the preset in the Plugin API; if one of them does not match what you see in your file, please [open an issue](https://github.com/tokens-bruecke/figma-plugin/issues). ## Design tokens types In order to validate types, the plugin uses the [Design Tokens types](https://github.com/tokens-bruecke/figma-plugin/blob/main/plugin-types.d.ts). ## Scopes limitations Figma variables have no font weight, font family or opacity type, so the plugin reads the variable’s scopes to pick the token type: * A number or string variable whose only scope is `FONT_WEIGHT` becomes a `fontWeight` token. With any other scope next to it, it stays a `dimension` or `string`. * A string variable whose only scope is `FONT_FAMILY` becomes a `fontFamily` token. With any other scope next to it, it stays a `string`. * A number variable whose scopes are all `OPACITY` or `COLOR_OPACITY` (the opacity of a color variable) becomes a `number` token, or a `string` with `%` if [Use percentage for opacity](/plugin/advanced-settings/#use-percentage-for-opacity) is enabled. With any other scope next to them, it is exported as a `dimension`. Unless [scopes are included](/plugin/advanced-settings/#include-variable-scopes), such a token carries its scopes in `$extensions.figmaScopes`, so the [import](/getting-started/export-and-import/#import-json--variables) recreates an opacity variable (50, not 0.5). # Privacy and feedback > What the plugin and this site collect, and where to report issues. ## Privacy and analytics The plugin counts a few anonymous usage events with [GoatCounter](https://www.goatcounter.com), a privacy-friendly, open-source counter. It helps us see which features are used so we know where to focus. What is sent: the plugin was opened, and whether in Dev Mode; the file had variables or not; tokens were downloaded, copied from the code preview or imported; a connection test or a push to one of the servers (GitHub, GitHub pull request, GitLab, GitLab merge request, JSONBin, custom URL) was started, and whether a Git push left some collections out; a profile was shared in the file, shared again, stopped being shared, added from a shared profile, or updated from one. That is the full list. What is never sent: your tokens, variable or collection names, file names, server URLs, access tokens, or any other data read from your Figma file. GoatCounter sets no cookies and does not track you across sites. This documentation site counts page views with a separate GoatCounter: the page address, the referring site, and the browser, screen size and country GoatCounter derives from the request. No cookies are set and nothing identifies you. ## Feedback If you have any questions or suggestions, feel free to [create an issue](https://github.com/tokens-bruecke/figma-plugin/issues)