tokens-bruecke 3.10.0 → 3.12.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 +6 -0
- package/README.md +71 -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 +29 -0
- package/skills/tokens-bruecke/SKILL.md +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
## [3.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.9.0...v3.10.0) (2026-09-05)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
- **analytics:** count anonymous usage events with GoatCounter ([e34eb7e](https://github.com/tokens-bruecke/figma-plugin/commit/e34eb7e3231e1ab048bd8128386c50b447ad0899))
|
|
6
|
+
|
|
1
7
|
## [3.9.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.8.1...v3.9.0) (2026-09-05)
|
|
2
8
|
|
|
3
9
|
### 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 `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }` — pass them 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,51 @@ 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
|
+
> [!WARNING]
|
|
1085
|
+
> Some Figma clients can read these variables but refuse to write them ("Composed color variable values are not supported"), currently including Figma Desktop. 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.
|
|
1086
|
+
|
|
1087
|
+
> [!NOTE]
|
|
1088
|
+
> This shape is an extension of the DTCG format, so a consumer needs a small custom transform: resolve the `components` reference, then apply `alpha`.
|
|
1089
|
+
|
|
1090
|
+
---
|
|
1091
|
+
|
|
1044
1092
|
### Handle variables from another file
|
|
1045
1093
|
|
|
1046
1094
|
Imagine you have a library from another file with "base" variables. And you use this variables in your current file.
|
|
@@ -1077,16 +1125,16 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
|
|
|
1077
1125
|
|
|
1078
1126
|
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
1127
|
|
|
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) \*\*\*
|
|
1128
|
+
| Figma type | Scope condition | Design Tokens type |
|
|
1129
|
+
| ---------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
1130
|
+
| COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
|
|
1131
|
+
| BOOLEAN | — | _boolean_ \* |
|
|
1132
|
+
| FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \* |
|
|
1133
|
+
| FLOAT | `OPACITY` scope (no %) | _number_ \* |
|
|
1134
|
+
| FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
|
|
1135
|
+
| FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
|
|
1136
|
+
| STRING | — | _string_ \* |
|
|
1137
|
+
| TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
|
|
1090
1138
|
| EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
|
|
1091
1139
|
|
|
1092
1140
|
\* 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 +1149,23 @@ Unlike design tokens, Figma variables [support only 6 types](https://www.figma.c
|
|
|
1101
1149
|
|
|
1102
1150
|
## Motion variables
|
|
1103
1151
|
|
|
1104
|
-
Figma's `EASING` variables hold either a custom curve or one of Figma's presets.
|
|
1152
|
+
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
1153
|
|
|
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
|
|
1154
|
+
| Figma easing | Token type | Example value |
|
|
1155
|
+
| ----------------------------------------------------------------------------------- | ------------- | ----------------------- |
|
|
1156
|
+
| Custom bezier | `cubicBezier` | `[0, 0, 0.58, 1]` |
|
|
1157
|
+
| Linear, Ease in / out / in and out, Ease in / out / in and out back | `cubicBezier` | `[0.42, 0, 1, 1]` |
|
|
1158
|
+
| Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off | `string` | `"ease-in"` |
|
|
1159
|
+
| Gentle, Quick, Bouncy, Slow | `string` | `"gentle"` |
|
|
1160
|
+
| Custom spring | `string` | `"spring(bounce 0.35)"` |
|
|
1161
|
+
| Hold | `string` | `"hold"` |
|
|
1114
1162
|
|
|
1115
1163
|
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
1164
|
|
|
1117
|
-
All of these forms are read back on import, so a round trip through the plugin preserves the original preset
|
|
1165
|
+
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
1166
|
|
|
1119
1167
|
> [!NOTE]
|
|
1120
|
-
>
|
|
1168
|
+
> 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
1169
|
|
|
1122
1170
|
---
|
|
1123
1171
|
|