tokens-bruecke 3.12.0 → 3.13.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 +19 -0
- package/README.md +35 -2
- package/bin/cli.js +1 -1
- package/package.json +1 -1
- package/schemas/tokens-snapshot.schema.json +21 -0
- package/skills/tokens-bruecke/SKILL.md +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,22 @@
|
|
|
1
|
+
## [3.12.2](https://github.com/tokens-bruecke/figma-plugin/compare/v3.12.0...v3.12.2) (2026-09-17)
|
|
2
|
+
|
|
3
|
+
### Bug Fixes
|
|
4
|
+
|
|
5
|
+
- **color:** support the { color, opacity } shape of composed colors ([d486243](https://github.com/tokens-bruecke/figma-plugin/commit/d486243d62e1ea3ea960e77056bdc1c95e7dd770)), closes [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91)
|
|
6
|
+
- **export:** keep exporting when a color variable has an unknown shape ([0a0ba67](https://github.com/tokens-bruecke/figma-plugin/commit/0a0ba670660d7531a85af27bd5152f6213d5fcdc)), closes [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91)
|
|
7
|
+
|
|
8
|
+
## [3.12.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.10.0...v3.12.0) (2026-09-08)
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
- **color:** export color aliases with a separate opacity as composed values ([c2451b7](https://github.com/tokens-bruecke/figma-plugin/commit/c2451b7a8e04ab356be66a583007e987b03088f2)), closes [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91)
|
|
13
|
+
- **import:** write composed colors back to Figma ([4b3e152](https://github.com/tokens-bruecke/figma-plugin/commit/4b3e1526c7013b1213f22758debe4db1f4de8108)), closes [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91)
|
|
14
|
+
|
|
15
|
+
### Bug Fixes
|
|
16
|
+
|
|
17
|
+
- **import:** report composed colors this Figma version cannot write ([0578075](https://github.com/tokens-bruecke/figma-plugin/commit/0578075c91ace03408eb87041e7f8dd2e6c088da)), closes [figma/plugin-typings#375](https://github.com/figma/plugin-typings/issues/375)
|
|
18
|
+
- **motion:** round-trip named easings and skip scopes on motion variables ([72985de](https://github.com/tokens-bruecke/figma-plugin/commit/72985ded7fdb64ae290725d9894e2e026f21106d))
|
|
19
|
+
|
|
1
20
|
## [3.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.9.0...v3.10.0) (2026-09-05)
|
|
2
21
|
|
|
3
22
|
### Features
|
package/README.md
CHANGED
|
@@ -32,6 +32,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
32
32
|
- [Split collections into separate files](#split-collections-into-separate-files)
|
|
33
33
|
- [Split modes into separate files](#split-modes-into-separate-files)
|
|
34
34
|
- [Omit collection names](#omit-collection-names)
|
|
35
|
+
- [Extended collections](#extended-collections)
|
|
35
36
|
- [Use as cli tool](#use-as-cli-tool)
|
|
36
37
|
- [Installation](#installation)
|
|
37
38
|
- [Usage](#usage)
|
|
@@ -388,6 +389,33 @@ Alias references are also rewritten so they point to the flat path (the collecti
|
|
|
388
389
|
|
|
389
390
|
---
|
|
390
391
|
|
|
392
|
+
### Extended collections
|
|
393
|
+
|
|
394
|
+
Collections created with [Extend a variable collection](https://help.figma.com/hc/en-us/articles/36346281624471-Extend-a-variable-collection) are exported as collections of their own. Figma stores only what an extension changes, so the export writes all the variables it inherits, with the overrides of its chain applied, which keeps every collection complete.
|
|
395
|
+
|
|
396
|
+
- The value of a variable is the closest override in the chain of extensions, or the value of the root collection when nothing overrides it. An override that was cleared falls through to the parent. Each mode follows the parent mode it inherits from, even when the extension renames it.
|
|
397
|
+
- Aliases to variables of the root collection point to the extension's own variable, so `{Core.color.brand}` becomes `{Regional.color.brand}` inside `Regional`. Aliases to other collections stay as they are.
|
|
398
|
+
- Extensions of a library collection are exported without the variables they inherit, because those live in the library file, not in yours. The export warns about them.
|
|
399
|
+
- With [Omit collection names](#omit-collection-names) the extended collections are skipped with a warning, because they repeat the variables of their root collection and would collide in a single namespace.
|
|
400
|
+
|
|
401
|
+
```json
|
|
402
|
+
// "Regional" extends "Core" and overrides color/brand
|
|
403
|
+
{
|
|
404
|
+
"Core": {
|
|
405
|
+
"color": {
|
|
406
|
+
"brand": { "type": "color", "value": "#ff0000" },
|
|
407
|
+
"text": { "type": "color", "value": "{Core.color.brand}" }
|
|
408
|
+
}
|
|
409
|
+
},
|
|
410
|
+
"Regional": {
|
|
411
|
+
"color": {
|
|
412
|
+
"brand": { "type": "color", "value": "#00ff00" },
|
|
413
|
+
"text": { "type": "color", "value": "{Regional.color.brand}" }
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
```
|
|
418
|
+
|
|
391
419
|
## Use as cli tool
|
|
392
420
|
|
|
393
421
|
The CLI is published on npm: [tokens-bruecke](https://www.npmjs.com/package/tokens-bruecke)
|
|
@@ -560,7 +588,7 @@ Things worth knowing when building a snapshot:
|
|
|
560
588
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
561
589
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
562
590
|
- 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.
|
|
563
|
-
- Color aliases with their own opacity come back from the Plugin API as `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }` — pass
|
|
591
|
+
- 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).
|
|
564
592
|
|
|
565
593
|
> [!NOTE]
|
|
566
594
|
> Plugin API objects are live proxies, so `JSON.stringify` may not enumerate their properties. Copy the fields listed in the schema onto plain objects before serializing.
|
|
@@ -1081,8 +1109,13 @@ The `alpha` is the opacity Figma applies on top of the referenced color. If the
|
|
|
1081
1109
|
|
|
1082
1110
|
[Importing](#import-json--variables) these tokens recreates the composed color variable in Figma: `components` becomes the alias, `alpha` the opacity (a plain percentage or an alias to the number variable). References to variables in other collections are resolved once every collection has been imported.
|
|
1083
1111
|
|
|
1112
|
+
Figma has exposed these variables to plugins in two shapes so far: current runtimes (the Figma web app, and what `setValueForMode` accepts) use `{ "color": <alias or rgba>, "opacity": <0..100 or alias> }`, while Figma Desktop 126.x returned a `COMPOSE_COLOR` expression. The export reads both. The import writes the current shape and falls back to the expression for runtimes that only accept that one.
|
|
1113
|
+
|
|
1084
1114
|
> [!WARNING]
|
|
1085
|
-
> Some Figma clients can read these variables but refuse to write them ("Composed color variable values are not supported"),
|
|
1115
|
+
> Some Figma clients can read these variables but refuse to write them in either shape ("Composed color variable values are not supported"), including Figma Desktop 126.x. The plugin then leaves those values untouched, reports how many were skipped and links to [figma/plugin-typings#375](https://github.com/figma/plugin-typings/issues/375). Other tokens in the same import are not affected.
|
|
1116
|
+
|
|
1117
|
+
> [!NOTE]
|
|
1118
|
+
> Figma is still changing how these values are exposed to plugins. If a color variable comes back in a shape the plugin does not recognise, the export leaves that variable out and logs a `[tokens-bruecke] Skipped variable …` warning with the raw value to the Figma console (`Plugins → Development → Open console`) instead of failing. Please paste that warning into [#91](https://github.com/tokens-bruecke/figma-plugin/issues/91).
|
|
1086
1119
|
|
|
1087
1120
|
> [!NOTE]
|
|
1088
1121
|
> This shape is an extension of the DTCG format, so a consumer needs a small custom transform: resolve the `components` reference, then apply `alpha`.
|