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 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.41, 0, 1, 1]
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. 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:
1105
1153
 
1106
- | Figma easing | Token type | Example value |
1107
- | ------------------------------------------------------------------------------------ | --------------------- | -------------------------- |
1108
- | Custom bezier | `cubicBezier` | `[0, 0, 0.58, 1]` |
1109
- | Linear, Ease in / out / in and out, Ease in / out / in and out back | `cubicBezier` | `[0.41, 0, 1, 1]` |
1110
- | Linear, Ease in / out / in and out, Ease in / out / in and out back — expansion off | `string` | `"ease-in"` |
1111
- | Gentle, Quick, Bouncy, Slow | `string` | `"gentle"` |
1112
- | Custom spring | `string` | `"spring(bounce 0.35)"` |
1113
- | 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"` |
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 — 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.
1118
1166
 
1119
1167
  > [!NOTE]
1120
- > 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).
1121
1169
 
1122
1170
  ---
1123
1171