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 +12 -0
- package/README.md +110 -73
- package/bin/cli.js +1 -1
- package/examples/tokens-snapshot.json +21 -4
- package/llms.txt +1 -1
- package/package.json +1 -1
- package/schemas/cli-options.schema.json +3 -3
- package/schemas/tokens-snapshot.schema.json +101 -8
- package/skills/tokens-bruecke/SKILL.md +26 -22
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
111
|
-
- ✅
|
|
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
|
|
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
|

|
|
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
|
|
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
|
|
519
|
-
| ------------------------- | ----- |
|
|
520
|
-
| `--api-key` | `-a` | Figma personal access token (PAT)
|
|
521
|
-
| `--oauth-token` | `-t` | Figma OAuth token
|
|
522
|
-
| `--file-key` | `-f` | Figma file key
|
|
523
|
-
| `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin)
|
|
524
|
-
| `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode`
|
|
525
|
-
| `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split
|
|
526
|
-
| `--config` | `-c` | Path to configuration file
|
|
527
|
-
| `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output`
|
|
528
|
-
| `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output`
|
|
529
|
-
| `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace
|
|
530
|
-
| `--quiet` | `-q` | Suppress progress logs (errors are still printed)
|
|
531
|
-
| `--help` | `-h` | Show usage help
|
|
532
|
-
| `--version` | | Show the CLI version
|
|
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, //
|
|
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) => ({
|
|
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
|

|
|
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
|
|
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
|

|
|
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
|
-
|
|
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
|

|
|
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
|
|
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
|

|
|
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
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
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
|
|
1009
|
+
### Multiple shadows support
|
|
974
1010
|
|
|
975
|
-
If
|
|
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
|
|
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
|
|
1162
|
-
| ---------- |
|
|
1163
|
-
| COLOR | —
|
|
1164
|
-
| BOOLEAN | —
|
|
1165
|
-
| FLOAT | `FONT_WEIGHT`
|
|
1166
|
-
| FLOAT |
|
|
1167
|
-
| FLOAT |
|
|
1168
|
-
| FLOAT | all other scopes
|
|
1169
|
-
| STRING |
|
|
1170
|
-
|
|
|
1171
|
-
|
|
|
1172
|
-
|
|
1173
|
-
|
|
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
|
|
1248
|
+
## Scopes limitations
|
|
1212
1249
|
|
|
1213
|
-
|
|
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
|
|
1216
|
-
- `OPACITY`
|
|
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
|
|