tokens-bruecke 3.21.0 → 3.22.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.
- package/CHANGELOG.md +41 -0
- package/README.md +18 -10
- package/bin/api.js +1 -1
- package/bin/api.js.LICENSE.txt +8 -0
- package/bin/api.mjs +1 -1
- package/bin/api.mjs.LICENSE.txt +8 -0
- package/bin/cli.js +1 -1
- package/bin/cli.js.LICENSE.txt +8 -0
- package/global.d.ts +5 -0
- package/package.json +1 -1
- package/schemas/tokens-snapshot.schema.json +4 -4
- package/skills/tokens-bruecke/SKILL.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,44 @@
|
|
|
1
|
+
## [3.22.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.21.0...v3.22.0) (2026-10-28)
|
|
2
|
+
|
|
3
|
+
### Behaviour changes
|
|
4
|
+
|
|
5
|
+
- **export:** with DTCG on, a variable named like a group of other variables (`border/brand` next to `border/brand/subtle`) becomes the group's `$root` token, and aliases to it end in `.$root` (DTCG 2025.10 §6.2). The import reads both this and the old shape.
|
|
6
|
+
- **export:** `.`, `{` and `}` in a collection name become `-` in its token key (`1. Primitives` → `1- Primitives`), with a warning. The meta keeps the Figma name, so the import maps it back.
|
|
7
|
+
- **export:** the `hex` fallback of DTCG color objects has 6 digits; the opacity is only in `alpha`. The import still reads 8-digit values.
|
|
8
|
+
- **export:** opacity tokens carry `$extensions.figmaScopes` when `includeScopes` is off, so they import as percentages again.
|
|
9
|
+
- **cli:** REST mode exports collections hidden from publishing, as the plugin does.
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
- **export:** fix export, import and REST-mode issues found in real files ([#135](https://github.com/tokens-bruecke/figma-plugin/issues/135)) ([6fe1936](https://github.com/tokens-bruecke/figma-plugin/commit/6fe1936d5b038a69d41cd74dbb41092ee9eb1fa9))
|
|
14
|
+
|
|
15
|
+
Thanks to [@skraegelin](https://github.com/skraegelin) for [#135](https://github.com/tokens-bruecke/figma-plugin/pull/135).
|
|
16
|
+
|
|
17
|
+
## [3.21.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.20.0...v3.21.0) (2026-10-27)
|
|
18
|
+
|
|
19
|
+
### Features
|
|
20
|
+
|
|
21
|
+
- **api:** keep warnings out of the console, with an onWarning option ([869cc51](https://github.com/tokens-bruecke/figma-plugin/commit/869cc51c5134b105126edf1f3f8ad49f62de0dd2))
|
|
22
|
+
|
|
23
|
+
### Behaviour changes
|
|
24
|
+
|
|
25
|
+
- **api:** `tokens-bruecke/api` no longer prints export warnings (skipped variables and styles, aliases to missing variables, name collisions) to the console. Pass `onWarning` to receive them: `fetchTokens({ …, onWarning })` or `convertTokens(input, options, { onWarning })`. The CLI and the plugin still print them.
|
|
26
|
+
|
|
27
|
+
### Bug Fixes
|
|
28
|
+
|
|
29
|
+
- **cli:** export an alias into a hidden collection as `#missing#` ([8f1ac2d](https://github.com/tokens-bruecke/figma-plugin/commit/8f1ac2d2220d4f613223aa08513652bef7baa8ca))
|
|
30
|
+
- export bound shadow blur as an alias ([688d568](https://github.com/tokens-bruecke/figma-plugin/commit/688d5684f12e13c9ee47e3ad44c9dc52d36263d0))
|
|
31
|
+
- **export:** keep styles separate when their collection is missing ([7249e82](https://github.com/tokens-bruecke/figma-plugin/commit/7249e8239f2d1c9b633b85039bc13baf6788141a))
|
|
32
|
+
- **export:** leave the collection out of style aliases with omitCollectionNames ([5346526](https://github.com/tokens-bruecke/figma-plugin/commit/534652616d70549a694b9e8ea4b4c3cb21010d29))
|
|
33
|
+
- **export:** skip styles that cannot be exported instead of failing ([fdeb4f3](https://github.com/tokens-bruecke/figma-plugin/commit/fdeb4f36599d46d580293f405fbd17fce93504a5))
|
|
34
|
+
- **import:** resolve names with dots and skip tokens of another type ([3692fd7](https://github.com/tokens-bruecke/figma-plugin/commit/3692fd7b17d272b0afc53603f27b43d945804756))
|
|
35
|
+
- **import:** write opacity into an existing opacity variable as percent ([3eae585](https://github.com/tokens-bruecke/figma-plugin/commit/3eae5856d719356d0d4bf39e36f9f3202e35b04c))
|
|
36
|
+
- **plugin:** accept GitLab hosts with a scheme and owners with subgroups ([f68988f](https://github.com/tokens-bruecke/figma-plugin/commit/f68988fd9c52b43ea659e868e0b344a46d75d56f))
|
|
37
|
+
- **plugin:** fill "Add styles to" with the open file's collections ([da444f0](https://github.com/tokens-bruecke/figma-plugin/commit/da444f06543c33f74cd42ac3838d608c363d9011))
|
|
38
|
+
- **plugin:** report export, import and push errors in the UI ([ff510fe](https://github.com/tokens-bruecke/figma-plugin/commit/ff510fed70754d77612962634e160ed7936e966b))
|
|
39
|
+
|
|
40
|
+
Thanks to [@skraegelin](https://github.com/skraegelin), whose fork these fixes come from ([#132](https://github.com/tokens-bruecke/figma-plugin/pull/132)).
|
|
41
|
+
|
|
1
42
|
## [3.20.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.19.0...v3.20.0) (2026-10-18)
|
|
2
43
|
|
|
3
44
|
### Features
|
package/README.md
CHANGED
|
@@ -116,10 +116,12 @@ The plugin supports both **exporting** and **importing** design tokens:
|
|
|
116
116
|
|
|
117
117
|
**What to know before importing:**
|
|
118
118
|
|
|
119
|
-
-
|
|
119
|
+
- Tokens without their own `$type` take it from the closest group, as DTCG allows; an alias without a type takes the type of the token it references.
|
|
120
|
+
- Every top-level key becomes a collection. Files exported with [Omit collection names](#omit-collection-names) don't map back to the original collections.
|
|
121
|
+
- A file of a [split-by-mode export](#split-modes-into-separate-files) carries its mode in the meta, so its values go into that mode of the collection, which is added if it's missing. Import the files one by one; the first one imported into a new collection becomes its default mode.
|
|
120
122
|
- An existing collection's first mode is renamed to the first mode in the tokens.
|
|
121
123
|
- Units are dropped from dimensions, since Figma number variables have no unit: `1rem` imports as `1`.
|
|
122
|
-
- Extended collections are imported as regular collections.
|
|
124
|
+
- Extended collections are imported as regular collections when they don't exist in the file yet. If the extended collection exists, its tokens update the variables it inherits: the values become overrides for its modes. New variables and modes can't be added to an extended collection, so those tokens are reported as errors.
|
|
123
125
|
- An existing variable keeps its type. A token of another type, for example a `dimension` token for a color variable, is skipped and listed in the import result.
|
|
124
126
|
|
|
125
127
|
> [!WARNING]
|
|
@@ -142,6 +144,8 @@ Allows you to choose the color mode for the generated JSON. Default value is `HE
|
|
|
142
144
|
- `HSL DTCG` — HSL color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#hsl)
|
|
143
145
|
- `OKLCH DTCG` — OKLCH color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#oklch)
|
|
144
146
|
|
|
147
|
+
The DTCG color objects carry the opacity in `alpha` and a 6-digit `hex` fallback, as the specification requires. Older exports wrote an 8-digit `hex` for translucent colors; the import reads both.
|
|
148
|
+
|
|
145
149
|
### Include styles
|
|
146
150
|
|
|
147
151
|
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.
|
|
@@ -230,6 +234,7 @@ Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](http
|
|
|
230
234
|
- All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`).
|
|
231
235
|
- 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.
|
|
232
236
|
- The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect.
|
|
237
|
+
- A variable named like a group of other variables (`border/brand` next to `border/brand/subtle`) becomes the group's root token per DTCG 2025.10 §6.2: `border.brand.$root`. References to it point at `{….border.brand.$root}`. With the format off, the token and the group share one object, as before. The import reads both shapes.
|
|
233
238
|
|
|
234
239
|
```json
|
|
235
240
|
// Off — native Figma format
|
|
@@ -568,6 +573,8 @@ The REST API returns variables, collections and styles in no fixed order, so the
|
|
|
568
573
|
|
|
569
574
|
In REST mode the CLI exports the file's own styles, published or not, the same set the plugin exports. This also works for a branch, which can't publish styles. Styles that come from a library are left out, as in the plugin.
|
|
570
575
|
|
|
576
|
+
The REST API reports letter spacing in pixels only, so a text style with percentage letter spacing exports as `{ "value": -0.32, "unit": "px" }` in REST mode, where the plugin writes `"-2%"`. Snapshot mode keeps the plugin's unit.
|
|
577
|
+
|
|
571
578
|
### Snapshot input
|
|
572
579
|
|
|
573
580
|
`--input <path>` transforms a local JSON snapshot of a Figma file's variables and styles instead of calling the REST API. `--input -` reads stdin, so it composes with anything that can dump the data:
|
|
@@ -607,7 +614,6 @@ Things worth knowing when building a snapshot:
|
|
|
607
614
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
608
615
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
609
616
|
- [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.
|
|
610
|
-
- Unlike REST mode, snapshot mode doesn't drop collections hidden from publishing. Leave out anything you don't want exported.
|
|
611
617
|
- 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.
|
|
612
618
|
- 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).
|
|
613
619
|
|
|
@@ -747,7 +753,7 @@ Snapshot mode ignores `FIGMA_API_KEY` / `FIGMA_FILE_KEY`, so a token exported in
|
|
|
747
753
|
On a bad snapshot the CLI exits `1` and names the offending key — for example `variables[3] is missing a string "variableCollectionId"` — so an agent can correct its dump and retry without guesswork.
|
|
748
754
|
|
|
749
755
|
> [!NOTE]
|
|
750
|
-
> Aliases pointing at variables outside the snapshot
|
|
756
|
+
> Aliases pointing at variables outside the snapshot export as `"#missing#"`. To resolve aliases to library variables from another file, include those variables in the `variables` array and their collections in `variableCollections`, with `"remote": true`: they resolve the aliases, as in the plugin and in REST mode, but aren't exported.
|
|
751
757
|
|
|
752
758
|
---
|
|
753
759
|
|
|
@@ -791,7 +797,7 @@ for (const [key, tree] of Object.entries(tokens)) {
|
|
|
791
797
|
```
|
|
792
798
|
|
|
793
799
|
- **Aliases** inside a tree are qualified with the collection name (for example `{Semantic.spacing.md}`), so the tree has to be wrapped in `{ [collection]: tree }` for references to resolve.
|
|
794
|
-
- **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names.
|
|
800
|
+
- **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are, except that `.`, `{` and `}` in a collection name become `-` (`1. Primitives` is keyed as `1- Primitives`), because references use them. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names. Match the key against the collection names in `$extensions["tokens-bruecke-meta"].variableCollections`, with those characters replaced, instead, as the CLI does.
|
|
795
801
|
|
|
796
802
|
---
|
|
797
803
|
|
|
@@ -954,7 +960,7 @@ A style the plugin can't export, such as an image fill or a color style with sev
|
|
|
954
960
|
|
|
955
961
|
### Colors
|
|
956
962
|
|
|
957
|
-
The plugin supports solid colors and gradients (linear, radial, angular, diamond). Color styles are converted to DTCG format with support for variable aliases.
|
|
963
|
+
The plugin supports solid colors and gradients (linear, radial, angular, diamond). Color styles are converted to DTCG format with support for variable aliases. A solid style bound to a color variable with its own opacity below 100% is exported like a [color alias with opacity](#color-aliases-with-opacity): `{ "components": "{color.brand}", "alpha": 0.5 }`.
|
|
958
964
|
|
|
959
965
|
```json
|
|
960
966
|
// Solid color
|
|
@@ -999,7 +1005,7 @@ DTCG has no direction or type for a gradient, only the stops, so they are export
|
|
|
999
1005
|
|
|
1000
1006
|
### Grids
|
|
1001
1007
|
|
|
1002
|
-
In Figma you can add as many grids in the style as you want.
|
|
1008
|
+
In Figma you can add as many grids in the style as you want. The plugin exports the first `Columns` grid as `column*` values and the first `Rows` grid as `row*` values; further grids of the same kind are left out. A square `Grid` only has a cell size, which is exported as `columnWidth` when the style has no columns. Sizes of `0` are kept, and an `Auto` count is left out.
|
|
1003
1009
|
|
|
1004
1010
|
```json
|
|
1005
1011
|
// Column grid
|
|
@@ -1060,7 +1066,7 @@ The first effect of a style decides its type: a style that starts with a shadow
|
|
|
1060
1066
|
|
|
1061
1067
|
### Blur
|
|
1062
1068
|
|
|
1063
|
-
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,
|
|
1069
|
+
The plugin supports `background` and `layer` blur effects. In order to distinguish between them, the plugin adds the `role` property to the generated JSON. Only the first effect of a blur style is exported. Like all other tokens, blur tokens use the `$type` / `$value` keys with the [DTCG 2025.10 format](#dtcg-202510-format) setting on, and `type` / `value` with it off.
|
|
1064
1070
|
|
|
1065
1071
|
```json
|
|
1066
1072
|
// Background blur
|
|
@@ -1178,6 +1184,8 @@ All aliases are converted into the alias string format from the [Design Tokens s
|
|
|
1178
1184
|
}
|
|
1179
1185
|
```
|
|
1180
1186
|
|
|
1187
|
+
References use `.` as separator, so DTCG forbids `.`, `{` and `}` in token and group names. A collection whose name contains them, like `1. Primitives`, is exported as `1- Primitives`, with a warning; the meta keeps the original name, and the [import](#import-json--variables) uses it to recreate the collection under its Figma name.
|
|
1188
|
+
|
|
1181
1189
|
### Include `.value` string for aliases
|
|
1182
1190
|
|
|
1183
1191
|
You can switch on the `Include .value string for aliases` option in [the plugin settings](#include-value-string-for-aliases).
|
|
@@ -1251,7 +1259,7 @@ The plugin will generate the alias name anyway, but it will be a path to the var
|
|
|
1251
1259
|
}
|
|
1252
1260
|
```
|
|
1253
1261
|
|
|
1254
|
-
The plugin wouldn't include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files.
|
|
1262
|
+
The plugin wouldn't include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files. The CLI and the library API do the same in REST mode. In snapshot mode, add the library variables and their collections with `"remote": true`: they resolve aliases but aren't exported.
|
|
1255
1263
|
|
|
1256
1264
|
So you will need to merge the file with the base variables from one file with another where you use them. Otherwise tools like Style Dictionary wouldn't be able to resolve the aliases.
|
|
1257
1265
|
|
|
@@ -1328,7 +1336,7 @@ Figma variables have no font weight, font family or opacity type, so the plugin
|
|
|
1328
1336
|
|
|
1329
1337
|
- 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`.
|
|
1330
1338
|
- A string variable whose only scope is `FONT_FAMILY` becomes a `fontFamily` token. With any other scope next to it, it stays a `string`.
|
|
1331
|
-
- 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`.
|
|
1339
|
+
- 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`. Unless [scopes are included](#include-variable-scopes), such a token carries its scopes in `$extensions.figmaScopes`, so the [import](#import-json--variables) recreates an opacity variable (50, not 0.5).
|
|
1332
1340
|
|
|
1333
1341
|
---
|
|
1334
1342
|
|