tokens-bruecke 3.14.0 → 3.14.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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,15 @@
1
+ ## [3.14.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.14.0...v3.14.1) (2026-10-02)
2
+
3
+ ### Bug Fixes
4
+
5
+ - **import:** scale RGBA object colors from 0-255 to 0-1 ([1592922](https://github.com/tokens-bruecke/figma-plugin/commit/1592922779b6456996aa8b98b3488b2eb41bbe45))
6
+
7
+ ## [3.14.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.13.1...v3.14.0) (2026-10-02)
8
+
9
+ ### Features
10
+
11
+ - **color:** import color aliases with opacity now that Figma allows it ([c225d06](https://github.com/tokens-bruecke/figma-plugin/commit/c225d062727d1ab991322df68c3ff0e8d13b98b2)), closes [figma/plugin-typings#375](https://github.com/figma/plugin-typings/issues/375)
12
+
1
13
  ## [3.13.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.13.0...v3.13.1) (2026-10-02)
2
14
 
3
15
  ### Bug Fixes
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # TokensBruecke — Figma plugin
1
+ # TokensBruecke — Figma plugin and CLI
2
2
 
3
3
  <a href="https://www.figma.com/community/plugin/1254538877056388290" target="_blank">
4
4
  <img src="./readme-assets/preview.webp" alt="preview" width="100%">
@@ -6,7 +6,7 @@
6
6
 
7
7
  ## What is this plugin for?
8
8
 
9
- The plugin converts Figma variables into design-tokens JSON that are compatible with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/).
9
+ TokensBruecke exports Figma variables and styles as design tokens JSON compatible with the [DTCG 2025.10 specification](https://www.designtokens.org/tr/2025.10/format/), and imports tokens back into Figma variables. Use it as a Figma plugin, or as a [CLI](#use-as-cli-tool) in CI and agent workflows.
10
10
 
11
11
  ---
12
12
 
@@ -58,7 +58,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
58
58
  - [Grids](#grids)
59
59
  - [Shadows](#shadows)
60
60
  - [Blur](#blur)
61
- - [Multiple `Shadow` and `Blur` styles support](#multiple-shadow-and-blur-styles-support)
61
+ - [Multiple shadows support](#multiple-shadows-support)
62
62
  - [Tokens structure](#tokens-structure)
63
63
  - [Aliases handling](#aliases-handling)
64
64
  - [Include `.value` string for aliases](#include-value-string-for-aliases-1)
@@ -68,7 +68,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
68
68
  - [Variables types conversion](#variables-types-conversion)
69
69
  - [Motion variables](#motion-variables)
70
70
  - [Design tokens types](#design-tokens-types)
71
- - [Scopes lemitations](#scopes-lemitations)
71
+ - [Scopes limitations](#scopes-limitations)
72
72
  - [Privacy and analytics](#privacy-and-analytics)
73
73
  - [Feedback](#feedback)
74
74
 
@@ -80,7 +80,7 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
80
80
  2. Make sure you have variables in your Figma file.
81
81
  3. Run the plugin.
82
82
  4. Adjust the settings.
83
- 5. Then you can download the JSON file or push it to on of the [supported services](#link).
83
+ 5. Then you can download the JSON file or push it to one of the [supported services](#push-to-server).
84
84
 
85
85
  ### Export and Import
86
86
 
@@ -95,7 +95,7 @@ The plugin supports both **exporting** and **importing** design tokens:
95
95
 
96
96
  #### Import (JSON → Variables)
97
97
 
98
- - Click **"Import JSON"** to import design tokens from a JSON file back into Figma
98
+ - Click **"Import tokens (Beta)"** to import design tokens from a JSON file back into Figma. The button is in the settings and on the "No variables found" screen
99
99
  - The plugin will create variable collections, modes, and variables based on the JSON structure
100
100
  - Supports both DTCG format (`$value`, `$type`) and standard format (`value`, `type`)
101
101
  - Handles alias references between variables
@@ -107,12 +107,19 @@ The plugin supports both **exporting** and **importing** design tokens:
107
107
  - ✅ Supports multiple modes (from `$extensions.mode` or `extensions.mode`)
108
108
  - ✅ Handles all variable types (color, number, string, boolean, timing, easing)
109
109
  - ✅ Resolves alias references between variables
110
- - ✅ Supports various color formats (HEX, RGBA CSS, RGBA Object)
111
- - ✅ Preserves variable descriptions and metadata
110
+ - ✅ Supports these color formats: HEX, RGBA CSS, RGBA Object, DTCG color objects (`srgb-dtcg`, `hsl-dtcg`, `oklch-dtcg`, through their `hex` fallback) and [color aliases with opacity](#color-aliases-with-opacity). HSLA CSS and HSLA Object can't be imported yet
111
+ - ✅ Imports variable descriptions and `scopes`. Invalid scopes are reported, and scopes are skipped on `duration` and `cubicBezier` tokens. `$extensions.figma` (code syntax, variable IDs) is ignored
112
112
  - ✅ Imports `duration` and `cubicBezier` tokens as Figma motion variables (see [Motion variables](#motion-variables))
113
113
 
114
+ **What to know before importing:**
115
+
116
+ - Every top-level key becomes a collection. Files exported with [Omit collection names](#omit-collection-names) or split by mode don't map back to the original collections.
117
+ - An existing collection's first mode is renamed to the first mode in the tokens.
118
+ - Units are dropped from dimensions, since Figma number variables have no unit: `1rem` imports as `1`.
119
+ - Extended collections are imported as regular collections.
120
+
114
121
  > [!WARNING]
115
- > **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.
122
+ > **Styles Export Limitation**: If you exported tokens with styles included (typography, grids, shadows, or blur), these cannot be imported back as Figma styles. Figma variables only have color, number, string and boolean types, plus timing and easing for motion. Solid color styles import as color variables. Typography, grid, shadow and blur tokens fall back to `STRING` variables, but their object values can't be written, so they are reported as errors in the import result.
116
123
 
117
124
  ---
118
125
 
@@ -133,7 +140,7 @@ Allows you to choose the color mode for the generated JSON. Default value is `HE
133
140
 
134
141
  ### Include styles
135
142
 
136
- Allows you to include styles into the generated JSON. See more about styles support in the [Styles support](#styles-support) section.
143
+ Allows you to include styles into the generated JSON. Text, effect, grid and color styles each have their own toggle, and all of them are `off` by default. See more about styles support in the [Styles support](#styles-support) section.
137
144
 
138
145
  There is an option to rename each style's group and give it a custom name for better organization.
139
146
 
@@ -141,13 +148,13 @@ There is an option to rename each style's group and give it a custom name for be
141
148
 
142
149
  ### Add styles to
143
150
 
144
- Allows you to choose where to put styles in the generated JSON. By default, the selected value is `Keep separate`. In this case styles will be added into the root of the JSON and will be treated as collections. There is also an option to add styles into the corresponding collection (fig.4).
151
+ Shown once at least one style type is included. Allows you to choose where to put styles in the generated JSON. By default, the selected value is `Keep separate`. In this case styles will be added into the root of the JSON and will be treated as collections. There is also an option to add styles into the corresponding collection (fig.4).
145
152
 
146
153
  ![fig.4](readme-assets/fig4.webp)
147
154
 
148
155
  ### Include variable scopes
149
156
 
150
- Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api/VariableScope). The plugin allows you to include scopes into the generated JSON. It will be included as an array of strings without any transformations.
157
+ Is `off` by default. Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api/VariableScope). The plugin allows you to include scopes into the generated JSON. It will be included as an array of strings without any transformations.
151
158
 
152
159
  ```json
153
160
  {
@@ -163,7 +170,7 @@ Each Figma variable has a [scope property](https://www.figma.com/plugin-docs/api
163
170
 
164
171
  ### Use percentage for opacity
165
172
 
166
- 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.
173
+ Is `off` by default. When enabled, opacity values will be exported as percentages instead of normalized decimal values. This affects number variables whose scopes are all `OPACITY` or `COLOR_OPACITY` (see [Scopes limitations](#scopes-limitations)).
167
174
 
168
175
  ```json
169
176
  // Without percentage format (default)
@@ -218,7 +225,6 @@ Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](http
218
225
 
219
226
  - All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`).
220
227
  - Dimensions are exported as objects per [§8.2 Dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) — `{ "value": 6, "unit": "px" }` instead of `"6px"`. This also applies to sub-values in shadows, typography, and grids.
221
- - `$type` is omitted for Figma `STRING` and `BOOLEAN` variables, since those aren't part of the DTCG type set. The original Figma type is preserved under the token's `$extensions.figmaType`.
222
228
  - The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect.
223
229
 
224
230
  ```json
@@ -332,6 +338,8 @@ Is `off` by default. When enabled, each mode of a variable collection is exporte
332
338
 
333
339
  Collections with a single mode are exported as a single `{CollectionName}.tokens.json` file.
334
340
 
341
+ Splitting by mode needs the [DTCG 2025.10 format](#dtcg-202510-format) setting on. With it off, each collection is exported as a single file.
342
+
335
343
  For example, a collection `color` with modes `light` and `dark` produces `color/light.tokens.json` and `color/dark.tokens.json`:
336
344
 
337
345
  ```json
@@ -511,25 +519,27 @@ The four questions cover the settings people change most often, but the generate
511
519
  | `--force` | | Overwrite an existing config file |
512
520
  | `--path` | `-p` | Where to write it (default: `tokens-bruecke.config.json`) |
513
521
 
514
- When stdin is not a terminal — CI, a pipe, an agent — `init` skips the questions and writes the defaults instead of hanging.
522
+ When stdin or stdout is not a terminal — CI, a pipe, an agent — `init` skips the questions and writes the defaults instead of hanging. It refuses to overwrite an existing config (exit `1`) unless you pass `--force`, and cancelling the questions exits `130` without writing anything.
523
+
524
+ The export never picks up `tokens-bruecke.config.json` on its own: pass it with `-c`.
515
525
 
516
526
  ### Options
517
527
 
518
- | Option | Alias | Description | Required |
519
- | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
520
- | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
521
- | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
522
- | `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
523
- | `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
524
- | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
525
- | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
526
- | `--config` | `-c` | Path to configuration file | No |
527
- | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
528
- | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
529
- | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
530
- | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
531
- | `--help` | `-h` | Show usage help | No |
532
- | `--version` | | Show the CLI version | No |
528
+ | Option | Alias | Description | Required |
529
+ | ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
530
+ | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
531
+ | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
532
+ | `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
533
+ | `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
534
+ | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
535
+ | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split options) | No |
536
+ | `--config` | `-c` | Path to configuration file | No |
537
+ | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
538
+ | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
539
+ | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
540
+ | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
541
+ | `--help` | `-h` | Show usage help | No |
542
+ | `--version` | | Show the CLI version | No |
533
543
 
534
544
  Progress logs are printed to **stderr**, so stdout stays clean for piping:
535
545
 
@@ -587,6 +597,8 @@ Things worth knowing when building a snapshot:
587
597
  - `valuesByMode` is keyed by **`modeId`**, not mode name — names come from the collection's `modes` array.
588
598
  - Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
589
599
  - `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
600
+ - [Extended collections](#extended-collections) need `isExtension`, `parentVariableCollectionId`, `variableOverrides`, `modes[].parentModeId` and `variableIds`. Their variables belong to the root collection, so `variableIds` is the only list of what they contain: without it the extension exports as an empty group.
601
+ - Unlike REST mode, snapshot mode doesn't drop collections hidden from publishing. Leave out anything you don't want exported.
590
602
  - 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.
591
603
  - Color aliases with their own opacity come back from the Plugin API as `{ "color": <alias or rgba>, "opacity": <0..100 or alias> }` (older Figma Desktop builds used `{ "type": "VARIABLE_EXPRESSION", "expressionFunction": "COMPOSE_COLOR", "expressionArguments": [<alias or rgba>, <0..100 or alias>] }`) — pass either through as-is, see [Color aliases with opacity](#color-aliases-with-opacity).
592
604
 
@@ -608,7 +620,7 @@ You can use a JSON configuration file to specify the export options for the CLI.
608
620
  "includeScopes": true,
609
621
  "useDTCG": true, // DTCG 2025.10 format: $-prefixed keys, dimension objects, spec-valid types
610
622
  "includeValueStringKeyToAlias": true,
611
- "includeFigmaMetaData": false, // Include Figma metadata like styleId, variableId, etc.
623
+ "includeFigmaMetaData": false, // Add $extensions.figma (variableId, codeSyntax, collection) to variables
612
624
  "usePercentageOpacity": false, // Export opacity as percentage (10%) instead of decimal (0.1)
613
625
  "expandEasingPresets": true, // Expand Figma's named easing presets into cubicBezier values
614
626
  "colorMode": "hex", // "hex" | "rgba-object" | "srgb-dtcg" | "rgba-css" | "hsla-object" | "hsl-dtcg" | "hsla-css" | "oklch-dtcg";
@@ -624,6 +636,8 @@ Save this JSON file and pass it to the CLI using the `--config` option. A JSON s
624
636
  > [!NOTE]
625
637
  > Explicit CLI flags (e.g. `--split-by-collection`) override values from the config file, which override the defaults.
626
638
 
639
+ Each style type in `includedStyles` is merged with its default, so `"text": { "isIncluded": true }` is enough: the group keeps its default name (`Typography-styles`) and the other style types stay excluded.
640
+
627
641
  ### For AI agents
628
642
 
629
643
  This repository and the npm package ship agent-friendly docs:
@@ -658,8 +672,17 @@ const snapshot = {
658
672
  id: c.id,
659
673
  name: c.name,
660
674
  defaultModeId: c.defaultModeId,
661
- modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
675
+ modes: c.modes.map((m) => ({
676
+ modeId: m.modeId,
677
+ name: m.name,
678
+ parentModeId: m.parentModeId,
679
+ })),
662
680
  variableIds: c.variableIds,
681
+ // Extended collections only (undefined otherwise)
682
+ isExtension: c.isExtension,
683
+ parentVariableCollectionId: c.parentVariableCollectionId,
684
+ rootVariableCollectionId: c.rootVariableCollectionId,
685
+ variableOverrides: c.variableOverrides,
663
686
  })),
664
687
  variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({
665
688
  id: v.id,
@@ -710,12 +733,12 @@ On a bad snapshot the CLI exits `1` and names the offending key — for example
710
733
 
711
734
  ## Push to server
712
735
 
713
- With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports [JSONBin](https://jsonbin.io), [GitHub](https://github.com) and custom servers.
736
+ With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports [JSONBin](https://jsonbin.io), [GitHub](https://github.com) (direct commit or pull request), [GitLab](https://gitlab.com) and custom servers.
714
737
 
715
738
  ![fig.5](readme-assets/fig5.webp)
716
739
 
717
740
  If you connected multiple servers, the plugin will try to push the tokens to all of them one by one.
718
- In ordere to test if your credentials are valid you can make a test request by clicking the `Push to server` button (fig.6).
741
+ In order to test if your credentials are valid you can make a test request by clicking the `Push to server` button (fig.6).
719
742
 
720
743
  ![fig.6](readme-assets/fig6.webp)
721
744
 
@@ -742,16 +765,20 @@ In ordere to test if your credentials are valid you can make a test request by c
742
765
 
743
766
  ### [GitHub PR](https://github.com)
744
767
 
745
- All the steps are the same as for the [GitHub](#github) server, except the last two.
768
+ Instead of committing to a branch directly, the plugin commits the tokens to a separate branch and opens a pull request. The token, owner, repo, file name and commit message fields work the same as for the [GitHub](#github) server. The other fields:
746
769
 
770
+ - **Base branch** (required). The branch the pull request targets, e.g. `main`.
771
+ - **Branch name** (optional). The branch the tokens are committed to. Defaults to `tokens-bruecke/update-tokens`. It is reset to a new commit on top of the base branch on every push, so don't commit anything else to it.
747
772
  - **PR title**. You can specify a title for the PR. If you leave it empty, the plugin will use `chore(tokens): update tokens` as a default title.
748
773
  - **PR body**. You can specify a body for the PR. If you leave it empty, the plugin won't add any body to the PR.
749
774
 
775
+ If a pull request from that branch is already open, the plugin updates it instead of opening a new one. After a push, the toast shows an **Open Pull Request** link.
776
+
750
777
  ![fig.12](readme-assets/fig12.webp)
751
778
 
752
779
  ### [GitLab](https://gitlab.com)
753
780
 
754
- 1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope.
781
+ 1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope. For a self-hosted GitLab, fill in the host field; it defaults to `gitlab.com`.
755
782
  2. In the plugin settings paste the token into the `Project access token` field.
756
783
  3. Add an owner name, repository name and a branch name.
757
784
  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`.
@@ -763,7 +790,9 @@ All the steps are the same as for the [GitHub](#github) server, except the last
763
790
 
764
791
  ### Custom server
765
792
 
766
- There is a possibilty to connect a custom server. In order to do that you need to specify a URL, a method (by default it's `POST`) and headers.
793
+ There is a possibility to connect a custom server. In order to do that you need to specify a URL, a method (`POST` or `PUT`, by default it's `POST`) and optional headers.
794
+
795
+ JSONBin and custom servers always receive the whole JSON in one request: the [split into separate files](#split-collections-into-separate-files) settings only apply to downloads, the CLI and the Git servers.
767
796
 
768
797
  ![fig.9](readme-assets/fig9.webp)
769
798
 
@@ -842,11 +871,16 @@ Supported styles:
842
871
  "fontFamily": "Inter",
843
872
  "fontWeight": 400,
844
873
  "fontSize": "18px",
874
+ "fontStyle": "normal",
845
875
  "lineHeight": "28px",
846
- "letterSpacing": "0%"
876
+ "letterSpacing": "0%",
877
+ "paragraphSpacing": "0",
878
+ "paragraphIndent": "0",
879
+ "textDecoration": "NONE",
880
+ "textCase": "ORIGINAL"
847
881
  },
848
882
  "description": "",
849
- "extensions": {
883
+ "$extensions": {
850
884
  "styleId": "S:0ffe98ad785a13839980113831d5fbaf21724594,"
851
885
  }
852
886
  }
@@ -930,31 +964,33 @@ In Figma you can add as many grids in the style as you want. But the plugin will
930
964
 
931
965
  ### Shadows
932
966
 
933
- The plugin supports `drop-shadow` and `inner-shadow` effects. If the effect is `inner-shadow`, the plugin will set the `inset` property to `true`.
967
+ The plugin supports `drop-shadow` and `inner-shadow` effects. If the effect is `inner-shadow`, the plugin will set the `inset` property to `true`. The value is always an array, even when the style has a single shadow.
934
968
 
935
969
  ```json
936
970
  "xl": {
937
971
  "type": "shadow",
938
- "value": {
939
- "inset": false,
940
- "color": "#0000000a",
941
- "offsetX": "0px",
942
- "offsetY": "10px",
943
- "blur": "10px",
944
- "spread": "-5px"
945
- }
972
+ "value": [
973
+ {
974
+ "inset": false,
975
+ "color": "#0000000a",
976
+ "offsetX": "0px",
977
+ "offsetY": "10px",
978
+ "blur": "10px",
979
+ "spread": "-5px"
980
+ }
981
+ ]
946
982
  }
947
983
  ```
948
984
 
949
985
  ### Blur
950
986
 
951
- The plugin supports `background` and `layer` blur effects. In order to distinguish between them, the plugin adds the `role` property to the generated JSON.
987
+ The plugin supports `background` and `layer` blur effects. In order to distinguish between them, the plugin adds the `role` property to the generated JSON. Only the first effect of a blur style is exported, and blur tokens always use the `$type` / `$value` keys, whatever the [DTCG 2025.10 format](#dtcg-202510-format) setting.
952
988
 
953
989
  ```json
954
990
  // Background blur
955
991
  "sm": {
956
- "type": "blur",
957
- "value": {
992
+ "$type": "blur",
993
+ "$value": {
958
994
  "role": "background",
959
995
  "blur": "4px"
960
996
  }
@@ -962,17 +998,17 @@ The plugin supports `background` and `layer` blur effects. In order to distingui
962
998
 
963
999
  // Layer blur
964
1000
  "md": {
965
- "type": "blur",
966
- "value": {
1001
+ "$type": "blur",
1002
+ "$value": {
967
1003
  "role": "layer",
968
1004
  "blur": "12px"
969
1005
  }
970
1006
  }
971
1007
  ```
972
1008
 
973
- ### Multiple `Shadow` and `Blur` styles support
1009
+ ### Multiple shadows support
974
1010
 
975
- If the style has multiple `Shadow` or `Blur` styles, the plugin will add them into the array.
1011
+ If a shadow style has several shadows, the plugin exports all of them in the array.
976
1012
 
977
1013
  ```json
978
1014
  "new-sh": {
@@ -1147,7 +1183,7 @@ So you will need to merge the file with the base variables from one file with an
1147
1183
 
1148
1184
  ### Handle modes
1149
1185
 
1150
- If there is only one mode — the plugin wouldn't include it in a generated JSON.
1186
+ If there is only one mode, the mode values are left out: `$extensions.mode` is an empty object.
1151
1187
  If there are multiple modes, the plugin will place them under the `$extensions` objects.
1152
1188
 
1153
1189
  It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guides/modes#with-modes)
@@ -1158,19 +1194,20 @@ It follows the same pattern as used by [Cobalt](https://cobalt-ui.pages.dev/guid
1158
1194
 
1159
1195
  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).
1160
1196
 
1161
- | Figma type | Scope condition | Design Tokens type |
1162
- | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
1163
- | COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
1164
- | BOOLEAN | — | _boolean_ \* |
1165
- | FLOAT | `FONT_WEIGHT` scope | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) \* |
1166
- | FLOAT | `OPACITY` scope (no %) | _number_ \* |
1167
- | FLOAT | `OPACITY` scope (with %) | _string_ (e.g. `"10%"`) \* |
1168
- | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
1169
- | STRING | — | _string_ \* |
1170
- | TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
1171
- | EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
1172
-
1173
- \* 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).
1197
+ | Figma type | Scope condition | Design Tokens type |
1198
+ | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
1199
+ | COLOR | — | [color](https://www.designtokens.org/tr/2025.10/format/#color) |
1200
+ | BOOLEAN | — | _boolean_ \* |
1201
+ | FLOAT | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) |
1202
+ | FLOAT | opacity scopes (no %) | _number_ \* |
1203
+ | FLOAT | opacity scopes (with %) | _string_ (e.g. `"10%"`) \* |
1204
+ | FLOAT | all other scopes | [dimension](https://www.designtokens.org/tr/2025.10/format/#dimension) \*\* |
1205
+ | STRING | only `FONT_WEIGHT` | [fontWeight](https://www.designtokens.org/tr/2025.10/format/#font-weight) |
1206
+ | STRING | all other scopes | _string_ \* |
1207
+ | TIMING | — | [duration](https://www.designtokens.org/tr/2025.10/format/#duration) \*\*\* |
1208
+ | EASING | — | [cubicBezier](https://www.designtokens.org/tr/2025.10/format/#cubic-bezier) or _string_ \*\*\*\* |
1209
+
1210
+ \* native JSON types — not part of the closed DTCG 2025.10 type set. The plugin still writes them as the token's `$type`. "Opacity scopes" means every scope of the variable is `OPACITY` or `COLOR_OPACITY`, see [Scopes limitations](#scopes-limitations). Also see [this issue](https://github.com/design-tokens/community-group/issues/120#issuecomment-1279527414).
1174
1211
 
1175
1212
  \*\* 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.
1176
1213
 
@@ -1208,12 +1245,12 @@ In order to validate types, the plugin uses the [Design Tokens types](https://gi
1208
1245
 
1209
1246
  ---
1210
1247
 
1211
- ## Scopes lemitations
1248
+ ## Scopes limitations
1212
1249
 
1213
- In order to convert `FONT-WEIGHT` and `OPACITY` types into valid values you should specify them 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.
1250
+ Figma variables have no font weight or opacity type, so the plugin reads the variable's scopes to pick the token type:
1214
1251
 
1215
- - `FONT_WEIGHT` scope will be converted into `fontWeight` type.
1216
- - `OPACITY` scope will be converted into `number` type (or `string` with `%` if "Use percentage for opacity" is enabled).
1252
+ - A number or string variable whose only scope is `FONT_WEIGHT` becomes a `fontWeight` token. With any other scope next to it, it stays a `dimension` or `string`.
1253
+ - A number variable whose scopes are all `OPACITY` or `COLOR_OPACITY` (the opacity of a color variable) becomes a `number` token, or a `string` with `%` if [Use percentage for opacity](#use-percentage-for-opacity) is enabled. With any other scope next to them, it is exported as a `dimension`.
1217
1254
 
1218
1255
  ---
1219
1256