tokens-bruecke 3.6.0 → 3.8.1

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,21 @@
1
+ ## [3.7.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.6.0...v3.7.0) (2026-08-22)
2
+
3
+ ### Features
4
+
5
+ - **servers:** commit split token files to Github and Gitlab ([f3ba2b4](https://github.com/tokens-bruecke/figma-plugin/commit/f3ba2b4c5c8dc0593a918ab46a2c68f813314729))
6
+
7
+ ## [3.6.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.5.0...v3.6.0) (2026-08-21)
8
+
9
+ ### Features
10
+
11
+ - **cli:** add an interactive `init` command ([7752a58](https://github.com/tokens-bruecke/figma-plugin/commit/7752a580f14461dde5027ccb30573638ae4d5609))
12
+ - **cli:** keyboard navigation for the init prompts ([4a839bc](https://github.com/tokens-bruecke/figma-plugin/commit/4a839bc07fae8acd77a08d38edf320a75c4c480f))
13
+
14
+ ### Bug Fixes
15
+
16
+ - **ci:** generate the release CHANGELOG section that -r 1 silently skipped ([e116963](https://github.com/tokens-bruecke/figma-plugin/commit/e116963d0ceb82a738635bf15b627c0a5a5df956))
17
+ - **ci:** publish to npm via trusted publishing (OIDC) ([3775e31](https://github.com/tokens-bruecke/figma-plugin/commit/3775e31744e33f7442d143ebf36dfe4e13403301))
18
+
1
19
  # Changelog
2
20
 
3
21
  ## [3.5.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.4...v3.5.0) (2026-08-21)
package/README.md CHANGED
@@ -25,6 +25,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
25
25
  - [Add styles to](#add-styles-to)
26
26
  - [Include variable scopes](#include-variable-scopes)
27
27
  - [Use percentage for opacity](#use-percentage-for-opacity)
28
+ - [Expand easing presets to cubic-bezier](#expand-easing-presets-to-cubic-bezier)
28
29
  - [DTCG 2025.10 format](#dtcg-202510-format)
29
30
  - [Include `.value` string for aliases](#include-value-string-for-aliases)
30
31
  - [Include Figma metadata](#include-figma-metadata)
@@ -63,6 +64,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
63
64
  - [Handle variables from another file](#handle-variables-from-another-file)
64
65
  - [Handle modes](#handle-modes)
65
66
  - [Variables types conversion](#variables-types-conversion)
67
+ - [Motion variables](#motion-variables)
66
68
  - [Design tokens types](#design-tokens-types)
67
69
  - [Scopes lemitations](#scopes-lemitations)
68
70
  - [Feedback](#feedback)
@@ -100,13 +102,14 @@ The plugin supports both **exporting** and **importing** design tokens:
100
102
 
101
103
  - ✅ Creates variable collections from top-level objects
102
104
  - ✅ Supports multiple modes (from `$extensions.mode` or `extensions.mode`)
103
- - ✅ Handles all variable types (color, number, string, boolean)
105
+ - ✅ Handles all variable types (color, number, string, boolean, timing, easing)
104
106
  - ✅ Resolves alias references between variables
105
107
  - ✅ Supports various color formats (HEX, RGBA CSS, RGBA Object)
106
108
  - ✅ Preserves variable descriptions and metadata
109
+ - ✅ Imports `duration` and `cubicBezier` tokens as Figma motion variables (see [Motion variables](#motion-variables))
107
110
 
108
111
  > [!WARNING]
109
- > **Styles Export Limitation**: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles or variables. Figma's variable API currently only supports basic types: `color`, `number`, `string`, `boolean`, and `dimension`. Complex style types will be imported as `STRING` variables without proper value conversion. This is a temporary limitation until Figma supports these types natively in their API.
112
+ > **Styles Export Limitation**: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles or variables. Figma's variable API currently only supports basic types: `color`, `number`, `string`, `boolean`, `dimension`, `duration` and `cubicBezier`. Complex style types will be imported as `STRING` variables without proper value conversion. This is a temporary limitation until Figma supports these types natively in their API.
110
113
 
111
114
  ---
112
115
 
@@ -177,6 +180,34 @@ Is `off` by default. When enabled, opacity values will be exported as percentage
177
180
  }
178
181
  ```
179
182
 
183
+ ### Expand easing presets to cubic-bezier
184
+
185
+ Is `on` by default. Figma's `EASING` variables hold either a custom curve or one of Figma's named presets, and the API only returns numbers for the custom ones — a preset arrives as just its name.
186
+
187
+ When enabled, the named bezier presets (Linear, Ease in, Ease out, Ease in and out and the three "back" variants) are expanded into their curve, so every bezier easing exports as a spec-valid `cubicBezier` token. When disabled, they keep the name Figma gave them.
188
+
189
+ ```json
190
+ // Expanded (default)
191
+ {
192
+ "easing": {
193
+ "$type": "cubicBezier",
194
+ "$value": [0.41, 0, 1, 1]
195
+ }
196
+ }
197
+
198
+ // Not expanded
199
+ {
200
+ "easing": {
201
+ "$type": "string",
202
+ "$value": "ease-in"
203
+ }
204
+ }
205
+ ```
206
+
207
+ Custom beziers always export as `cubicBezier` and are unaffected by this setting.
208
+
209
+ Spring presets (Gentle, Quick, Bouncy, Slow), custom springs and Hold are always exported as strings regardless of the setting — DTCG has no spring type, and Figma exposes no curve to expand a spring into. See [Motion variables](#motion-variables) for the full mapping.
210
+
180
211
  ### DTCG 2025.10 format
181
212
 
182
213
  Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/):
@@ -283,6 +314,7 @@ Is `off` by default. When enabled, each Figma variable collection is exported as
283
314
 
284
315
  - **Download JSON** — produces a `design.tokens.zip` archive containing one `{CollectionName}.tokens.json` per collection.
285
316
  - **CLI** — writes individual `{CollectionName}.tokens.json` files into the directory specified by `--output`.
317
+ - **Push to a server** — the GitHub, GitHub PR and GitLab servers commit one `{CollectionName}.tokens.json` per collection in a single commit. The `File name` field of the server becomes the folder they are written into, e.g. `tokens` → `tokens/{CollectionName}.tokens.json`.
286
318
 
287
319
  This is useful when you want to keep component-level token files separate (e.g. `button.tokens.json`, `card.tokens.json`).
288
320
 
@@ -292,6 +324,7 @@ Is `off` by default. When enabled, each mode of a variable collection is exporte
292
324
 
293
325
  - **Download JSON** — produces a `design.tokens.zip` archive containing one `{CollectionName}/{ModeName}.tokens.json` per mode.
294
326
  - **CLI** — writes individual `{CollectionName}/{ModeName}.tokens.json` files into the directory specified by `--output`.
327
+ - **Push to a server** — the GitHub, GitHub PR and GitLab servers commit one `{CollectionName}/{ModeName}.tokens.json` per mode in a single commit, inside the folder set in the server's `File name` field.
295
328
 
296
329
  Collections with a single mode are exported as a single `{CollectionName}.tokens.json` file.
297
330
 
@@ -545,6 +578,7 @@ You can use a JSON configuration file to specify the export options for the CLI.
545
578
  "includeValueStringKeyToAlias": true,
546
579
  "includeFigmaMetaData": false, // Include Figma metadata like styleId, variableId, etc.
547
580
  "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
581
+ "expandEasingPresets": true, // Expand Figma's named easing presets into cubicBezier values
548
582
  "colorMode": "hex", // "hex" | "rgba-object" | "srgb-dtcg" | "rgba-css" | "hsla-object" | "hsl-dtcg" | "hsla-css" | "oklch-dtcg";
549
583
  "storeStyleInCollection": "none", // Name of one of your collection or "none" to keep them separated
550
584
  "splitByCollection": false, // Write each collection as a separate .tokens.json file
@@ -670,6 +704,8 @@ In ordere to test if your credentials are valid you can make a test request by c
670
704
  4. In the file name field you can specify a path to the file. If the file doesn't exist, it will be created. If the file exists, it will be overwritten. File name should include the file extension, e.g. `tokens.json`.
671
705
  5. You can also specify a commit message.
672
706
 
707
+ > **Splitting into several files.** If _Split collections into separate files_ or _Split modes into separate files_ is enabled in the advanced settings, the file name field is treated as a folder instead, and every file is written in a single commit — e.g. `tokens` → `tokens/Colors.tokens.json`, or `tokens/Colors/Light.tokens.json` when splitting by mode.
708
+
673
709
  ![fig.8](readme-assets/fig8.webp)
674
710
 
675
711
  ### [GitHub PR](https://github.com)
@@ -686,7 +722,10 @@ All the steps are the same as for the [GitHub](#github) server, except the last
686
722
  1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope.
687
723
  2. In the plugin settings paste the token into the `Project access token` field.
688
724
  3. Add an owner name, repository name and a branch name.
689
- 4. In the file name field you can specify a path to the file. If the file doesn't exist, it will be created. If the file exists, it will be overwritten. File name should include the file extension, e.g. `tokens.json`. 5. You can also specify a commit message.
725
+ 4. In the file name field you can specify a path to the file. If the file doesn't exist, it will be created. If the file exists, it will be overwritten. File name should include the file extension, e.g. `tokens.json`.
726
+ 5. You can also specify a commit message.
727
+
728
+ > **Splitting into several files.** If _Split collections into separate files_ or _Split modes into separate files_ is enabled in the advanced settings, the file name field is treated as a folder instead, and every file is written in a single commit — e.g. `tokens` → `tokens/Colors.tokens.json`, or `tokens/Colors/Light.tokens.json` when splitting by mode.
690
729
 
691
730
  ![fig.11](readme-assets/fig11.webp)
692
731
 
@@ -1035,7 +1074,7 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
1035
1074
 
1036
1075
  ## Variables types conversion
1037
1076
 
1038
- Unlike design tokens, Figma variables now [support only 4 types](https://www.figma.com/plugin-docs/api/VariableResolvedDataType) — `COLOR`, `BOOLEAN`, `FLOAT` and `STRING`. So, the plugin converts them into the corresponding types from the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/#types).
1077
+ 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).
1039
1078
 
1040
1079
  | Figma type | Scope condition | Design Tokens type |
1041
1080
  | ---------- | ------------------------ | ---------------------------------------------------------------------------- |
@@ -1046,11 +1085,39 @@ Unlike design tokens, Figma variables now [support only 4 types](https://www.fig
1046
1085
  | FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
1047
1086
  | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
1048
1087
  | STRING | — | _string_ \* |
1088
+ | TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
1089
+ | EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
1049
1090
 
1050
1091
  \* 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).
1051
1092
 
1052
1093
  \*\* Figma currently supports only `FLOAT` for numeric values used as dimensions, which map to `px` units. With the DTCG 2025.10 format on, dimensions are exported as `{ "value": 6, "unit": "px" }` objects; otherwise the plugin appends `px` to the number.
1053
1094
 
1095
+ \*\*\* Figma stores timings in seconds; the plugin converts them to milliseconds. With the DTCG 2025.10 format on, durations are exported as `{ "value": 300, "unit": "ms" }` objects; otherwise the plugin appends `ms` to the number.
1096
+
1097
+ \*\*\*\* See [Motion variables](#motion-variables) below.
1098
+
1099
+ ---
1100
+
1101
+ ## Motion variables
1102
+
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:
1104
+
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"` |
1113
+
1114
+ 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
+
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.
1117
+
1118
+ > [!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).
1120
+
1054
1121
  ---
1055
1122
 
1056
1123
  ## Design tokens types