tokens-bruecke 3.9.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 +16 -0
- package/README.md +82 -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,19 @@
|
|
|
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
|
+
|
|
7
|
+
## [3.9.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.8.1...v3.9.0) (2026-09-05)
|
|
8
|
+
|
|
9
|
+
### Features
|
|
10
|
+
|
|
11
|
+
- **servers:** show a link to the GitHub Pull Request after pushing ([67562e2](https://github.com/tokens-bruecke/figma-plugin/commit/67562e21286a6d69227f57675b3b0a1191d3994b))
|
|
12
|
+
|
|
13
|
+
### Bug Fixes
|
|
14
|
+
|
|
15
|
+
- **ci:** generate the CHANGELOG section when the release tag is on a merge commit ([ce0a628](https://github.com/tokens-bruecke/figma-plugin/commit/ce0a628354d9f8a811ea1bf809454f7688f8b802))
|
|
16
|
+
|
|
1
17
|
## [3.8.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.7.0...v3.8.1) (2026-09-05)
|
|
2
18
|
|
|
3
19
|
### Features
|
package/README.md
CHANGED
|
@@ -61,12 +61,14 @@ 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)
|
|
67
68
|
- [Motion variables](#motion-variables)
|
|
68
69
|
- [Design tokens types](#design-tokens-types)
|
|
69
70
|
- [Scopes lemitations](#scopes-lemitations)
|
|
71
|
+
- [Privacy and analytics](#privacy-and-analytics)
|
|
70
72
|
- [Feedback](#feedback)
|
|
71
73
|
|
|
72
74
|
---
|
|
@@ -191,7 +193,7 @@ When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and o
|
|
|
191
193
|
{
|
|
192
194
|
"easing": {
|
|
193
195
|
"$type": "cubicBezier",
|
|
194
|
-
"$value": [0.
|
|
196
|
+
"$value": [0.42, 0, 1, 1]
|
|
195
197
|
}
|
|
196
198
|
}
|
|
197
199
|
|
|
@@ -199,7 +201,8 @@ When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and o
|
|
|
199
201
|
{
|
|
200
202
|
"easing": {
|
|
201
203
|
"$type": "string",
|
|
202
|
-
"$value": "ease-in"
|
|
204
|
+
"$value": "ease-in",
|
|
205
|
+
"$extensions": { "figmaType": "EASING" }
|
|
203
206
|
}
|
|
204
207
|
}
|
|
205
208
|
```
|
|
@@ -557,6 +560,7 @@ Things worth knowing when building a snapshot:
|
|
|
557
560
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
558
561
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
559
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).
|
|
560
564
|
|
|
561
565
|
> [!NOTE]
|
|
562
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.
|
|
@@ -1040,6 +1044,51 @@ You can switch on the `Include .value string for aliases` option in [the plugin
|
|
|
1040
1044
|
|
|
1041
1045
|
---
|
|
1042
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
|
+
|
|
1043
1092
|
### Handle variables from another file
|
|
1044
1093
|
|
|
1045
1094
|
Imagine you have a library from another file with "base" variables. And you use this variables in your current file.
|
|
@@ -1076,16 +1125,16 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
|
|
|
1076
1125
|
|
|
1077
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).
|
|
1078
1127
|
|
|
1079
|
-
| Figma type | Scope condition | Design Tokens type
|
|
1080
|
-
| ---------- | ------------------------ |
|
|
1081
|
-
| COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color)
|
|
1082
|
-
| BOOLEAN | — | _boolean_ \*
|
|
1083
|
-
| FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \*
|
|
1084
|
-
| FLOAT | `OPACITY` scope (no %) | _number_ \*
|
|
1085
|
-
| FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \*
|
|
1086
|
-
| FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\*
|
|
1087
|
-
| STRING | — | _string_ \*
|
|
1088
|
-
| 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) \*\*\* |
|
|
1089
1138
|
| EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
|
|
1090
1139
|
|
|
1091
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).
|
|
@@ -1100,23 +1149,23 @@ Unlike design tokens, Figma variables [support only 6 types](https://www.figma.c
|
|
|
1100
1149
|
|
|
1101
1150
|
## Motion variables
|
|
1102
1151
|
|
|
1103
|
-
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:
|
|
1104
1153
|
|
|
1105
|
-
| Figma easing
|
|
1106
|
-
|
|
|
1107
|
-
| Custom bezier
|
|
1108
|
-
| Linear, Ease in / out / in and out, Ease in / out / in and out back
|
|
1109
|
-
| Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off
|
|
1110
|
-
| Gentle, Quick, Bouncy, Slow
|
|
1111
|
-
| Custom spring
|
|
1112
|
-
| 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"` |
|
|
1113
1162
|
|
|
1114
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.
|
|
1115
1164
|
|
|
1116
|
-
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.
|
|
1117
1166
|
|
|
1118
1167
|
> [!NOTE]
|
|
1119
|
-
>
|
|
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).
|
|
1120
1169
|
|
|
1121
1170
|
---
|
|
1122
1171
|
|
|
@@ -1135,6 +1184,16 @@ In order to convert `FONT-WEIGHT` and `OPACITY` types into valid values you shou
|
|
|
1135
1184
|
|
|
1136
1185
|
---
|
|
1137
1186
|
|
|
1187
|
+
## Privacy and analytics
|
|
1188
|
+
|
|
1189
|
+
The plugin counts a few anonymous usage events with [GoatCounter](https://www.goatcounter.com), a privacy-friendly, open-source counter. It helps us see which features are used so we know where to focus.
|
|
1190
|
+
|
|
1191
|
+
What is sent: the plugin was opened, the file had variables or not, tokens were downloaded, tokens were copied from the code preview, tokens were imported, or a push to one of the servers (GitHub, GitLab, JSONBin, custom URL) was started. That is the full list.
|
|
1192
|
+
|
|
1193
|
+
What is never sent: your tokens, variable or collection names, file names, server URLs, access tokens, or any other data read from your Figma file. GoatCounter sets no cookies and does not track you across sites.
|
|
1194
|
+
|
|
1195
|
+
---
|
|
1196
|
+
|
|
1138
1197
|
## Feedback
|
|
1139
1198
|
|
|
1140
1199
|
If you have any questions or suggestions, feel free to [create an issue](https://github.com/tokens-bruecke/figma-plugin/issues)
|