tokens-bruecke 2.16.4 → 3.3.0

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.
Files changed (12) hide show
  1. package/CHANGELOG.md +170 -15
  2. package/CONTRIBUTING.md +1 -1
  3. package/README.md +120 -37
  4. package/bin/cli.js +1 -1
  5. package/examples/cli-options.json +26 -0
  6. package/global.d.ts +12 -4
  7. package/llms.txt +19 -0
  8. package/manifest.json +1 -1
  9. package/package.json +10 -3
  10. package/readme-assets/fig10.webp +0 -0
  11. package/schemas/cli-options.schema.json +108 -0
  12. package/skills/tokens-bruecke/SKILL.md +65 -0
package/CHANGELOG.md CHANGED
@@ -1,56 +1,211 @@
1
- ## [2.16.1](https://github.com/tokens-bruecke/figma-plugin/compare/v16.0.1...v2.16.1) (2026-05-11)
2
1
  # Changelog
3
2
 
4
- ## [2.11.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.0...v2.11.1) (2026-03-28)
3
+ ## [3.0.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.19.0...v3.0.0) (2026-07-11)
4
+
5
+ ### Features
6
+
7
+ - support DTCG 2025.10 export format ([332882d](https://github.com/tokens-bruecke/figma-plugin/commit/332882dbf95e0aaf792ef4d50f14d1b97d92f5e9))
8
+
9
+ ## [2.19.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.18.4...v2.19.0) (2026-06-29)
10
+
11
+ ### Features
5
12
 
13
+ - add support for DTCG 2025.10 color value objects ([956155c](https://github.com/tokens-bruecke/figma-plugin/commit/956155c02d6b66ba92e7678d6dbbfad58ea5bfc3))
14
+
15
+ ### Bug Fixes
16
+
17
+ - add default case to color format switch ([aa56614](https://github.com/tokens-bruecke/figma-plugin/commit/aa56614e7386d01e76261b4f0c520df6be33a155))
18
+ - drop "Object" from labels ([02fe4f5](https://github.com/tokens-bruecke/figma-plugin/commit/02fe4f586575f8adb896910435cb4d531d77fb34))
6
19
 
7
20
  ### Miscellaneous
8
21
 
9
- * bump version to 2.11.2 ([9983f6a](https://github.com/tokens-bruecke/figma-plugin/commit/9983f6a2939207c85f3f289aa44d38ae64a1f4d1))
22
+ - update README to address changes to font weight ([6133ad5](https://github.com/tokens-bruecke/figma-plugin/commit/6133ad51b2383dc2efe5a134aefbb9e62cb3fd41))
10
23
 
11
- ## [2.11.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.10.0...v2.11.0) (2026-03-28)
24
+ ## [2.18.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.18.3...v2.18.4) (2026-06-25)
25
+
26
+ ### Bug Fixes
27
+
28
+ - correct typo in normalizeRGBAColor module ([b50399b](https://github.com/tokens-bruecke/figma-plugin/commit/b50399bfac4cdaa8d7b370a80087823500810c64))
29
+ - add missing file ([127fdca](https://github.com/tokens-bruecke/figma-plugin/commit/127fdca53338c6df35d7deef2b163c86d2130a1b))
30
+
31
+ ## [2.18.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.18.2...v2.18.3) (2026-06-25)
32
+
33
+ ### Bug Fixes
34
+
35
+ - set type and value properly for font weights ([0f2ca65](https://github.com/tokens-bruecke/figma-plugin/commit/0f2ca652defa57190b3ee35c6e62ec1509e46560))
36
+
37
+ ## [2.18.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.18.1...v2.18.2) (2026-06-11)
38
+
39
+ ### Miscellaneous
40
+
41
+ - change plugin name ([c17a42a](https://github.com/tokens-bruecke/figma-plugin/commit/c17a42a5c3ffa09f4553d1c71411ab3ef9ff0dbd))
42
+
43
+ ## [2.18.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.18.0...v2.18.1) (2026-06-08)
44
+
45
+ ### Bug Fixes
46
+
47
+ - collection key in exported token files ([3a6476f](https://github.com/tokens-bruecke/figma-plugin/commit/3a6476f185579b07e3af2ea650c7bddd758f975e))
12
48
 
49
+ ## [2.18.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.17.0...v2.18.0) (2026-06-07)
13
50
 
14
51
  ### Features
15
52
 
16
- * split collections into separate files on export ([2e7fcff](https://github.com/tokens-bruecke/figma-plugin/commit/2e7fcffa1f65b37a42c1410f5e79a0403d340b5a)), closes [#17](https://github.com/tokens-bruecke/figma-plugin/issues/17)
53
+ - add split-by-mode export option ([e3aeb16](https://github.com/tokens-bruecke/figma-plugin/commit/e3aeb1604ab4acf0a6a52c87144f639faabf6798))
17
54
 
55
+ ## [2.17.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.16.4...v2.17.0) (2026-06-07)
18
56
 
19
57
  ### Miscellaneous
20
58
 
21
- * remove trailing whitespace in release.yml ([a3340cc](https://github.com/tokens-bruecke/figma-plugin/commit/a3340cc815a522dcc84f40ba40dd90395c45c647))
22
- * update README and bump version to 2.11.0 ([9b3a332](https://github.com/tokens-bruecke/figma-plugin/commit/9b3a3325dab53c1852ff2914f98ef587bdee791d))
59
+ - move all settings into a view ([d18bf11](https://github.com/tokens-bruecke/figma-plugin/commit/d18bf11dde0d24c5edb7a2d587e237c78adbd15f))
23
60
 
24
- ## [2.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.4...v2.10.0) (2026-03-28)
61
+ ## [2.16.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.16.3...v2.16.4) (2026-05-21)
62
+
63
+ ### Features
64
+
65
+ - include variable collection names in export metadata ([4b78417](https://github.com/tokens-bruecke/figma-plugin/commit/4b78417a7ba77da676d042d729d4c7435f1eaec0))
66
+
67
+ ## [2.16.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.16.2...v2.16.3) (2026-05-11)
68
+
69
+ ### Bug Fixes
70
+
71
+ - enable useDTCGKeys for CLI ([f2425ea](https://github.com/tokens-bruecke/figma-plugin/commit/f2425eab63e3768157030e298de02a02619595de))
72
+
73
+ ## [2.16.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.16.1...v2.16.2) (2026-05-11)
74
+
75
+ ### Bug Fixes
76
+
77
+ - enable DTCG keys by default ([1cd28ec](https://github.com/tokens-bruecke/figma-plugin/commit/1cd28ec54e5ca1131c93d8a43f567fa60876d769))
78
+
79
+ ### Miscellaneous
80
+
81
+ - **ci:** fix changelog push on release workflow ([43fe0b7](https://github.com/tokens-bruecke/figma-plugin/commit/43fe0b78506fa16e2cec560c2a085ad6af0b47ed))
82
+
83
+ ## [2.16.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.16.0...v2.16.1) (2026-05-11)
84
+
85
+ ### Bug Fixes
86
+
87
+ - create new profile defaults ([3cefa76](https://github.com/tokens-bruecke/figma-plugin/commit/3cefa7643f58fb0c3f44ba87a84bde6083e96c54))
88
+ - drop legacy profile support and fix style inputs ([00e2718](https://github.com/tokens-bruecke/figma-plugin/commit/00e27181ffd7006469039e24836938a29657aa28))
89
+
90
+ ## [2.16.0](https://github.com/tokens-bruecke/figma-plugin/compare/2.15.1...v2.16.0) (2026-05-11)
91
+
92
+ ### Miscellaneous
93
+
94
+ - drop legacy profile support and fix style inputs ([acb8ef5](https://github.com/tokens-bruecke/figma-plugin/commit/acb8ef5e8f303410ad0b30b63fafc455bed84630))
95
+
96
+ ## [2.15.1](https://github.com/tokens-bruecke/figma-plugin/compare/2.15.0...2.15.1) (2026-05-10)
97
+
98
+ ### Miscellaneous
25
99
 
100
+ - swap buttons order ([8b19085](https://github.com/tokens-bruecke/figma-plugin/commit/8b1908519eee5a2003cd03ba422cf1ae691cf66a))
101
+ - update README ([6c6a752](https://github.com/tokens-bruecke/figma-plugin/commit/6c6a752e697c20ea5cd26674b835a0b354aa047c))
102
+
103
+ ## [2.15.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.5...2.15.0) (2026-05-10)
26
104
 
27
105
  ### Features
28
106
 
29
- * Add export/import docs and styles warning ([6446d2a](https://github.com/tokens-bruecke/figma-plugin/commit/6446d2ab117f6e5b9270588b886e6903505f36fe))
30
- * **cli:** add --oauth-token flag to support OAuth authentication ([ccbc16e](https://github.com/tokens-bruecke/figma-plugin/commit/ccbc16e931c653d4a1aa345902aada38c71a0af3))
107
+ - add multiple accounts ([002d972](https://github.com/tokens-bruecke/figma-plugin/commit/002d97293cba7e9fa7fdbba8c579d4e9ab4986f0))
108
+
109
+ ### Bug Fixes
110
+
111
+ - fix multi-profile layout ([3dec5fe](https://github.com/tokens-bruecke/figma-plugin/commit/3dec5fef66b82f28622a43a0f02bfd613fe21bb7))
112
+
113
+ ## [2.14.5](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.4...v2.14.5) (2026-04-26)
114
+
115
+ ### Miscellaneous
31
116
 
117
+ - fix README misalignments and stale URLs in config ([48e68c8](https://github.com/tokens-bruecke/figma-plugin/commit/48e68c88cf1421ce2ef1b41c2719c9cd12dd776e))
118
+
119
+ ## [2.14.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.3...v2.14.4) (2026-04-26)
32
120
 
33
121
  ### Bug Fixes
34
122
 
35
- * import variables ([1d72235](https://github.com/tokens-bruecke/figma-plugin/commit/1d722358b5e714710df3546727fdaba41427c863))
36
- * **normilizeType:** return 'string' instead of 'dimension' for percentage opacity ([52085c6](https://github.com/tokens-bruecke/figma-plugin/commit/52085c63d50809f9a25a86c6fad9a26fbfd67427))
123
+ - **textStyles:** prioritize bound variables for fontWeight and fontStyle ([3d2df3e](https://github.com/tokens-bruecke/figma-plugin/commit/3d2df3e31bc0d14feab747992ef46a17afc47c6b))
124
+
125
+ ## [2.14.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.2...v2.14.3) (2026-04-21)
126
+
127
+ ### Miscellaneous
128
+
129
+ - **ci:** update release workflow ([09c4253](https://github.com/tokens-bruecke/figma-plugin/commit/09c42537d75863128fb9c1713910c8b38378b6cd))
130
+
131
+ ## [2.14.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.1...v2.14.2) (2026-04-21)
132
+
133
+ ### Miscellaneous
134
+
135
+ - add CONTRIBUTING.md ([dd86530](https://github.com/tokens-bruecke/figma-plugin/commit/dd865308c6123a7e63b72296640b67d2f7a24db9))
136
+
137
+ ## [2.14.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.14.0...v2.14.1) (2026-04-19)
138
+
139
+ ### Miscellaneous
140
+
141
+ - add 'omit collection names' option docs ([753fdb9](https://github.com/tokens-bruecke/figma-plugin/commit/753fdb95ef241d135f33193aab2091db1c4fb8be))
142
+
143
+ ## [2.14.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.4...v2.14.0) (2026-04-19)
144
+
145
+ ### Features
146
+
147
+ - add resizable plugin window with drag handle ([3c67366](https://github.com/tokens-bruecke/figma-plugin/commit/3c6736682523a6e7a64aaf633229f673f8582799))
148
+ - add option to omit collection names as top-level groups ([ac7ebd6](https://github.com/tokens-bruecke/figma-plugin/commit/ac7ebd6b47f20f07bf630e08460f03452bf725e6)), closes [#21](https://github.com/tokens-bruecke/figma-plugin/issues/21)
149
+
150
+ ### Miscellaneous
151
+
152
+ - upgrade TypeScript to 6.x and fix type errors ([5980d51](https://github.com/tokens-bruecke/figma-plugin/commit/5980d511508fb731f94c59bfab56fe7ac293ba25))
153
+ - replace relative imports with path aliases ([5fbaaee](https://github.com/tokens-bruecke/figma-plugin/commit/5fbaaee8a9a2a5009ef599794ffb9b43da15cae9))
154
+ - update README link to plugin types ([86aa2e7](https://github.com/tokens-bruecke/figma-plugin/commit/86aa2e72693b0f10371a005e9d144c6f13d403fe))
155
+
156
+ ## [2.11.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.3...v2.11.4) (2026-04-10)
157
+
158
+ ### Features
37
159
 
160
+ - add "scopes" support on import ([f4060ee](https://github.com/tokens-bruecke/figma-plugin/commit/f4060ee4a08568e704942e93ad506d6d97e2e8f3))
38
161
 
39
162
  ### Miscellaneous
40
163
 
41
- * format CHANGELOG ([0e2e4b0](https://github.com/tokens-bruecke/figma-plugin/commit/0e2e4b0e2fe655451c36bdd7e54f2fffbfeb3a46))
164
+ - validate token scopes and add tests ([621a767](https://github.com/tokens-bruecke/figma-plugin/commit/621a767d6f8204ebf969233fd452ac49c79affdc))
165
+
166
+ ## [2.11.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.2...v2.11.3) (2026-03-30)
167
+
168
+ ### Miscellaneous
169
+
170
+ - maintenance release, no user-facing changes
171
+
172
+ ## [2.11.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.1...v2.11.2) (2026-03-30)
173
+
174
+ ### Features
175
+
176
+ - wrap collection tokens under top-level collection name key when splitting by collection ([272175e](https://github.com/tokens-bruecke/figma-plugin/commit/272175e79228daec2e7722a926f775fb5fc151cc))
42
177
 
43
178
  ## [2.11.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.0...v2.11.1) (2026-03-28)
44
179
 
45
180
  ### Bug Fixes
46
181
 
47
- - **normilizeType:** return `string` instead of `dimension` for percentage opacity
182
+ - **normalizeType:** return `string` instead of `dimension` for percentage opacity ([52085c6](https://github.com/tokens-bruecke/figma-plugin/commit/52085c63d50809f9a25a86c6fad9a26fbfd67427))
48
183
 
49
184
  ## [2.11.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.10.0...v2.11.0) (2026-03-28)
50
185
 
51
186
  ### Features
52
187
 
53
- - **cli:** add `--oauth-token` flag to support OAuth authentication ([#65](https://github.com/tokens-bruecke/figma-plugin/issues/65))
188
+ - split collections into separate files on export ([2e7fcff](https://github.com/tokens-bruecke/figma-plugin/commit/2e7fcffa1f65b37a42c1410f5e79a0403d340b5a)), closes [#17](https://github.com/tokens-bruecke/figma-plugin/issues/17)
189
+
190
+ ### Miscellaneous
191
+
192
+ - remove trailing whitespace in release.yml ([a3340cc](https://github.com/tokens-bruecke/figma-plugin/commit/a3340cc815a522dcc84f40ba40dd90395c45c647))
193
+ - update README and bump version to 2.11.0 ([9b3a332](https://github.com/tokens-bruecke/figma-plugin/commit/9b3a3325dab53c1852ff2914f98ef587bdee791d))
194
+
195
+ ## [2.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.4...v2.10.0) (2026-03-28)
196
+
197
+ ### Features
198
+
199
+ - Add export/import docs and styles warning ([6446d2a](https://github.com/tokens-bruecke/figma-plugin/commit/6446d2ab117f6e5b9270588b886e6903505f36fe))
200
+ - **cli:** add --oauth-token flag to support OAuth authentication ([ccbc16e](https://github.com/tokens-bruecke/figma-plugin/commit/ccbc16e931c653d4a1aa345902aada38c71a0af3)), closes [#65](https://github.com/tokens-bruecke/figma-plugin/issues/65)
201
+
202
+ ### Bug Fixes
203
+
204
+ - import variables ([1d72235](https://github.com/tokens-bruecke/figma-plugin/commit/1d722358b5e714710df3546727fdaba41427c863))
205
+
206
+ ### Miscellaneous
207
+
208
+ - format CHANGELOG ([0e2e4b0](https://github.com/tokens-bruecke/figma-plugin/commit/0e2e4b0e2fe655451c36bdd7e54f2fffbfeb3a46))
54
209
 
55
210
  ## [2.9.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.3...v2.9.4) (2026-01-13)
56
211
 
package/CONTRIBUTING.md CHANGED
@@ -1,4 +1,4 @@
1
- # Contributing to TokensBrücke
1
+ # Contributing to TokensBruecke
2
2
 
3
3
  Thanks for taking the time to contribute! Here's everything you need to get started.
4
4
 
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # TokensBrücke — Figma plugin
1
+ # TokensBruecke — Figma plugin
2
2
 
3
3
  <a href="https://www.figma.com/community/plugin/1254538877056388290" target="_blank">
4
4
  <img src="./readme-assets/preview.webp" alt="preview" width="100%">
@@ -6,13 +6,13 @@
6
6
 
7
7
  ## What is this plugin for?
8
8
 
9
- The plugin converts Figma variables into design-tokens JSON that are compatible with the latest [Design Tokens specification](https://design-tokens.github.io/community-group/format/).
9
+ The plugin converts Figma variables into design-tokens JSON that are compatible with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/).
10
10
 
11
11
  ---
12
12
 
13
13
  ## Table of contents
14
14
 
15
- - [TokensBrücke — Figma plugin](#tokensbrücke--figma-plugin)
15
+ - [TokensBruecke — Figma plugin](#tokensbruecke--figma-plugin)
16
16
  - [What is this plugin for?](#what-is-this-plugin-for)
17
17
  - [Table of contents](#table-of-contents)
18
18
  - [How to use](#how-to-use)
@@ -25,16 +25,18 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
25
25
  - [Add styles to](#add-styles-to)
26
26
  - [Include variable scopes](#include-variable-scopes)
27
27
  - [Use percentage for opacity](#use-percentage-for-opacity)
28
- - [Use DTCG keys format](#use-dtcg-keys-format)
28
+ - [DTCG 2025.10 format](#dtcg-202510-format)
29
29
  - [Include `.value` string for aliases](#include-value-string-for-aliases)
30
30
  - [Include Figma metadata](#include-figma-metadata)
31
31
  - [Split collections into separate files](#split-collections-into-separate-files)
32
+ - [Split modes into separate files](#split-modes-into-separate-files)
32
33
  - [Omit collection names](#omit-collection-names)
33
34
  - [Use as cli tool](#use-as-cli-tool)
34
35
  - [Installation](#installation)
35
36
  - [Usage](#usage)
36
37
  - [Options](#options)
37
38
  - [CLI Configuration File](#cli-configuration-file)
39
+ - [For AI agents](#for-ai-agents)
38
40
  - [Push to server](#push-to-server)
39
41
  - [JSONBin](#jsonbin)
40
42
  - [GitHub](#github)
@@ -79,7 +81,7 @@ The plugin supports both **exporting** and **importing** design tokens:
79
81
  #### Export (Variables → JSON)
80
82
 
81
83
  - Click **"Download JSON"** to export your Figma variables as a design tokens JSON file
82
- - The exported file is compatible with the [Design Tokens specification](https://design-tokens.github.io/community-group/format/)
84
+ - The exported file is compatible with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/)
83
85
  - You can also push directly to supported services (JSONBin, GitHub, GitLab, etc.)
84
86
  - The exported tokens can be converted into CSS, JS, and other platform formats using tools like [Terrazzo](https://terrazzo.app/docs/) or [Style Dictionary](https://amzn.github.io/style-dictionary/)
85
87
 
@@ -114,8 +116,11 @@ Allows you to choose the color mode for the generated JSON. Default value is `HE
114
116
  - `HEX` — HEX color format. Could be converted into `HEXA` if the color has an alpha channel.
115
117
  - `RGBA CSS` — RGBA color format in CSS syntax, e.g. `rgba(0, 0, 0, 0.5)`. When alpha is `1`, the output is `rgb(r, g, b)` (no alpha channel).
116
118
  - `RGBA Object` — RGBA color format in object syntax, e.g. `{ r: 0, g: 0, b: 0, a: 0.5 }`.
119
+ - `sRGB DTCG` — sRGB color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#srgb)
117
120
  - `HSLA CSS` — HSLA color format in CSS syntax, e.g. `hsla(0, 0%, 0%, 0.5)`.
118
121
  - `HSLA Object` — HSLA color format in object syntax, e.g. `{ h: 0, s: 0, l: 0, a: 0.5 }`.
122
+ - `HSL DTCG` — HSL color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#hsl)
123
+ - `OKLCH DTCG` — OKLCH color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#oklch)
119
124
 
120
125
  ### Include styles
121
126
 
@@ -169,32 +174,48 @@ Is `off` by default. When enabled, opacity values will be exported as percentage
169
174
  }
170
175
  ```
171
176
 
172
- ### Use DTCG keys format
177
+ ### DTCG 2025.10 format
173
178
 
174
- Is `on` by default. All DTCG keys are prefixed with `$` symbol. Currently many design tokens tools support [DTCG keys format](https://design-tokens.github.io/community-group/format/#character-restrictions).
179
+ Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/):
180
+
181
+ - All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`).
182
+ - 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.
183
+ - `$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`.
184
+ - The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect.
175
185
 
176
186
  ```json
177
- // Without DTCG keys format
187
+ // Off — native Figma format
178
188
  {
179
189
  "button": {
180
190
  "background": {
181
191
  "type": "color",
182
192
  "value": "#000000"
193
+ },
194
+ "height": {
195
+ "type": "dimension",
196
+ "value": "32px"
183
197
  }
184
198
  }
185
199
  }
186
200
 
187
- // With DTCG keys format
201
+ // On — DTCG 2025.10 format
188
202
  {
189
203
  "button": {
190
204
  "background": {
191
205
  "$type": "color",
192
- "$value": "#000000",
206
+ "$value": "#000000"
207
+ },
208
+ "height": {
209
+ "$type": "dimension",
210
+ "$value": { "value": 32, "unit": "px" }
193
211
  }
194
212
  }
195
213
  }
196
214
  ```
197
215
 
216
+ > [!NOTE]
217
+ > Values that have no valid DTCG representation stay as strings even with this setting on: percentage-based `lineHeight`/`letterSpacing` (e.g. `"150%"`) and `"auto"` line height. `blur` and `grid` style tokens are exported with non-spec `$type` values as documented in [Styles support](#styles-support).
218
+
198
219
  ### Include `.value` string for aliases
199
220
 
200
221
  Is `off` by default. Allows you to include `.value` string to the end of the path for aliases. It will be added to the alias string.
@@ -262,6 +283,35 @@ Is `off` by default. When enabled, each Figma variable collection is exported as
262
283
 
263
284
  This is useful when you want to keep component-level token files separate (e.g. `button.tokens.json`, `card.tokens.json`).
264
285
 
286
+ ### Split modes into separate files
287
+
288
+ Is `off` by default. When enabled, each mode of a variable collection is exported as its own file. The top-level key in each file is the collection name, and every token's value is resolved for that mode.
289
+
290
+ - **Download JSON** — produces a `design.tokens.zip` archive containing one `{CollectionName}/{ModeName}.tokens.json` per mode.
291
+ - **CLI** — writes individual `{CollectionName}/{ModeName}.tokens.json` files into the directory specified by `--output`.
292
+
293
+ Collections with a single mode are exported as a single `{CollectionName}.tokens.json` file.
294
+
295
+ For example, a collection `color` with modes `light` and `dark` produces `color/light.tokens.json` and `color/dark.tokens.json`:
296
+
297
+ ```json
298
+ // color/light.tokens.json
299
+ {
300
+ "color": {
301
+ "primary": { "$type": "color", "$value": "#ffffff" }
302
+ }
303
+ }
304
+
305
+ // color/dark.tokens.json
306
+ {
307
+ "color": {
308
+ "primary": { "$type": "color", "$value": "#000000" }
309
+ }
310
+ }
311
+ ```
312
+
313
+ This is useful for generating a [resolver.json](https://www.designtokens.org/tr/drafts/resolver/) file that references per-mode token files.
314
+
265
315
  ### Omit collection names
266
316
 
267
317
  Is `off` by default. When enabled, the plugin drops the top-level collection name from the output and merges all variables into a single flat namespace (variables are still grouped by the `/` separator in their names).
@@ -337,15 +387,26 @@ This will fetch figma variables and export them in `out/tokens.json`
337
387
 
338
388
  ### Options
339
389
 
340
- | Option | Alias | Description | Required |
341
- | ------------------------- | ----- | ------------------------------------------------------------------------------- | ------------------------------------------------- |
342
- | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token` is required |
343
- | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token` is required |
344
- | `--file-key` | `-f` | Figma file key | Yes |
345
- | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` | Yes |
346
- | `--config` | `-c` | Path to configuration file | No |
347
- | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
348
- | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
390
+ | Option | Alias | Description | Required |
391
+ | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
392
+ | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token` is required |
393
+ | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token` is required |
394
+ | `--file-key` | `-f` | Figma file key | Yes |
395
+ | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
396
+ | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
397
+ | `--config` | `-c` | Path to configuration file | No |
398
+ | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
399
+ | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
400
+ | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
401
+ | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
402
+ | `--help` | `-h` | Show usage help | No |
403
+ | `--version` | | Show the CLI version | No |
404
+
405
+ Progress logs are printed to **stderr**, so stdout stays clean for piping:
406
+
407
+ ```bash
408
+ tokens-bruecke -a $FIGMA_TOKEN -f $FIGMA_FILE --stdout --quiet | jq .
409
+ ```
349
410
 
350
411
  > [!TIP]
351
412
  > For automated pipelines, `--oauth-token` is preferred over `--api-key`. Personal Access Tokens expire every 90 days and require manual renewal, while OAuth tokens support programmatic refresh for indefinite access.
@@ -365,18 +426,32 @@ You can use a JSON configuration file to specify the export options for the CLI.
365
426
  "colors": { "isIncluded": false, "customName": "colors" }
366
427
  },
367
428
  "includeScopes": true,
368
- "useDTCGKeys": true,
429
+ "useDTCG": true, // DTCG 2025.10 format: $-prefixed keys, dimension objects, spec-valid types
369
430
  "includeValueStringKeyToAlias": true,
370
431
  "includeFigmaMetaData": false, // Include Figma metadata like styleId, variableId, etc.
371
432
  "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
372
- "colorMode": "hex", // "hex" | "rgba-object" | "rgba-css" | "hsla-object" | "hsla-css";
433
+ "colorMode": "hex", // "hex" | "rgba-object" | "srgb-dtcg" | "rgba-css" | "hsla-object" | "hsl-dtcg" | "hsla-css" | "oklch-dtcg";
373
434
  "storeStyleInCollection": "none", // Name of one of your collection or "none" to keep them separated
374
435
  "splitByCollection": false, // Write each collection as a separate .tokens.json file
436
+ "splitByMode": false, // Write each mode as a separate .tokens.json file under its collection directory
375
437
  "omitCollectionNames": false // Drop top-level collection names and merge all variables into one flat namespace
376
438
  }
377
439
  ```
378
440
 
379
- Save this JSON file and pass it to the CLI using the `--config` option:
441
+ Save this JSON file and pass it to the CLI using the `--config` option. A JSON schema with all options, types and defaults is available at [schemas/cli-options.schema.json](schemas/cli-options.schema.json) — reference it via a `$schema` key for editor validation and autocompletion (see [examples/cli-options.json](examples/cli-options.json)).
442
+
443
+ > [!NOTE]
444
+ > Explicit CLI flags (e.g. `--split-by-collection`) override values from the config file, which override the defaults.
445
+
446
+ ### For AI agents
447
+
448
+ This repository and the npm package ship agent-friendly docs:
449
+
450
+ - [llms.txt](llms.txt) — entry point for LLM-based tools
451
+ - [skills/tokens-bruecke/SKILL.md](skills/tokens-bruecke/SKILL.md) — an [agent skill](https://code.visualstudio.com/docs/copilot/customization/agent-skills) covering CLI usage, auth, config and exit codes; copy the `skills/tokens-bruecke` folder into your project's skills directory to teach your agent the CLI
452
+ - [schemas/cli-options.schema.json](schemas/cli-options.schema.json) — machine-readable config schema
453
+
454
+ For scripted/agent usage prefer `--stdout --quiet` (pure JSON on stdout, logs on stderr) and pass tokens via environment variables.
380
455
 
381
456
  ---
382
457
 
@@ -438,7 +513,15 @@ There is a possibilty to connect a custom server. In order to do that you need t
438
513
 
439
514
  ## Show output
440
515
 
441
- If you want to see the generated JSON, you can enable the `Show output` option. The plugin will show the JSON in the sidebar. The output doesn't update automatically, in order to optimize the performance. So, if you want to see the updated JSON, you need to click the `Update` button.
516
+ If you want to see the generated JSON, you can enable the `Show output` option. The plugin will show the JSON in a code preview sidebar with:
517
+
518
+ - Syntax highlighting that matches the Figma theme
519
+ - Line numbers and code folding for collapsing groups
520
+ - Search with match highlighting
521
+ - A `Copy` button to copy the whole JSON to the clipboard
522
+ - A stats bar showing the number of tokens, groups, lines, and the file size
523
+
524
+ The output doesn't update automatically, in order to optimize the performance. So, if you want to see the updated JSON, you need to click the `Update` button.
442
525
 
443
526
  ![fig.10](readme-assets/fig10.webp)
444
527
 
@@ -765,21 +848,21 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
765
848
 
766
849
  ## Variables types conversion
767
850
 
768
- Unlike design tokens, Figma variables now [support only 4 types](https://www.figma.com/plugin-docs/api/VariableResolvedDataType) — `COLOR`, `BOOLEAN`, `FLOAT` and `STRING`. So, the plugin converts them into the corresponding types from the [Design Tokens specification](https://design-tokens.github.io/community-group/format/#types).
851
+ Unlike design tokens, Figma variables now [support only 4 types](https://www.figma.com/plugin-docs/api/VariableResolvedDataType) — `COLOR`, `BOOLEAN`, `FLOAT` and `STRING`. So, the plugin converts them into the corresponding types from the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/#types).
769
852
 
770
- | Figma type | Scope condition | Design Tokens type |
771
- | ---------- | ------------------------ | ----------------------------------------------------------------------------------- |
772
- | COLOR | — | [color](https://design-tokens.github.io/community-group/format/#color) |
773
- | BOOLEAN | — | _boolean_ \* |
774
- | FLOAT | `FONT_WEIGHT` scope | _string_ \* |
775
- | FLOAT | `OPACITY` scope (no %) | _number_ \* |
776
- | FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
777
- | FLOAT | all other scopes | [dimension](https://design-tokens.github.io/community-group/format/#dimension) \*\* |
778
- | STRING | — | _string_ \* |
853
+ | Figma type | Scope condition | Design Tokens type |
854
+ | ---------- | ------------------------ | ---------------------------------------------------------------------------- |
855
+ | COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
856
+ | BOOLEAN | — | _boolean_ \* |
857
+ | FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \* |
858
+ | FLOAT | `OPACITY` scope (no %) | _number_ \* |
859
+ | FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
860
+ | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
861
+ | STRING | — | _string_ \* |
779
862
 
780
- \* native JSON types. The specification doesn't restrict the type of the value, so it could be any JSON type. Also see [this issue](https://github.com/design-tokens/community-group/issues/120#issuecomment-1279527414).
863
+ \* 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).
781
864
 
782
- \*\* Figma currently supports only `FLOAT` for numeric values used as dimensions, which map to `px` units. The plugin appends `px` to produce a valid dimension token.
865
+ \*\* 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.
783
866
 
784
867
  ---
785
868
 
@@ -791,9 +874,9 @@ In order to validate types, the plugin uses the [Design Tokens types](https://gi
791
874
 
792
875
  ## Scopes lemitations
793
876
 
794
- In order to convert `FONT-WEIGHT` and `OPACITY` types into valid values you should specify thme as scopes in the Figma variables. The plugin will read the first scope and convert it into the valid value. If there are multiple scopes, the plugin will take the first one.
877
+ 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.
795
878
 
796
- - `FONT_WEIGHT` scope will be converted into `string` type.
879
+ - `FONT_WEIGHT` scope will be converted into `fontWeight` type.
797
880
  - `OPACITY` scope will be converted into `number` type (or `string` with `%` if "Use percentage for opacity" is enabled).
798
881
 
799
882
  ---