tokens-bruecke 3.14.0 → 3.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +111 -71
- package/examples/tokens-snapshot.json +21 -4
- package/llms.txt +1 -1
- package/package.json +1 -1
- package/schemas/cli-options.schema.json +3 -3
- package/schemas/tokens-snapshot.schema.json +101 -8
- package/skills/tokens-bruecke/SKILL.md +28 -22
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
## [3.14.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.13.1...v3.14.0) (2026-10-02)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
- **color:** import color aliases with opacity now that Figma allows it ([c225d06](https://github.com/tokens-bruecke/figma-plugin/commit/c225d062727d1ab991322df68c3ff0e8d13b98b2)), closes [figma/plugin-typings#375](https://github.com/figma/plugin-typings/issues/375)
|
|
6
|
+
|
|
1
7
|
## [3.13.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.13.0...v3.13.1) (2026-10-02)
|
|
2
8
|
|
|
3
9
|
### Bug Fixes
|
package/README.md
CHANGED
|
@@ -58,7 +58,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
58
58
|
- [Grids](#grids)
|
|
59
59
|
- [Shadows](#shadows)
|
|
60
60
|
- [Blur](#blur)
|
|
61
|
-
- [Multiple
|
|
61
|
+
- [Multiple shadows support](#multiple-shadows-support)
|
|
62
62
|
- [Tokens structure](#tokens-structure)
|
|
63
63
|
- [Aliases handling](#aliases-handling)
|
|
64
64
|
- [Include `.value` string for aliases](#include-value-string-for-aliases-1)
|
|
@@ -68,7 +68,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
68
68
|
- [Variables types conversion](#variables-types-conversion)
|
|
69
69
|
- [Motion variables](#motion-variables)
|
|
70
70
|
- [Design tokens types](#design-tokens-types)
|
|
71
|
-
- [Scopes
|
|
71
|
+
- [Scopes limitations](#scopes-limitations)
|
|
72
72
|
- [Privacy and analytics](#privacy-and-analytics)
|
|
73
73
|
- [Feedback](#feedback)
|
|
74
74
|
|
|
@@ -80,7 +80,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
80
80
|
2. Make sure you have variables in your Figma file.
|
|
81
81
|
3. Run the plugin.
|
|
82
82
|
4. Adjust the settings.
|
|
83
|
-
5. Then you can download the JSON file or push it to
|
|
83
|
+
5. Then you can download the JSON file or push it to one of the [supported services](#push-to-server).
|
|
84
84
|
|
|
85
85
|
### Export and Import
|
|
86
86
|
|
|
@@ -95,7 +95,7 @@ The plugin supports both **exporting** and **importing** design tokens:
|
|
|
95
95
|
|
|
96
96
|
#### Import (JSON → Variables)
|
|
97
97
|
|
|
98
|
-
- Click **"Import
|
|
98
|
+
- 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
|
|
99
99
|
- The plugin will create variable collections, modes, and variables based on the JSON structure
|
|
100
100
|
- Supports both DTCG format (`$value`, `$type`) and standard format (`value`, `type`)
|
|
101
101
|
- Handles alias references between variables
|
|
@@ -107,12 +107,19 @@ The plugin supports both **exporting** and **importing** design tokens:
|
|
|
107
107
|
- ✅ Supports multiple modes (from `$extensions.mode` or `extensions.mode`)
|
|
108
108
|
- ✅ Handles all variable types (color, number, string, boolean, timing, easing)
|
|
109
109
|
- ✅ Resolves alias references between variables
|
|
110
|
-
- ✅ Supports
|
|
111
|
-
- ✅
|
|
110
|
+
- ✅ 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](#color-aliases-with-opacity). HSLA CSS and HSLA Object can't be imported yet
|
|
111
|
+
- ✅ 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
|
|
112
112
|
- ✅ Imports `duration` and `cubicBezier` tokens as Figma motion variables (see [Motion variables](#motion-variables))
|
|
113
113
|
|
|
114
|
+
**What to know before importing:**
|
|
115
|
+
|
|
116
|
+
- Every top-level key becomes a collection. Files exported with [Omit collection names](#omit-collection-names) or split by mode don't map back to the original collections.
|
|
117
|
+
- An existing collection's first mode is renamed to the first mode in the tokens.
|
|
118
|
+
- Units are dropped from dimensions, since Figma number variables have no unit: `1rem` imports as `1`.
|
|
119
|
+
- Extended collections are imported as regular collections.
|
|
120
|
+
|
|
114
121
|
> [!WARNING]
|
|
115
|
-
> **Styles Export Limitation**: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles
|
|
122
|
+
> **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.
|
|
116
123
|
|
|
117
124
|
---
|
|
118
125
|
|
|
@@ -133,7 +140,7 @@ Allows you to choose the color mode for the generated JSON. Default value is `HE
|
|
|
133
140
|
|
|
134
141
|
### Include styles
|
|
135
142
|
|
|
136
|
-
Allows you to include styles into the generated JSON. See more about styles support in the [Styles support](#styles-support) section.
|
|
143
|
+
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](#styles-support) section.
|
|
137
144
|
|
|
138
145
|
There is an option to rename each style's group and give it a custom name for better organization.
|
|
139
146
|
|
|
@@ -141,13 +148,13 @@ There is an option to rename each style's group and give it a custom name for be
|
|
|
141
148
|
|
|
142
149
|
### Add styles to
|
|
143
150
|
|
|
144
|
-
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).
|
|
151
|
+
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 (fig.4).
|
|
145
152
|
|
|
146
153
|

|
|
147
154
|
|
|
148
155
|
### Include variable scopes
|
|
149
156
|
|
|
150
|
-
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.
|
|
157
|
+
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.
|
|
151
158
|
|
|
152
159
|
```json
|
|
153
160
|
{
|
|
@@ -163,7 +170,7 @@ Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api
|
|
|
163
170
|
|
|
164
171
|
### Use percentage for opacity
|
|
165
172
|
|
|
166
|
-
Is `off` by default. When enabled, opacity values will be exported as percentages instead of normalized decimal values. This affects variables
|
|
173
|
+
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](#scopes-limitations)).
|
|
167
174
|
|
|
168
175
|
```json
|
|
169
176
|
// Without percentage format (default)
|
|
@@ -218,7 +225,6 @@ Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](http
|
|
|
218
225
|
|
|
219
226
|
- All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`).
|
|
220
227
|
- 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.
|
|
221
|
-
- `$type` is omitted for Figma `STRING` and `BOOLEAN` variables, since those aren't part of the DTCG type set. The original Figma type is preserved under the token's `$extensions.figmaType`.
|
|
222
228
|
- The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect.
|
|
223
229
|
|
|
224
230
|
```json
|
|
@@ -332,6 +338,8 @@ Is `off` by default. When enabled, each mode of a variable collection is exporte
|
|
|
332
338
|
|
|
333
339
|
Collections with a single mode are exported as a single `{CollectionName}.tokens.json` file.
|
|
334
340
|
|
|
341
|
+
Splitting by mode needs the [DTCG 2025.10 format](#dtcg-202510-format) setting on. With it off, each collection is exported as a single file.
|
|
342
|
+
|
|
335
343
|
For example, a collection `color` with modes `light` and `dark` produces `color/light.tokens.json` and `color/dark.tokens.json`:
|
|
336
344
|
|
|
337
345
|
```json
|
|
@@ -511,25 +519,29 @@ The four questions cover the settings people change most often, but the generate
|
|
|
511
519
|
| `--force` | | Overwrite an existing config file |
|
|
512
520
|
| `--path` | `-p` | Where to write it (default: `tokens-bruecke.config.json`) |
|
|
513
521
|
|
|
514
|
-
When stdin is not a terminal — CI, a pipe, an agent — `init` skips the questions and writes the defaults instead of hanging.
|
|
522
|
+
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.
|
|
523
|
+
|
|
524
|
+
The export never picks up `tokens-bruecke.config.json` on its own: pass it with `-c`.
|
|
515
525
|
|
|
516
526
|
### Options
|
|
517
527
|
|
|
518
|
-
| Option | Alias | Description
|
|
519
|
-
| ------------------------- | ----- |
|
|
520
|
-
| `--api-key` | `-a` | Figma personal access token (PAT)
|
|
521
|
-
| `--oauth-token` | `-t` | Figma OAuth token
|
|
522
|
-
| `--file-key` | `-f` | Figma file key
|
|
523
|
-
| `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin)
|
|
524
|
-
| `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode`
|
|
525
|
-
| `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
|
|
526
|
-
| `--config` | `-c` | Path to configuration file
|
|
527
|
-
| `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output`
|
|
528
|
-
| `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output`
|
|
529
|
-
| `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace
|
|
530
|
-
| `--quiet` | `-q` | Suppress progress logs (errors are still printed)
|
|
531
|
-
| `--help` | `-h` | Show usage help
|
|
532
|
-
| `--version` | | Show the CLI version
|
|
528
|
+
| Option | Alias | Description | Required |
|
|
529
|
+
| ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
530
|
+
| `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
|
|
531
|
+
| `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
|
|
532
|
+
| `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
|
|
533
|
+
| `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
|
|
534
|
+
| `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
|
|
535
|
+
| `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) \* | No |
|
|
536
|
+
| `--config` | `-c` | Path to configuration file | No |
|
|
537
|
+
| `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
|
|
538
|
+
| `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
|
|
539
|
+
| `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
|
|
540
|
+
| `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
|
|
541
|
+
| `--help` | `-h` | Show usage help | No |
|
|
542
|
+
| `--version` | | Show the CLI version | No |
|
|
543
|
+
|
|
544
|
+
\* Only the `--split-*` flags are checked. Keep `splitByCollection` and `splitByMode` off in a config file you use with `--stdout`, otherwise the CLI prints an internal map of files instead of the tokens.
|
|
533
545
|
|
|
534
546
|
Progress logs are printed to **stderr**, so stdout stays clean for piping:
|
|
535
547
|
|
|
@@ -587,6 +599,8 @@ Things worth knowing when building a snapshot:
|
|
|
587
599
|
- `valuesByMode` is keyed by **`modeId`**, not mode name — names come from the collection's `modes` array.
|
|
588
600
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
589
601
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
602
|
+
- [Extended collections](#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.
|
|
603
|
+
- Unlike REST mode, snapshot mode doesn't drop collections hidden from publishing. Leave out anything you don't want exported.
|
|
590
604
|
- 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.
|
|
591
605
|
- Color aliases with their own opacity come back from the Plugin API as `{ "color": <alias or rgba>, "opacity": <0..100 or alias> }` (older Figma Desktop builds used `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }`) — pass either through as-is, see [Color aliases with opacity](#color-aliases-with-opacity).
|
|
592
606
|
|
|
@@ -608,7 +622,7 @@ You can use a JSON configuration file to specify the export options for the CLI.
|
|
|
608
622
|
"includeScopes": true,
|
|
609
623
|
"useDTCG": true, // DTCG 2025.10 format: $-prefixed keys, dimension objects, spec-valid types
|
|
610
624
|
"includeValueStringKeyToAlias": true,
|
|
611
|
-
"includeFigmaMetaData": false, //
|
|
625
|
+
"includeFigmaMetaData": false, // Add $extensions.figma (variableId, codeSyntax, collection) to variables
|
|
612
626
|
"usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
|
|
613
627
|
"expandEasingPresets": true, // Expand Figma's named easing presets into cubicBezier values
|
|
614
628
|
"colorMode": "hex", // "hex" | "rgba-object" | "srgb-dtcg" | "rgba-css" | "hsla-object" | "hsl-dtcg" | "hsla-css" | "oklch-dtcg";
|
|
@@ -624,6 +638,9 @@ Save this JSON file and pass it to the CLI using the `--config` option. A JSON s
|
|
|
624
638
|
> [!NOTE]
|
|
625
639
|
> Explicit CLI flags (e.g. `--split-by-collection`) override values from the config file, which override the defaults.
|
|
626
640
|
|
|
641
|
+
> [!WARNING]
|
|
642
|
+
> Top-level keys are merged one level deep. If you set `includedStyles`, it replaces the whole default object, so give every included style type a `customName`, or its group is exported under the key `"undefined"`.
|
|
643
|
+
|
|
627
644
|
### For AI agents
|
|
628
645
|
|
|
629
646
|
This repository and the npm package ship agent-friendly docs:
|
|
@@ -658,8 +675,17 @@ const snapshot = {
|
|
|
658
675
|
id: c.id,
|
|
659
676
|
name: c.name,
|
|
660
677
|
defaultModeId: c.defaultModeId,
|
|
661
|
-
modes: c.modes.map((m) => ({
|
|
678
|
+
modes: c.modes.map((m) => ({
|
|
679
|
+
modeId: m.modeId,
|
|
680
|
+
name: m.name,
|
|
681
|
+
parentModeId: m.parentModeId,
|
|
682
|
+
})),
|
|
662
683
|
variableIds: c.variableIds,
|
|
684
|
+
// Extended collections only (undefined otherwise)
|
|
685
|
+
isExtension: c.isExtension,
|
|
686
|
+
parentVariableCollectionId: c.parentVariableCollectionId,
|
|
687
|
+
rootVariableCollectionId: c.rootVariableCollectionId,
|
|
688
|
+
variableOverrides: c.variableOverrides,
|
|
663
689
|
})),
|
|
664
690
|
variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({
|
|
665
691
|
id: v.id,
|
|
@@ -710,12 +736,12 @@ On a bad snapshot the CLI exits `1` and names the offending key — for example
|
|
|
710
736
|
|
|
711
737
|
## Push to server
|
|
712
738
|
|
|
713
|
-
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) and custom servers.
|
|
739
|
+
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) and custom servers.
|
|
714
740
|
|
|
715
741
|

|
|
716
742
|
|
|
717
743
|
If you connected multiple servers, the plugin will try to push the tokens to all of them one by one.
|
|
718
|
-
In
|
|
744
|
+
In order to test if your credentials are valid you can make a test request by clicking the `Push to server` button (fig.6).
|
|
719
745
|
|
|
720
746
|

|
|
721
747
|
|
|
@@ -742,16 +768,20 @@ In ordere to test if your credentials are valid you can make a test request by c
|
|
|
742
768
|
|
|
743
769
|
### [GitHub PR](https://github.com)
|
|
744
770
|
|
|
745
|
-
|
|
771
|
+
Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a pull request. The token, owner, repo, file name and commit message fields work the same as for the [GitHub](#github) server. The other fields:
|
|
746
772
|
|
|
773
|
+
- **Base branch** (required). The branch the pull request targets, e.g. `main`.
|
|
774
|
+
- **Branch name** (optional). 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.
|
|
747
775
|
- **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.
|
|
748
776
|
- **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.
|
|
749
777
|
|
|
778
|
+
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.
|
|
779
|
+
|
|
750
780
|

|
|
751
781
|
|
|
752
782
|
### [GitLab](https://gitlab.com)
|
|
753
783
|
|
|
754
|
-
1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope.
|
|
784
|
+
1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope. For a self-hosted GitLab, fill in the host field; it defaults to `gitlab.com`.
|
|
755
785
|
2. In the plugin settings paste the token into the `Project access token` field.
|
|
756
786
|
3. Add an owner name, repository name and a branch name.
|
|
757
787
|
4. 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`.
|
|
@@ -763,7 +793,9 @@ All the steps are the same as for the [GitHub](#github) server, except the last
|
|
|
763
793
|
|
|
764
794
|
### Custom server
|
|
765
795
|
|
|
766
|
-
There is a
|
|
796
|
+
There is a possibility to connect a custom server. In order to do that you need to specify a URL, a method (`POST` or `PUT`, by default it's `POST`) and optional headers.
|
|
797
|
+
|
|
798
|
+
JSONBin and custom servers always receive the whole JSON in one request: the [split into separate files](#split-collections-into-separate-files) settings only apply to downloads, the CLI and the Git servers.
|
|
767
799
|
|
|
768
800
|

|
|
769
801
|
|
|
@@ -842,11 +874,16 @@ Supported styles:
|
|
|
842
874
|
"fontFamily": "Inter",
|
|
843
875
|
"fontWeight": 400,
|
|
844
876
|
"fontSize": "18px",
|
|
877
|
+
"fontStyle": "normal",
|
|
845
878
|
"lineHeight": "28px",
|
|
846
|
-
"letterSpacing": "0%"
|
|
879
|
+
"letterSpacing": "0%",
|
|
880
|
+
"paragraphSpacing": "0",
|
|
881
|
+
"paragraphIndent": "0",
|
|
882
|
+
"textDecoration": "NONE",
|
|
883
|
+
"textCase": "ORIGINAL"
|
|
847
884
|
},
|
|
848
885
|
"description": "",
|
|
849
|
-
"extensions": {
|
|
886
|
+
"$extensions": {
|
|
850
887
|
"styleId": "S:0ffe98ad785a13839980113831d5fbaf21724594,"
|
|
851
888
|
}
|
|
852
889
|
}
|
|
@@ -930,31 +967,33 @@ In Figma you can add as many grids in the style as you want. But the plugin will
|
|
|
930
967
|
|
|
931
968
|
### Shadows
|
|
932
969
|
|
|
933
|
-
The plugin supports `drop-shadow` and `inner-shadow` effects. If the effect is `inner-shadow`, the plugin will set the `inset` property to `true`.
|
|
970
|
+
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.
|
|
934
971
|
|
|
935
972
|
```json
|
|
936
973
|
"xl": {
|
|
937
974
|
"type": "shadow",
|
|
938
|
-
"value":
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
975
|
+
"value": [
|
|
976
|
+
{
|
|
977
|
+
"inset": false,
|
|
978
|
+
"color": "#0000000a",
|
|
979
|
+
"offsetX": "0px",
|
|
980
|
+
"offsetY": "10px",
|
|
981
|
+
"blur": "10px",
|
|
982
|
+
"spread": "-5px"
|
|
983
|
+
}
|
|
984
|
+
]
|
|
946
985
|
}
|
|
947
986
|
```
|
|
948
987
|
|
|
949
988
|
### Blur
|
|
950
989
|
|
|
951
|
-
The plugin supports `background` and `layer` blur effects. In order to distinguish between them, the plugin adds the `role` property to the generated JSON.
|
|
990
|
+
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, and blur tokens always use the `$type` / `$value` keys, whatever the [DTCG 2025.10 format](#dtcg-202510-format) setting.
|
|
952
991
|
|
|
953
992
|
```json
|
|
954
993
|
// Background blur
|
|
955
994
|
"sm": {
|
|
956
|
-
"type": "blur",
|
|
957
|
-
"value": {
|
|
995
|
+
"$type": "blur",
|
|
996
|
+
"$value": {
|
|
958
997
|
"role": "background",
|
|
959
998
|
"blur": "4px"
|
|
960
999
|
}
|
|
@@ -962,17 +1001,17 @@ The plugin supports `background` and `layer` blur effects. In order to distingui
|
|
|
962
1001
|
|
|
963
1002
|
// Layer blur
|
|
964
1003
|
"md": {
|
|
965
|
-
"type": "blur",
|
|
966
|
-
"value": {
|
|
1004
|
+
"$type": "blur",
|
|
1005
|
+
"$value": {
|
|
967
1006
|
"role": "layer",
|
|
968
1007
|
"blur": "12px"
|
|
969
1008
|
}
|
|
970
1009
|
}
|
|
971
1010
|
```
|
|
972
1011
|
|
|
973
|
-
### Multiple
|
|
1012
|
+
### Multiple shadows support
|
|
974
1013
|
|
|
975
|
-
If
|
|
1014
|
+
If a shadow style has several shadows, the plugin exports all of them in the array.
|
|
976
1015
|
|
|
977
1016
|
```json
|
|
978
1017
|
"new-sh": {
|
|
@@ -1147,7 +1186,7 @@ So you will need to merge the file with the base variables from one file with an
|
|
|
1147
1186
|
|
|
1148
1187
|
### Handle modes
|
|
1149
1188
|
|
|
1150
|
-
If there is only one mode
|
|
1189
|
+
If there is only one mode, the mode values are left out: `$extensions.mode` is an empty object.
|
|
1151
1190
|
If there are multiple modes, the plugin will place them under the `$extensions` objects.
|
|
1152
1191
|
|
|
1153
1192
|
It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guides/modes#with-modes)
|
|
@@ -1158,19 +1197,20 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
|
|
|
1158
1197
|
|
|
1159
1198
|
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).
|
|
1160
1199
|
|
|
1161
|
-
| Figma type | Scope condition
|
|
1162
|
-
| ---------- |
|
|
1163
|
-
| COLOR | —
|
|
1164
|
-
| BOOLEAN | —
|
|
1165
|
-
| FLOAT | `FONT_WEIGHT`
|
|
1166
|
-
| FLOAT |
|
|
1167
|
-
| FLOAT |
|
|
1168
|
-
| FLOAT | all other scopes
|
|
1169
|
-
| STRING |
|
|
1170
|
-
|
|
|
1171
|
-
|
|
|
1172
|
-
|
|
1173
|
-
|
|
1200
|
+
| Figma type | Scope condition | Design Tokens type |
|
|
1201
|
+
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
|
|
1202
|
+
| COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
|
|
1203
|
+
| BOOLEAN | — | _boolean_ \* |
|
|
1204
|
+
| FLOAT | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) |
|
|
1205
|
+
| FLOAT | opacity scopes (no %) | _number_ \* |
|
|
1206
|
+
| FLOAT | opacity scopes (with %) | _string_ (e.g. `"10%"`) \* |
|
|
1207
|
+
| FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
|
|
1208
|
+
| STRING | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) |
|
|
1209
|
+
| STRING | all other scopes | _string_ \* |
|
|
1210
|
+
| TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
|
|
1211
|
+
| EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
|
|
1212
|
+
|
|
1213
|
+
\* 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).
|
|
1174
1214
|
|
|
1175
1215
|
\*\* 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.
|
|
1176
1216
|
|
|
@@ -1208,12 +1248,12 @@ In order to validate types, the plugin uses the [Design Tokens types](https://gi
|
|
|
1208
1248
|
|
|
1209
1249
|
---
|
|
1210
1250
|
|
|
1211
|
-
## Scopes
|
|
1251
|
+
## Scopes limitations
|
|
1212
1252
|
|
|
1213
|
-
|
|
1253
|
+
Figma variables have no font weight or opacity type, so the plugin reads the variable's scopes to pick the token type:
|
|
1214
1254
|
|
|
1215
|
-
- `FONT_WEIGHT` scope
|
|
1216
|
-
- `OPACITY`
|
|
1255
|
+
- 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`.
|
|
1256
|
+
- 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](#use-percentage-for-opacity) is enabled. With any other scope next to them, it is exported as a `dimension`.
|
|
1217
1257
|
|
|
1218
1258
|
---
|
|
1219
1259
|
|
|
@@ -17,6 +17,24 @@
|
|
|
17
17
|
{ "modeId": "2:1", "name": "Dark" }
|
|
18
18
|
],
|
|
19
19
|
"variableIds": ["VariableID:2:2", "VariableID:2:3"]
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
"id": "VariableCollectionId:3:1",
|
|
23
|
+
"name": "Campaign",
|
|
24
|
+
"defaultModeId": "3:0",
|
|
25
|
+
"isExtension": true,
|
|
26
|
+
"parentVariableCollectionId": "VariableCollectionId:2:1",
|
|
27
|
+
"rootVariableCollectionId": "VariableCollectionId:2:1",
|
|
28
|
+
"modes": [
|
|
29
|
+
{ "modeId": "3:0", "name": "Light", "parentModeId": "2:0" },
|
|
30
|
+
{ "modeId": "3:1", "name": "Dark", "parentModeId": "2:1" }
|
|
31
|
+
],
|
|
32
|
+
"variableIds": ["VariableID:2:2", "VariableID:2:3"],
|
|
33
|
+
"variableOverrides": {
|
|
34
|
+
"VariableID:2:2": {
|
|
35
|
+
"3:0": { "r": 0.9, "g": 0.3, "b": 0.2, "a": 1 }
|
|
36
|
+
}
|
|
37
|
+
}
|
|
20
38
|
}
|
|
21
39
|
],
|
|
22
40
|
"variables": [
|
|
@@ -70,13 +88,12 @@
|
|
|
70
88
|
"name": "surface/accent-muted",
|
|
71
89
|
"variableCollectionId": "VariableCollectionId:2:1",
|
|
72
90
|
"resolvedType": "COLOR",
|
|
73
|
-
"description": "Blue primitive with an opacity applied on top",
|
|
91
|
+
"description": "Blue primitive with an opacity applied on top. Light uses the current { color, opacity } shape, Dark the COMPOSE_COLOR expression of older Figma Desktop builds",
|
|
74
92
|
"remote": false,
|
|
75
93
|
"valuesByMode": {
|
|
76
94
|
"2:0": {
|
|
77
|
-
"type": "
|
|
78
|
-
"
|
|
79
|
-
"expressionArguments": [{ "type": "VARIABLE_ALIAS", "id": "VariableID:1:2" }, 50]
|
|
95
|
+
"color": { "type": "VARIABLE_ALIAS", "id": "VariableID:1:2" },
|
|
96
|
+
"opacity": 50
|
|
80
97
|
},
|
|
81
98
|
"2:1": {
|
|
82
99
|
"type": "VARIABLE_EXPRESSION",
|
package/llms.txt
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> Figma plugin + CLI that exports Figma variables and styles as DTCG 2025.10 design tokens JSON. The CLI (`npx tokens-bruecke`) either fetches variables via the Figma REST API (requires a Figma Enterprise plan) or transforms a local snapshot passed with `--input`, and writes tokens to a file or stdout.
|
|
4
4
|
|
|
5
|
-
Set up a config file: `npx tokens-bruecke init` (asks 4 questions; `init -y` writes defaults, and it
|
|
5
|
+
Set up a config file: `npx tokens-bruecke init` (asks 4 questions; `init -y` writes defaults, and it only prompts when both stdin and stdout are terminals). The export never loads the config on its own: pass it with `-c tokens-bruecke.config.json`.
|
|
6
6
|
|
|
7
7
|
Quick CLI usage:
|
|
8
8
|
`npx tokens-bruecke --api-key "$FIGMA_TOKEN" --file-key <FILE_KEY> --output tokens.json`
|
package/package.json
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
},
|
|
13
13
|
"includedStyles": {
|
|
14
14
|
"type": "object",
|
|
15
|
-
"description": "Which Figma styles to include in the export, and the token group name for each.",
|
|
15
|
+
"description": "Which Figma styles to include in the export, and the token group name for each. Setting this replaces the whole default object (the config is merged one level deep), so give every included style type a customName.",
|
|
16
16
|
"additionalProperties": false,
|
|
17
17
|
"properties": {
|
|
18
18
|
"text": { "$ref": "#/definitions/styleInclusion" },
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
"includeFigmaMetaData": {
|
|
65
65
|
"type": "boolean",
|
|
66
66
|
"default": false,
|
|
67
|
-
"description": "
|
|
67
|
+
"description": "Add $extensions.figma to every variable token: variableId, codeSyntax and the collection (id, name, defaultModeId). Styles are not affected."
|
|
68
68
|
},
|
|
69
69
|
"usePercentageOpacity": {
|
|
70
70
|
"type": "boolean",
|
|
@@ -105,7 +105,7 @@
|
|
|
105
105
|
},
|
|
106
106
|
"customName": {
|
|
107
107
|
"type": "string",
|
|
108
|
-
"description": "Token group name used for this style type in the output."
|
|
108
|
+
"description": "Token group name used for this style type in the output. Set it whenever isIncluded is true: without it the group is exported under the key \"undefined\"."
|
|
109
109
|
}
|
|
110
110
|
}
|
|
111
111
|
}
|
|
@@ -62,7 +62,11 @@
|
|
|
62
62
|
"required": ["modeId", "name"],
|
|
63
63
|
"properties": {
|
|
64
64
|
"modeId": { "type": "string" },
|
|
65
|
-
"name": { "type": "string" }
|
|
65
|
+
"name": { "type": "string" },
|
|
66
|
+
"parentModeId": {
|
|
67
|
+
"type": "string",
|
|
68
|
+
"description": "Extended collections only: the parent collection's mode this mode inherits from. When missing, the mode is matched by name, then by position."
|
|
69
|
+
}
|
|
66
70
|
}
|
|
67
71
|
}
|
|
68
72
|
},
|
|
@@ -72,8 +76,28 @@
|
|
|
72
76
|
},
|
|
73
77
|
"variableIds": {
|
|
74
78
|
"type": "array",
|
|
75
|
-
"description": "Variable ids in the order shown in Figma's Variables panel. Preserves token ordering in the output; without it, output order follows the variables array.",
|
|
79
|
+
"description": "Variable ids in the order shown in Figma's Variables panel. Preserves token ordering in the output; without it, output order follows the variables array. Required for extended collections: it is the only thing that lists their variables (which belong to the root collection), so an extension without it exports empty.",
|
|
76
80
|
"items": { "type": "string" }
|
|
81
|
+
},
|
|
82
|
+
"isExtension": {
|
|
83
|
+
"type": "boolean",
|
|
84
|
+
"description": "true for a collection made with \"Extend a variable collection\". Exported as its own collection, with the parent's values plus its overrides."
|
|
85
|
+
},
|
|
86
|
+
"parentVariableCollectionId": {
|
|
87
|
+
"type": "string",
|
|
88
|
+
"description": "Extended collections only: id of the collection this one extends. The parent must be in the snapshot."
|
|
89
|
+
},
|
|
90
|
+
"rootVariableCollectionId": {
|
|
91
|
+
"type": "string",
|
|
92
|
+
"description": "Extended collections only: id of the collection at the top of the chain, which owns the variables."
|
|
93
|
+
},
|
|
94
|
+
"variableOverrides": {
|
|
95
|
+
"type": "object",
|
|
96
|
+
"description": "Extended collections only: values this collection overrides, as { variableId: { modeId: value } }. Copy it verbatim from the Plugin API.",
|
|
97
|
+
"additionalProperties": {
|
|
98
|
+
"type": "object",
|
|
99
|
+
"additionalProperties": { "$ref": "#/definitions/variableValue" }
|
|
100
|
+
}
|
|
77
101
|
}
|
|
78
102
|
}
|
|
79
103
|
},
|
|
@@ -109,7 +133,7 @@
|
|
|
109
133
|
},
|
|
110
134
|
"scopes": {
|
|
111
135
|
"type": "array",
|
|
112
|
-
"description": "Figma variable scopes. Emitted
|
|
136
|
+
"description": "Figma variable scopes. Emitted when includeScopes is enabled, and used to refine FLOAT and STRING tokens: FONT_WEIGHT as the only scope gives fontWeight; scopes that are all OPACITY or COLOR_OPACITY give an opacity number. Defaults to an empty array when omitted.",
|
|
113
137
|
"default": [],
|
|
114
138
|
"items": { "type": "string" }
|
|
115
139
|
},
|
|
@@ -118,10 +142,13 @@
|
|
|
118
142
|
"description": "Per-platform code syntax (WEB, ANDROID, iOS). Emitted when includeFigmaMetaData is enabled.",
|
|
119
143
|
"additionalProperties": { "type": "string" }
|
|
120
144
|
},
|
|
121
|
-
"hiddenFromPublishing": {
|
|
145
|
+
"hiddenFromPublishing": {
|
|
146
|
+
"type": "boolean",
|
|
147
|
+
"description": "Not filtered in snapshot mode (REST mode drops collections hidden from publishing). Leave such variables out of the snapshot if you don't want them exported."
|
|
148
|
+
},
|
|
122
149
|
"remote": {
|
|
123
150
|
"type": "boolean",
|
|
124
|
-
"description": "Should be false
|
|
151
|
+
"description": "Should be false. Remote (library) variables are not resolved; aliases to them export as \"#missing#\" unless the variable is also in the snapshot."
|
|
125
152
|
}
|
|
126
153
|
}
|
|
127
154
|
},
|
|
@@ -132,6 +159,7 @@
|
|
|
132
159
|
{ "$ref": "#/definitions/composedColorObject" },
|
|
133
160
|
{ "$ref": "#/definitions/composedColor" },
|
|
134
161
|
{ "$ref": "#/definitions/rgba" },
|
|
162
|
+
{ "$ref": "#/definitions/motionEasing" },
|
|
135
163
|
{ "type": "number" },
|
|
136
164
|
{ "type": "string" },
|
|
137
165
|
{ "type": "boolean" }
|
|
@@ -168,7 +196,7 @@
|
|
|
168
196
|
},
|
|
169
197
|
"composedColor": {
|
|
170
198
|
"type": "object",
|
|
171
|
-
"description": "A color variable that aliases another color and applies its own opacity on top (Figma \"Control opacity at scale\", September 2026), as
|
|
199
|
+
"description": "A color variable that aliases another color and applies its own opacity on top (Figma \"Control opacity at scale\", September 2026), as older Figma Desktop builds (126.x) returned it; current runtimes return composedColorObject. The first argument is the base color (alias or rgba), the second the opacity in percent (0..100) or an alias to a number variable. Exports as `{ components: \"{color.brand}\", alpha: 0.5 }` — see README, \"Color aliases with opacity\".",
|
|
172
200
|
"required": ["type", "expressionFunction", "expressionArguments"],
|
|
173
201
|
"properties": {
|
|
174
202
|
"type": { "const": "VARIABLE_EXPRESSION" },
|
|
@@ -181,19 +209,84 @@
|
|
|
181
209
|
{
|
|
182
210
|
"oneOf": [
|
|
183
211
|
{ "$ref": "#/definitions/variableAlias" },
|
|
184
|
-
{ "$ref": "#/definitions/rgba" }
|
|
212
|
+
{ "$ref": "#/definitions/rgba" },
|
|
213
|
+
{
|
|
214
|
+
"type": "object",
|
|
215
|
+
"description": "The same argument wrapped as VariableData, as the typings describe it.",
|
|
216
|
+
"required": ["value"],
|
|
217
|
+
"properties": {
|
|
218
|
+
"value": {
|
|
219
|
+
"oneOf": [
|
|
220
|
+
{ "$ref": "#/definitions/variableAlias" },
|
|
221
|
+
{ "$ref": "#/definitions/rgba" }
|
|
222
|
+
]
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
185
226
|
]
|
|
186
227
|
},
|
|
187
228
|
{
|
|
188
229
|
"oneOf": [
|
|
189
230
|
{ "$ref": "#/definitions/variableAlias" },
|
|
190
|
-
{ "type": "number", "minimum": 0, "maximum": 100 }
|
|
231
|
+
{ "type": "number", "minimum": 0, "maximum": 100 },
|
|
232
|
+
{
|
|
233
|
+
"type": "object",
|
|
234
|
+
"description": "The same argument wrapped as VariableData, as the typings describe it.",
|
|
235
|
+
"required": ["value"],
|
|
236
|
+
"properties": {
|
|
237
|
+
"value": {
|
|
238
|
+
"oneOf": [
|
|
239
|
+
{ "$ref": "#/definitions/variableAlias" },
|
|
240
|
+
{ "type": "number", "minimum": 0, "maximum": 100 }
|
|
241
|
+
]
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
191
245
|
]
|
|
192
246
|
}
|
|
193
247
|
]
|
|
194
248
|
}
|
|
195
249
|
}
|
|
196
250
|
},
|
|
251
|
+
"motionEasing": {
|
|
252
|
+
"type": "object",
|
|
253
|
+
"description": "EASING variable value, as the Plugin API returns it. Exports as a cubicBezier or a preset name, see README, \"Motion variables\".",
|
|
254
|
+
"required": ["type"],
|
|
255
|
+
"properties": {
|
|
256
|
+
"type": {
|
|
257
|
+
"enum": [
|
|
258
|
+
"EASE_IN",
|
|
259
|
+
"EASE_OUT",
|
|
260
|
+
"EASE_IN_AND_OUT",
|
|
261
|
+
"LINEAR",
|
|
262
|
+
"EASE_IN_BACK",
|
|
263
|
+
"EASE_OUT_BACK",
|
|
264
|
+
"EASE_IN_AND_OUT_BACK",
|
|
265
|
+
"CUSTOM_CUBIC_BEZIER",
|
|
266
|
+
"GENTLE",
|
|
267
|
+
"QUICK",
|
|
268
|
+
"BOUNCY",
|
|
269
|
+
"SLOW",
|
|
270
|
+
"CUSTOM_SPRING",
|
|
271
|
+
"HOLD"
|
|
272
|
+
]
|
|
273
|
+
},
|
|
274
|
+
"easingFunctionCubicBezier": {
|
|
275
|
+
"type": "object",
|
|
276
|
+
"required": ["x1", "y1", "x2", "y2"],
|
|
277
|
+
"properties": {
|
|
278
|
+
"x1": { "type": "number" },
|
|
279
|
+
"y1": { "type": "number" },
|
|
280
|
+
"x2": { "type": "number" },
|
|
281
|
+
"y2": { "type": "number" }
|
|
282
|
+
}
|
|
283
|
+
},
|
|
284
|
+
"easingFunctionSpring": {
|
|
285
|
+
"type": "object",
|
|
286
|
+
"properties": { "bounce": { "type": "number" } }
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
},
|
|
197
290
|
"rgba": {
|
|
198
291
|
"type": "object",
|
|
199
292
|
"description": "Color in 0..1 float channels, as the Plugin API returns it. Alpha defaults to 1 when absent.",
|
|
@@ -57,27 +57,29 @@ npx tokens-bruecke init -y # tokens-bruecke.config.json with defaults
|
|
|
57
57
|
npx tokens-bruecke init -y -p cfg.json --force
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
`init`
|
|
60
|
+
`init` only prompts when both stdin and stdout are terminals, so it will not hang in a pipeline — but passing `-y` makes the intent explicit. Options: `-y/--yes`, `--force` (overwrite an existing file; without it an existing file exits `1`), `-p/--path`.
|
|
61
|
+
|
|
62
|
+
The export never loads `tokens-bruecke.config.json` on its own: always pass it with `-c`.
|
|
61
63
|
|
|
62
64
|
The generated file contains every option at its default plus a `$schema` link. Editing that file directly is usually faster than re-running `init`.
|
|
63
65
|
|
|
64
66
|
## Flags
|
|
65
67
|
|
|
66
|
-
| Flag | Alias | Description
|
|
67
|
-
| ------------------------- | ----- |
|
|
68
|
-
| `--api-key` | `-a` | Figma personal access token (one of api-key/oauth-token required)
|
|
69
|
-
| `--oauth-token` | `-t` | Figma OAuth token
|
|
70
|
-
| `--file-key` | `-f` | Figma file key (required unless `--input`)
|
|
71
|
-
| `--input` | `-i` | Read a local tokens snapshot instead of the REST API; `-` reads stdin
|
|
72
|
-
| `--output` | `-o` | Output file path, or directory when splitting (required unless `--stdout`)
|
|
73
|
-
| `--stdout` | | Print tokens JSON to stdout; mutually exclusive with `--output` and split flags |
|
|
74
|
-
| `--config` | `-c` | Path to a JSON config file (see below)
|
|
75
|
-
| `--split-by-collection` | `-s` | One `{Collection}.tokens.json` file per collection in the output dir
|
|
76
|
-
| `--split-by-mode` | `-m` | One `{Collection}/{Mode}.tokens.json` file per mode
|
|
77
|
-
| `--omit-collection-names` | | Merge all tokens into a single namespace (drop collection groups)
|
|
78
|
-
| `--quiet` | `-q` | Suppress progress logs (errors still printed to stderr)
|
|
79
|
-
| `init` (subcommand) | | Create a config file; pass `-y` in non-interactive contexts
|
|
80
|
-
| `--help` / `--version` | `-h` | Usage / version
|
|
68
|
+
| Flag | Alias | Description |
|
|
69
|
+
| ------------------------- | ----- | --------------------------------------------------------------------------------- |
|
|
70
|
+
| `--api-key` | `-a` | Figma personal access token (one of api-key/oauth-token required) |
|
|
71
|
+
| `--oauth-token` | `-t` | Figma OAuth token |
|
|
72
|
+
| `--file-key` | `-f` | Figma file key (required unless `--input`) |
|
|
73
|
+
| `--input` | `-i` | Read a local tokens snapshot instead of the REST API; `-` reads stdin |
|
|
74
|
+
| `--output` | `-o` | Output file path, or directory when splitting (required unless `--stdout`) |
|
|
75
|
+
| `--stdout` | | Print tokens JSON to stdout; mutually exclusive with `--output` and split flags\* |
|
|
76
|
+
| `--config` | `-c` | Path to a JSON config file (see below) |
|
|
77
|
+
| `--split-by-collection` | `-s` | One `{Collection}.tokens.json` file per collection in the output dir |
|
|
78
|
+
| `--split-by-mode` | `-m` | One `{Collection}/{Mode}.tokens.json` file per mode |
|
|
79
|
+
| `--omit-collection-names` | | Merge all tokens into a single namespace (drop collection groups) |
|
|
80
|
+
| `--quiet` | `-q` | Suppress progress logs (errors still printed to stderr) |
|
|
81
|
+
| `init` (subcommand) | | Create a config file; pass `-y` in non-interactive contexts |
|
|
82
|
+
| `--help` / `--version` | `-h` | Usage / version |
|
|
81
83
|
|
|
82
84
|
Precedence: explicit CLI flags > `FIGMA_*` env vars > config file > defaults.
|
|
83
85
|
|
|
@@ -89,7 +91,9 @@ Precedence: explicit CLI flags > `FIGMA_*` env vars > config file > defaults.
|
|
|
89
91
|
figma-dump-tokens | npx tokens-bruecke --input - --stdout --quiet > tokens.json
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
|
|
94
|
+
\* Only the `--split-*` flags are checked. Keep `splitByCollection` / `splitByMode` off in a config used with `--stdout`, or the CLI prints an internal map of files instead of the tokens.
|
|
95
|
+
|
|
96
|
+
Snapshot mode ignores `FIGMA_API_KEY` / `FIGMA_FILE_KEY` env vars. Passing `--api-key`, `--oauth-token` or `--file-key` explicitly alongside `--input` is an error. Every other flag (`--config`, `--split-by-collection`, `--split-by-mode`, `--omit-collection-names`, `--stdout`) works identically in both modes, and the output has the same shape. One difference: REST mode drops collections hidden from publishing and deleted-but-referenced variables; snapshot mode exports whatever is in the snapshot.
|
|
93
97
|
|
|
94
98
|
### Snapshot shape
|
|
95
99
|
|
|
@@ -142,17 +146,17 @@ Rules that matter:
|
|
|
142
146
|
|
|
143
147
|
- `variables` and `variableCollections` are **required**; the four style arrays are optional and only read when the matching `includedStyles.*.isIncluded` config flag is on.
|
|
144
148
|
- `valuesByMode` is keyed by **`modeId`**, not by mode name. Mode names come from the collection's `modes` array.
|
|
145
|
-
- Aliases are `{ "type": "VARIABLE_ALIAS", "id": "<variable id>" }`. The target variable must be present in the snapshot, otherwise the value exports as `"#missing#"` — the same behaviour as the REST resolver.
|
|
146
|
-
- Color aliases with their own opacity (Figma "Control opacity at scale") are `{ "color": <alias or rgba>, "opacity": <0..100 or alias> }` on current runtimes, or `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }` on older Figma Desktop builds. Pass either through verbatim
|
|
149
|
+
- Aliases are `{ "type": "VARIABLE_ALIAS", "id": "<variable id>" }`. The target variable must be present in the snapshot, otherwise the value exports as `"#missing#"` — the same behaviour as the REST resolver. Leave remote (library) variables and collections out of the snapshot, except a library variable that a local alias points at: add that one to `variables` to keep the alias resolvable.
|
|
150
|
+
- Color aliases with their own opacity (Figma "Control opacity at scale") are `{ "color": <alias or rgba>, "opacity": <0..100 or alias> }` on current runtimes, or `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }` on older Figma Desktop builds. Pass either through verbatim. With an aliased base color they export as `{ "components": "{path.to.color}", "alpha": 0.5 }` (a reference in `alpha` when the opacity is aliased, `"50%"` with `usePercentageOpacity`). With a literal base color and an aliased opacity, the color is written in the configured `colorMode` with the opacity reference in its `alpha` (or `a`). They import back as `{ color, opacity }` (falling back to the expression where only that is accepted).
|
|
147
151
|
- `collection.variableIds` preserves Figma's Variables-panel ordering in the output. Without it, output order follows the `variables` array.
|
|
152
|
+
- Extended collections ("Extend a variable collection") need `isExtension`, `parentVariableCollectionId`, `variableOverrides` (`{ variableId: { modeId: value } }`), `modes[].parentModeId` and `variableIds` copied from the Plugin API. Their variables belong to the root collection, so `variableIds` is the only list of what an extension contains: drop it and the extension exports as an empty group, with no error.
|
|
148
153
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them — not 0..255 and not hex.
|
|
149
|
-
- Filter out remote (library) variables and collections, matching what the REST resolver does.
|
|
150
154
|
|
|
151
155
|
## Config file
|
|
152
156
|
|
|
153
157
|
Optional JSON file passed via `--config`. Schema: [schemas/cli-options.schema.json](../../schemas/cli-options.schema.json). Example: [examples/cli-options.json](../../examples/cli-options.json).
|
|
154
158
|
|
|
155
|
-
Key options (all optional): `includedStyles` (include text/effects/grids/colors styles, default all excluded), `useDTCG` (default `true`, DTCG 2025.10 `$`-keys), `colorMode` (`hex` default; also `rgba-object`, `rgba-css`, `srgb-dtcg`, `hsla-object`, `hsla-css`, `hsl-dtcg`, `oklch-dtcg`), `includeScopes`, `includeFigmaMetaData`, `usePercentageOpacity`, `expandEasingPresets` (default `true`, expands Figma's named easing presets into `cubicBezier` values), `storeStyleInCollection`, `splitByCollection`, `splitByMode`, `omitCollectionNames`.
|
|
159
|
+
Key options (all optional): `includedStyles` (include text/effects/grids/colors styles, default all excluded; setting it replaces the whole default object, so give every included type a `customName` or its group is named `"undefined"`), `useDTCG` (default `true`, DTCG 2025.10 `$`-keys), `colorMode` (`hex` default; also `rgba-object`, `rgba-css`, `srgb-dtcg`, `hsla-object`, `hsla-css`, `hsl-dtcg`, `oklch-dtcg`), `includeScopes`, `includeFigmaMetaData` (adds `$extensions.figma` with `variableId`, `codeSyntax` and the collection to variable tokens), `usePercentageOpacity`, `expandEasingPresets` (default `true`, expands Figma's named easing presets into `cubicBezier` values), `storeStyleInCollection`, `splitByCollection`, `splitByMode`, `omitCollectionNames`.
|
|
156
160
|
|
|
157
161
|
## Output
|
|
158
162
|
|
|
@@ -160,11 +164,13 @@ Key options (all optional): `includedStyles` (include text/effects/grids/colors
|
|
|
160
164
|
- `--split-by-collection`: `{output}/{Collection}.tokens.json` per collection.
|
|
161
165
|
- `--split-by-mode`: `{output}/{Collection}/{Mode}.tokens.json` (unsafe filename chars replaced with `-`).
|
|
162
166
|
- `--stdout`: pure JSON on stdout; all logs on stderr, safe to pipe.
|
|
167
|
+
- Every file gets a top-level `$extensions["tokens-bruecke-meta"]` block with a `createdAt` timestamp, so two runs on the same input are not byte-identical.
|
|
163
168
|
- Format is DTCG only. To convert to CSS/platform outputs, feed the JSON to Style Dictionary or Terrazzo.
|
|
164
169
|
|
|
165
170
|
## Errors & exit codes
|
|
166
171
|
|
|
167
|
-
- Exit `0` on success, `1` on any failure (bad config file, API error, write error).
|
|
172
|
+
- Exit `0` on success, `1` on any failure (bad config file, API error, write error, `init` on an existing file without `--force`).
|
|
173
|
+
- Exit `130` when the `init` prompts are cancelled (`Ctrl+C` / `Esc`); nothing is written.
|
|
168
174
|
- `403` → Enterprise plan or `file_variables:read` scope missing.
|
|
169
175
|
- `404` → wrong `--file-key` or the token has no access to the file.
|
|
170
176
|
- Validation errors (missing/conflicting flags) are printed by yargs with usage help.
|