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 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 `Shadow` and `Blur` styles support](#multiple-shadow-and-blur-styles-support)
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 lemitations](#scopes-lemitations)
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 on of the [supported services](#link).
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 JSON"** to import design tokens from a JSON file back into Figma
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 various color formats (HEX, RGBA CSS, RGBA Object)
111
- - ✅ Preserves variable descriptions and metadata
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 or variables. Figma's variable API currently only supports basic types: `color`, `number`, `string`, `boolean`, `dimension`, `duration` and `cubicBezier`. Complex style types will be imported as `STRING` variables without proper value conversion. This is a temporary limitation until Figma supports these types natively in their API.
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
  ![fig.4](readme-assets/fig4.webp)
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 with the `OPACITY` scope.
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 | Required |
519
- | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
520
- | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
521
- | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
522
- | `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
523
- | `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
524
- | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
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 | No |
527
- | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
528
- | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
529
- | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
530
- | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
531
- | `--help` | `-h` | Show usage help | No |
532
- | `--version` | | Show the CLI version | No |
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, // Include Figma metadata like styleId, variableId, etc.
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) => ({ modeId: m.modeId, name: m.name })),
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
  ![fig.5](readme-assets/fig5.webp)
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 ordere to test if your credentials are valid you can make a test request by clicking the `Push to server` button (fig.6).
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
  ![fig.6](readme-assets/fig6.webp)
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
- All the steps are the same as for the [GitHub](#github) server, except the last two.
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
  ![fig.12](readme-assets/fig12.webp)
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 possibilty to connect a custom server. In order to do that you need to specify a URL, a method (by default it's `POST`) and headers.
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
  ![fig.9](readme-assets/fig9.webp)
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
- "inset": false,
940
- "color": "#0000000a",
941
- "offsetX": "0px",
942
- "offsetY": "10px",
943
- "blur": "10px",
944
- "spread": "-5px"
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 `Shadow` and `Blur` styles support
1012
+ ### Multiple shadows support
974
1013
 
975
- If the style has multiple `Shadow` or `Blur` styles, the plugin will add them into the array.
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 — the plugin wouldn't include it in a generated JSON.
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 | Design Tokens type |
1162
- | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
1163
- | COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
1164
- | BOOLEAN | — | _boolean_ \* |
1165
- | FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \* |
1166
- | FLOAT | `OPACITY` scope (no %) | _number_ \* |
1167
- | FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
1168
- | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
1169
- | STRING | — | _string_ \* |
1170
- | TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
1171
- | EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
1172
-
1173
- \* native JSON types — not part of the closed DTCG 2025.10 type set. With the [DTCG 2025.10 format](#dtcg-202510-format) setting on, `$type` is omitted for `string`/`boolean` tokens and the original Figma type is preserved under `$extensions.figmaType`. Also see [this issue](https://github.com/design-tokens/community-group/issues/120#issuecomment-1279527414).
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 lemitations
1251
+ ## Scopes limitations
1212
1252
 
1213
- In order to convert `FONT-WEIGHT` and `OPACITY` types into valid values you should specify them as scopes in the Figma variables. The plugin will read the first scope and convert it into the valid value. If there are multiple scopes, the plugin will take the first one.
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 will be converted into `fontWeight` type.
1216
- - `OPACITY` scope will be converted into `number` type (or `string` with `%` if "Use percentage for opacity" is enabled).
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": "VARIABLE_EXPRESSION",
78
- "expressionFunction": "COMPOSE_COLOR",
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 never prompts when stdin is not a TTY).
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tokens-bruecke",
3
- "version": "3.14.0",
3
+ "version": "3.14.1",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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": "Include Figma-specific metadata (variable ids, collection ids) in $extensions[\"tokens-bruecke-meta\"]."
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 in $extensions when includeScopes is enabled, and used to refine FLOAT tokens (e.g. FONT_WEIGHT, OPACITY). Defaults to an empty array when omitted.",
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": { "type": "boolean" },
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 — remote (library) variables are expected to be filtered out of the snapshot."
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 the Plugin API returns it. 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\".",
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` also detects a non-TTY stdin and skips the prompts automatically, so it will not hang in a pipeline — but passing `-y` makes the intent explicit. Options: `-y/--yes`, `--force` (overwrite an existing file), `-p/--path`.
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
- 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 is byte-for-byte the same shape.
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. Library (remote) variables are not resolvable today; include them in `variables` if you need them aliased.
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; they export as `{ "components": "{path.to.color}", "alpha": 0.5 }` (or a reference in `alpha`), and import back as `{ color, opacity }` (falling back to the expression where only that is accepted).
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.