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 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.41, 0, 1, 1]
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. The API returns numbers only for the two custom types — every preset arrives as just a name — so the plugin maps them like this:
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 | Token type | Example value |
1106
- | ------------------------------------------------------------------------------------ | --------------------- | -------------------------- |
1107
- | Custom bezier | `cubicBezier` | `[0, 0, 0.58, 1]` |
1108
- | Linear, Ease in / out / in and out, Ease in / out / in and out back | `cubicBezier` | `[0.41, 0, 1, 1]` |
1109
- | Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off | `string` | `"ease-in"` |
1110
- | Gentle, Quick, Bouncy, Slow | `string` | `"gentle"` |
1111
- | Custom spring | `string` | `"spring(bounce 0.35)"` |
1112
- | Hold | `string` | `"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 — including expanded curves, which are matched back to the preset they came from. Springs and Hold are the exception: they are indistinguishable from ordinary text on the way back in, so importing them creates `STRING` variables rather than `EASING` ones.
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
- > Figma does not publish the control points behind its named bezier presets, and the plugin API does not return them. The curves the plugin expands to are taken from Figma's own custom-bezier editor; 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).
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)