tokens-bruecke 2.9.4 → 2.11.2

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.
Files changed (7) hide show
  1. package/.github/workflows/release.yml +3 -1
  2. package/.release-please-manifest.json +1 -1
  3. package/CHANGELOG.md +40 -16
  4. package/README.md +62 -3
  5. package/bin/cli.js +1 -1
  6. package/global.d.ts +2 -1
  7. package/package.json +4 -2
package/.github/workflows/release.yml CHANGED
@@ -14,12 +14,14 @@ jobs:
14
14
  packages: write # to create NPM package under github registry
15
15
 
16
16
  runs-on: ubuntu-latest
17
+ env:
18
+ FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
17
19
  steps:
18
20
  - uses: googleapis/release-please-action@v4
19
21
  id: release
20
22
  with:
21
23
  token: ${{ secrets.GITHUB_TOKEN }}
22
-
24
+
23
25
  - name: Checkout
24
26
  uses: actions/checkout@v4
25
27
  if: ${{ steps.release.outputs.release_created }}
package/.release-please-manifest.json CHANGED
@@ -1,3 +1,3 @@
1
1
  {
2
- ".": "2.9.4"
2
+ ".": "2.10.0"
3
3
  }
package/CHANGELOG.md CHANGED
@@ -1,53 +1,77 @@
1
1
  # Changelog
2
2
 
