tokens-bruecke 3.10.0 → 3.12.2
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 +18 -0
- package/README.md +76 -23
- package/bin/cli.js +1 -1
- package/examples/tokens-snapshot.json +37 -2
- package/global.d.ts +1 -0
- package/package.json +1 -1
- package/schemas/tokens-snapshot.schema.json +50 -0
- package/skills/tokens-bruecke/SKILL.md +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,21 @@
|
|
|
1
|
+
## [3.12.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.10.0...v3.12.0) (2026-09-08)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
- **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)
|
|
6
|
+
- **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)
|
|
7
|
+
|
|
8
|
+
### Bug Fixes
|
|
9
|
+
|
|
10
|
+
- **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)
|
|
11
|
+
- **motion:** round-trip named easings and skip scopes on motion variables ([72985de](https://github.com/tokens-bruecke/figma-plugin/commit/72985ded7fdb64ae290725d9894e2e026f21106d))
|
|
12
|
+
|
|
13
|
+
## [3.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.9.0...v3.10.0) (2026-09-05)
|
|
14
|
+
|
|
15
|
+
### Features
|
|
16
|
+
|
|
17
|
+
- **analytics:** count anonymous usage events with GoatCounter ([e34eb7e](https://github.com/tokens-bruecke/figma-plugin/commit/e34eb7e3231e1ab048bd8128386c50b447ad0899))
|
|
18
|
+
|
|
1
19
|
## [3.9.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.8.1...v3.9.0) (2026-09-05)
|
|
2
20
|
|
|
3
21
|
### Features
|
package/README.md
CHANGED
|
@@ -61,6 +61,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
61
61
|
- [Tokens structure](#tokens-structure)
|
|
62
62
|
- [Aliases handling](#aliases-handling)
|
|
63
63
|
- [Include `.value` string for aliases](#include-value-string-for-aliases-1)
|
|
64
|
+
- [Color aliases with opacity](#color-aliases-with-opacity)
|
|
64
65
|
- [Handle variables from another file](#handle-variables-from-another-file)
|
|
65
66
|
- [Handle modes](#handle-modes)
|
|
66
67
|
- [Variables types conversion](#variables-types-conversion)
|
|
@@ -192,7 +193,7 @@ When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and o
|
|
|
192
193
|
{
|
|
193
194
|
"easing": {
|
|
194
195
|
"$type": "cubicBezier",
|
|
195
|
-
"$value": [0.
|
|
196
|
+
"$value": [0.42, 0, 1, 1]
|
|
196
197
|
}
|
|
197
198
|
}
|
|
198
199
|
|
|
@@ -200,7 +201,8 @@ When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and o
|
|
|
200
201
|
{
|
|
201
202
|
"easing": {
|
|
202
203
|
"$type": "string",
|
|
203
|
-
"$value": "ease-in"
|
|
204
|
+
"$value": "ease-in",
|
|
205
|
+
"$extensions": { "figmaType": "EASING" }
|
|
204
206
|
}
|
|
205
207
|
}
|
|
206
208
|
```
|
|
@@ -558,6 +560,7 @@ Things worth knowing when building a snapshot:
|
|
|
558
560
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
559
561
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
560
562
|
- 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 `{ "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).
|
|
561
564
|
|
|
562
565
|
> [!NOTE]
|
|
563
566
|
> 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.
|
|
@@ -1041,6 +1044,56 @@ You can switch on the `Include .value string for aliases` option in [the plugin
|
|
|
1041
1044
|
|
|
1042
1045
|
---
|
|
1043
1046
|
|
|
1047
|
+
### Color aliases with opacity
|
|
1048
|
+
|
|
1049
|
+
Since September 2026 Figma lets a color variable alias another color and apply its own opacity on top ("Control opacity at scale"). The opacity can be a plain percentage or a number variable with the `COLOR_OPACITY` scope.
|
|
1050
|
+
|
|
1051
|
+
The [DTCG color type](https://www.designtokens.org/tr/2025.10/color/#format) has no way to express "this color, with that opacity" while keeping the reference, so the plugin exports these variables as a composite value: `components` holds the reference to the base color and `alpha` holds the opacity, as a `0..1` number (or `"50%"` with [Use percentage for opacity](#use-percentage-for-opacity)) or a reference to the number variable driving it.
|
|
1052
|
+
|
|
1053
|
+
```json
|
|
1054
|
+
{
|
|
1055
|
+
"opacity": {
|
|
1056
|
+
"50": { "$type": "number", "$value": 0.5, "scopes": ["COLOR_OPACITY"] }
|
|
1057
|
+
},
|
|
1058
|
+
"color": {
|
|
1059
|
+
"brand": {
|
|
1060
|
+
"$type": "color",
|
|
1061
|
+
"$value": {
|
|
1062
|
+
"colorSpace": "srgb",
|
|
1063
|
+
"components": [0.2, 0.4, 0.8],
|
|
1064
|
+
"alpha": 1,
|
|
1065
|
+
"hex": "#3366cc"
|
|
1066
|
+
}
|
|
1067
|
+
},
|
|
1068
|
+
"brand-translucent": {
|
|
1069
|
+
"$type": "color",
|
|
1070
|
+
"$value": { "components": "{color.brand}", "alpha": 0.5 }
|
|
1071
|
+
},
|
|
1072
|
+
"brand-muted": {
|
|
1073
|
+
"$type": "color",
|
|
1074
|
+
"$value": { "components": "{color.brand}", "alpha": "{opacity.50}" }
|
|
1075
|
+
}
|
|
1076
|
+
}
|
|
1077
|
+
}
|
|
1078
|
+
```
|
|
1079
|
+
|
|
1080
|
+
The `alpha` is the opacity Figma applies on top of the referenced color. If the base color is a literal rather than an alias, the opacity is baked into the regular color value for the chosen [color mode](#color-mode); only when the opacity itself is a reference does the color value keep an `alpha` (or `a`) reference in place of the number.
|
|
1081
|
+
|
|
1082
|
+
[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
|
+
|
|
1084
|
+
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.
|
|
1085
|
+
|
|
1086
|
+
> [!WARNING]
|
|
1087
|
+
> 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.
|
|
1088
|
+
|
|
1089
|
+
> [!NOTE]
|
|
1090
|
+
> 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).
|
|
1091
|
+
|
|
1092
|
+
> [!NOTE]
|
|
1093
|
+
> This shape is an extension of the DTCG format, so a consumer needs a small custom transform: resolve the `components` reference, then apply `alpha`.
|
|
1094
|
+
|
|
1095
|
+
---
|
|
1096
|
+
|
|
1044
1097
|
### Handle variables from another file
|
|
1045
1098
|
|
|
1046
1099
|
Imagine you have a library from another file with "base" variables. And you use this variables in your current file.
|
|
@@ -1077,16 +1130,16 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
|
|
|
1077
1130
|
|
|
1078
1131
|
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).
|
|
1079
1132
|
|
|
1080
|
-
| Figma type | Scope condition | Design Tokens type
|
|
1081
|
-
| ---------- | ------------------------ |
|
|
1082
|
-
| COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color)
|
|
1083
|
-
| BOOLEAN | — | _boolean_ \*
|
|
1084
|
-
| FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \*
|
|
1085
|
-
| FLOAT | `OPACITY` scope (no %) | _number_ \*
|
|
1086
|
-
| FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \*
|
|
1087
|
-
| FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\*
|
|
1088
|
-
| STRING | — | _string_ \*
|
|
1089
|
-
| TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\*
|
|
1133
|
+
| Figma type | Scope condition | Design Tokens type |
|
|
1134
|
+
| ---------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
1135
|
+
| COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
|
|
1136
|
+
| BOOLEAN | — | _boolean_ \* |
|
|
1137
|
+
| FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \* |
|
|
1138
|
+
| FLOAT | `OPACITY` scope (no %) | _number_ \* |
|
|
1139
|
+
| FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
|
|
1140
|
+
| FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
|
|
1141
|
+
| STRING | — | _string_ \* |
|
|
1142
|
+
| TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
|
|
1090
1143
|
| EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
|
|
1091
1144
|
|
|
1092
1145
|
\* 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).
|
|
@@ -1101,23 +1154,23 @@ Unlike design tokens, Figma variables [support only 6 types](https://www.figma.c
|
|
|
1101
1154
|
|
|
1102
1155
|
## Motion variables
|
|
1103
1156
|
|
|
1104
|
-
Figma's `EASING` variables hold either a custom curve or one of Figma's presets.
|
|
1157
|
+
Figma's `EASING` variables hold either a custom curve or one of Figma's presets. DTCG only has a `cubicBezier` type, so the plugin maps them like this:
|
|
1105
1158
|
|
|
1106
|
-
| Figma easing
|
|
1107
|
-
|
|
|
1108
|
-
| Custom bezier
|
|
1109
|
-
| Linear, Ease in / out / in and out, Ease in / out / in and out back
|
|
1110
|
-
| Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off
|
|
1111
|
-
| Gentle, Quick, Bouncy, Slow
|
|
1112
|
-
| Custom spring
|
|
1113
|
-
| Hold
|
|
1159
|
+
| Figma easing | Token type | Example value |
|
|
1160
|
+
| ----------------------------------------------------------------------------------- | ------------- | ----------------------- |
|
|
1161
|
+
| Custom bezier | `cubicBezier` | `[0, 0, 0.58, 1]` |
|
|
1162
|
+
| Linear, Ease in / out / in and out, Ease in / out / in and out back | `cubicBezier` | `[0.42, 0, 1, 1]` |
|
|
1163
|
+
| Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off | `string` | `"ease-in"` |
|
|
1164
|
+
| Gentle, Quick, Bouncy, Slow | `string` | `"gentle"` |
|
|
1165
|
+
| Custom spring | `string` | `"spring(bounce 0.35)"` |
|
|
1166
|
+
| Hold | `string` | `"hold"` |
|
|
1114
1167
|
|
|
1115
1168
|
Named bezier presets are expanded into curves unless [Expand easing presets to cubic-bezier](#expand-easing-presets-to-cubic-bezier) is turned off. Springs and Hold are always names: DTCG has no spring type, and Figma exposes no numbers for them.
|
|
1116
1169
|
|
|
1117
|
-
All of these forms are read back on import, so a round trip through the plugin preserves the original preset
|
|
1170
|
+
All of these forms are read back on import, so a round trip through the plugin preserves the original preset. Expanded curves are matched back to the preset they came from, and easings exported as strings carry an `$extensions.figmaType: "EASING"` marker so they are recreated as `EASING` variables rather than `STRING` ones.
|
|
1118
1171
|
|
|
1119
1172
|
> [!NOTE]
|
|
1120
|
-
>
|
|
1173
|
+
> The curves of the named bezier presets are the ones Figma attaches to the preset in the Plugin API; if one of them does not match what you see in your file, please [open an issue](https://github.com/tokens-bruecke/figma-plugin/issues).
|
|
1121
1174
|
|
|
1122
1175
|
---
|
|
1123
1176
|
|