3
- ## [2.9.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.3...v2.9.4) (2026-01-13)
3
+ ## [2.10.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.4...v2.10.0) (2026-03-28)
4
+
5
+
6
+ ### Features
7
+
8
+ * Add export/import docs and styles warning ([6446d2a](https://github.com/tokens-bruecke/figma-plugin/commit/6446d2ab117f6e5b9270588b886e6903505f36fe))
9
+ * **cli:** add --oauth-token flag to support OAuth authentication ([ccbc16e](https://github.com/tokens-bruecke/figma-plugin/commit/ccbc16e931c653d4a1aa345902aada38c71a0af3))
4
10
 
5
11
 
6
12
  ### Bug Fixes
7
13
 
8
- * hardcoded style colors into variables ([403c4a5](https://github.com/tokens-bruecke/figma-plugin/commit/403c4a582da3cd7f1d3a4af3654660b84275c9dc))
14
+ * import variables ([1d72235](https://github.com/tokens-bruecke/figma-plugin/commit/1d722358b5e714710df3546727fdaba41427c863))
15
+ * **normilizeType:** return 'string' instead of 'dimension' for percentage opacity ([52085c6](https://github.com/tokens-bruecke/figma-plugin/commit/52085c63d50809f9a25a86c6fad9a26fbfd67427))
9
16
 
10
- ## [2.9.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.2...v2.9.3) (2025-12-06)
11
17
 
18
+ ### Miscellaneous
19
+
20
+ * format CHANGELOG ([0e2e4b0](https://github.com/tokens-bruecke/figma-plugin/commit/0e2e4b0e2fe655451c36bdd7e54f2fffbfeb3a46))
21
+
22
+ ## [2.11.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.11.0...v2.11.1) (2026-03-28)
12
23
 
13
24
  ### Bug Fixes
14
25
 
15
- * Remove pnpm version and install options in release workflow ([62ea535](https://github.com/tokens-bruecke/figma-plugin/commit/62ea535c12639ab21b056eb08209fa1115d33920))
26
+ - **normilizeType:** return `string` instead of `dimension` for percentage opacity
16
27
 
17
- ## [2.9.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.1...v2.9.2) (2025-12-06)
28
+ ## [2.11.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.10.0...v2.11.0) (2026-03-28)
29
+
30
+ ### Features
18
31
 
32
+ - **cli:** add `--oauth-token` flag to support OAuth authentication ([#65](https://github.com/tokens-bruecke/figma-plugin/issues/65))
33
+
34
+ ## [2.9.4](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.3...v2.9.4) (2026-01-13)
19
35
 
20
36
  ### Bug Fixes
21
37
 
22
- * Add zip existence check and force artifact upload ([f9d9b4b](https://github.com/tokens-bruecke/figma-plugin/commit/f9d9b4b8aa7b79cb858140fc0fed2e24eca1faca))
38
+ - hardcoded style colors into variables ([403c4a5](https://github.com/tokens-bruecke/figma-plugin/commit/403c4a582da3cd7f1d3a4af3654660b84275c9dc))
23
39
 
24
- ## [2.9.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.0...v2.9.1) (2025-12-06)
40
+ ## [2.9.3](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.2...v2.9.3) (2025-12-06)
41
+
42
+ ### Bug Fixes
25
43
 
44
+ - Remove pnpm version and install options in release workflow ([62ea535](https://github.com/tokens-bruecke/figma-plugin/commit/62ea535c12639ab21b056eb08209fa1115d33920))
45
+
46
+ ## [2.9.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.1...v2.9.2) (2025-12-06)
26
47
 
27
48
  ### Bug Fixes
28
49
 
29
- * Add Release Please configuration files ([dcedd19](https://github.com/tokens-bruecke/figma-plugin/commit/dcedd19dc186bb97bb770af7701be5c8f821f861))
50
+ - Add zip existence check and force artifact upload ([f9d9b4b](https://github.com/tokens-bruecke/figma-plugin/commit/f9d9b4b8aa7b79cb858140fc0fed2e24eca1faca))
30
51
 
31
- ## [2.7.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.6.2...v2.7.0) (2025-09-21)
52
+ ## [2.9.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.9.0...v2.9.1) (2025-12-06)
32
53
 
54
+ ### Bug Fixes
33
55
 
34
- ### Features
56
+ - Add Release Please configuration files ([dcedd19](https://github.com/tokens-bruecke/figma-plugin/commit/dcedd19dc186bb97bb770af7701be5c8f821f861))
57
+
58
+ ## [2.7.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.6.2...v2.7.0) (2025-09-21)
35
59
 
36
- * Add direct new GitHub token URL with "repo" scope ([f2f68f9](https://github.com/tokens-bruecke/figma-plugin/commit/f2f68f91bb20ded52cb193391bf4eeaca0e6d303))
37
- * Add direct new GitHub token URL with "repo" scope ([aea4d98](https://github.com/tokens-bruecke/figma-plugin/commit/aea4d983b99892f28040b919bc79b161fe4e4aa2))
60
+ ### Features
38
61
 
62
+ - Add direct new GitHub token URL with "repo" scope ([f2f68f9](https://github.com/tokens-bruecke/figma-plugin/commit/f2f68f91bb20ded52cb193391bf4eeaca0e6d303))
63
+ - Add direct new GitHub token URL with "repo" scope ([aea4d98](https://github.com/tokens-bruecke/figma-plugin/commit/aea4d983b99892f28040b919bc79b161fe4e4aa2))
39
64
 
40
65
  ### Bug Fixes
41
66
 
42
- * file path must be URL-encoded for Gitlab API ([369d43f](https://github.com/tokens-bruecke/figma-plugin/commit/369d43fd01d04ea44a810ebcada07a97c5924072))
43
- * URL encode file path for Gitlab API ([6a590b1](https://github.com/tokens-bruecke/figma-plugin/commit/6a590b15966d4b4188d210d6d8a7dcd4ab07884f))
67
+ - file path must be URL-encoded for Gitlab API ([369d43f](https://github.com/tokens-bruecke/figma-plugin/commit/369d43fd01d04ea44a810ebcada07a97c5924072))
68
+ - URL encode file path for Gitlab API ([6a590b1](https://github.com/tokens-bruecke/figma-plugin/commit/6a590b15966d4b4188d210d6d8a7dcd4ab07884f))
44
69
 
45
70
  ## [2.6.2](https://github.com/tokens-bruecke/figma-plugin/compare/v2.6.1...v2.6.2) (2025-06-01)
46
71
 
47
-
48
72
  ### Bug Fixes
49
73
 
50
- * prettier and file formatting ([43bbca5](https://github.com/tokens-bruecke/figma-plugin/commit/43bbca5a922a2d5653704c56b0c2d6e1060855d2))
74
+ - prettier and file formatting ([43bbca5](https://github.com/tokens-bruecke/figma-plugin/commit/43bbca5a922a2d5653704c56b0c2d6e1060855d2))
51
75
 
52
76
  ## [2.6.1](https://github.com/tokens-bruecke/figma-plugin/compare/v2.6.0...v2.6.1) (2025-04-17)
53
77
 
package/README.md CHANGED
@@ -18,14 +18,18 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
18
18
  - [New version 2.0.0](#new-version-200)
19
19
  - [How to use](#how-to-use)
20
20
  - [Export and Import](#export-and-import)
21
+ - [Export (Variables → JSON)](#export-variables--json)
22
+ - [Import (JSON → Variables)](#import-json--variables)
21
23
  - [General settings](#general-settings)
22
24
  - [Color mode](#color-mode)
23
25
  - [Include styles](#include-styles)
24
26
  - [Add styles to](#add-styles-to)
25
27
  - [Include variable scopes](#include-variable-scopes)
28
+ - [Use percentage for opacity](#use-percentage-for-opacity)
26
29
  - [Use DTCG keys format](#use-dtcg-keys-format)
27
30
  - [Include `.value` string for aliases](#include-value-string-for-aliases)
28
31
  - [Include Figma metadata](#include-figma-metadata)
32
+ - [Split collections into separate files](#split-collections-into-separate-files)
29
33
  - [Use as cli tool](#use-as-cli-tool)
30
34
  - [Installation](#installation)
31
35
  - [Usage](#usage)
@@ -80,11 +84,13 @@ You can download and install previos version `1.6.1` here — [github.com/tokens
80
84
  The plugin supports both **exporting** and **importing** design tokens:
81
85
 
82
86
  #### Export (Variables → JSON)
87
+
83
88
  - Click **"Download JSON"** to export your Figma variables as a design tokens JSON file
84
89
  - The exported file is compatible with the [Design Tokens specification](https://design-tokens.github.io/community-group/format/)
85
90
  - You can also push directly to supported services (JSONBin, GitHub, GitLab, etc.)
86
91
 
87
92
  #### Import (JSON → Variables)
93
+
88
94
  - Click **"Import JSON"** to import design tokens from a JSON file back into Figma
89
95
  - The plugin will create variable collections, modes, and variables based on the JSON structure
90
96
  - Supports both DTCG format (`$value`, `$type`) and standard format (`value`, `type`)
@@ -92,6 +98,7 @@ The plugin supports both **exporting** and **importing** design tokens:
92
98
  - Creates new collections and variables as needed, or updates existing ones
93
99
 
94
100
  **Import Features:**
101
+
95
102
  - ✅ Creates variable collections from top-level objects
96
103
  - ✅ Supports multiple modes (from `$extensions.mode` or `extensions.mode`)
97
104
  - ✅ Handles all variable types (color, number, string, boolean)
@@ -99,6 +106,9 @@ The plugin supports both **exporting** and **importing** design tokens:
99
106
  - ✅ Supports various color formats (HEX, RGBA CSS, RGBA Object)
100
107
  - ✅ Preserves variable descriptions and metadata
101
108
 
109
+ > [!WARNING]
110
+ > **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.
111
+
102
112
  ---
103
113
 
104
114
  ## General settings
@@ -143,6 +153,28 @@ Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api
143
153
  }
144
154
  ```
145
155
 
156
+ ### Use percentage for opacity
157
+
158
+ Is `off` by default. When enabled, opacity values will be exported as percentages instead of normalized decimal values. This affects variables with the `OPACITY` scope.
159
+
160
+ ```json
161
+ // Without percentage format (default)
162
+ {
163
+ "opacity": {
164
+ "type": "number",
165
+ "value": 0.1
166
+ }
167
+ }
168
+
169
+ // With percentage format
170
+ {
171
+ "opacity": {
172
+ "type": "string",
173
+ "value": "10%"
174
+ }
175
+ }
176
+ ```
177
+
146
178
  ### Use DTCG keys format
147
179
 
148
180
  Is `off` by default. Currently many design tokens tools doesn't support [DTCG keys format](https://design-tokens.github.io/community-group/format/#character-restrictions). All DTCG keys are prefixed with `$` symbol.
@@ -215,6 +247,15 @@ Is `off` by default. Allows you to include Figma metadata like `styleId`, `varia
215
247
  }
216
248
  ```
217
249
 
250
+ ### Split collections into separate files
251
+
252
+ Is `off` by default. When enabled, each Figma variable collection is exported as its own file instead of a single merged JSON.
253
+
254
+ - **Download JSON** — produces a `design.tokens.zip` archive containing one `{CollectionName}.tokens.json` per collection.
255
+ - **CLI** — writes individual `{CollectionName}.tokens.json` files into the directory specified by `--output`.
256
+
257
+ This is useful when you want to keep component-level token files separate (e.g. `button.tokens.json`, `card.tokens.json`).
258
+
218
259
  ---
219
260
 
220
261
  ## Use as cli tool
@@ -244,14 +285,30 @@ tokens-bruecke [options]
244
285
  For example:
245
286
 
246
287
  ```bash
288
+ # Using a Personal Access Token (PAT)
247
289
  tokens-bruecke --api-key $FIGMA_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json
290
+
291
+ # Using an OAuth token
292
+ tokens-bruecke --oauth-token $FIGMA_OAUTH_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json
248
293
  ```
249
294
 
250
295
  This will fetch figma variables and export them in `out/tokens.json`
251
296
 
252
297
  ### Options
253
298
 
254
- Same options than the plugin are available throught the usage of a json file.
299
+ | Option | Alias | Description | Required |
300
+ | ----------------------- | ----- | --------------------------------------------------------------------- | ------------------------------------------------- |
301
+ | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token` is required |
302
+ | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token` is required |
303
+ | `--file-key` | `-f` | Figma file key | Yes |
304
+ | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` | Yes |
305
+ | `--config` | `-c` | Path to configuration file | No |
306
+ | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
307
+
308
+ > [!TIP]
309
+ > For automated pipelines, `--oauth-token` is preferred over `--api-key`. Personal Access Tokens expire every 90 days and require manual renewal, while OAuth tokens support programmatic refresh for indefinite access.
310
+
311
+ Other export settings are available through a JSON configuration file (see [CLI Configuration File](#cli-configuration-file) below).
255
312
 
256
313
  ### CLI Configuration File
257
314
 
@@ -269,8 +326,10 @@ You can use a JSON configuration file to specify the export options for the CLI.
269
326
  "useDTCGKeys": false,
270
327
  "includeValueStringKeyToAlias": true,
271
328
  "includeFigmaMetaData": false, // Include Figma metadata like styleId, variableId, etc.
329
+ "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
272
330
  "colorMode": "hex", // "hex" | "rgba-object" | "rgba-css" | "hsla-object" | "hsla-css";
273
- "storeStyleInCollection": "none" // Name of one of your collection or "none" to keep them separated
331
+ "storeStyleInCollection": "none", // Name of one of your collection or "none" to keep them separated
332
+ "splitByCollection": false // Write each collection as a separate .tokens.json file
274
333
  }
275
334
  ```
276
335
 
@@ -659,7 +718,7 @@ In order to validate types, the plugin uses the [Design Tokens types](https://gi
659
718
  In order to convert `FONT-WEIGHT` and `OPACITY` types into valid values you should specify thme as scopes in the Figma variables. The plugin will read the first scope and convert it into the valid value. If there are multiple scopes, the plugin will take the first one.
660
719
 
661
720
  - `FONT_WEIGHT` scope will be converted into `string` type.
662
- - `OPACITY` scope will be converted into `number` type.
721
+ - `OPACITY` scope will be converted into `number` type (or `string` with `%` if "Use percentage for opacity" is enabled).
663
722
 
664
723
  ---
665
724