tokens-bruecke 3.20.0 → 3.22.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 +47 -0
- package/README.md +29 -15
- package/api.d.ts +12 -2
- package/bin/api.js +1 -1
- package/bin/api.mjs +1 -1
- package/bin/cli.js +1 -1
- package/global.d.ts +18 -33
- package/package.json +3 -2
- package/schemas/tokens-snapshot.schema.json +4 -4
- package/skills/tokens-bruecke/SKILL.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,50 @@
|
|
|
1
|
+
## [3.22.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.21.0...v3.22.0) (2026-10-28)
|
|
2
|
+
|
|
3
|
+
### Behaviour changes
|
|
4
|
+
|
|
5
|
+
- **export:** with DTCG on, a variable named like a group of other variables (`border/brand` next to `border/brand/subtle`) becomes the group's `$root` token, and aliases to it end in `.$root` (DTCG 2025.10 §6.2). The import reads both this and the old shape.
|
|
6
|
+
- **export:** `.`, `{` and `}` in a collection name become `-` in its token key (`1. Primitives` → `1- Primitives`), with a warning. The meta keeps the Figma name, so the import maps it back.
|
|
7
|
+
- **export:** the `hex` fallback of DTCG color objects has 6 digits; the opacity is only in `alpha`. The import still reads 8-digit values.
|
|
8
|
+
- **export:** opacity tokens carry `$extensions.figmaScopes` when `includeScopes` is off, so they import as percentages again.
|
|
9
|
+
- **cli:** REST mode exports collections hidden from publishing, as the plugin does.
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
- **export:** fix export, import and REST-mode issues found in real files ([#135](https://github.com/tokens-bruecke/figma-plugin/issues/135)) ([6fe1936](https://github.com/tokens-bruecke/figma-plugin/commit/6fe1936d5b038a69d41cd74dbb41092ee9eb1fa9))
|
|
14
|
+
|
|
15
|
+
Thanks to [@skraegelin](https://github.com/skraegelin) for [#135](https://github.com/tokens-bruecke/figma-plugin/pull/135).
|
|
16
|
+
|
|
17
|
+
## [3.21.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.20.0...v3.21.0) (2026-10-27)
|
|
18
|
+
|
|
19
|
+
### Features
|
|
20
|
+
|
|
21
|
+
- **api:** keep warnings out of the console, with an onWarning option ([869cc51](https://github.com/tokens-bruecke/figma-plugin/commit/869cc51c5134b105126edf1f3f8ad49f62de0dd2))
|
|
22
|
+
|
|
23
|
+
### Behaviour changes
|
|
24
|
+
|
|
25
|
+
- **api:** `tokens-bruecke/api` no longer prints export warnings (skipped variables and styles, aliases to missing variables, name collisions) to the console. Pass `onWarning` to receive them: `fetchTokens({ …, onWarning })` or `convertTokens(input, options, { onWarning })`. The CLI and the plugin still print them.
|
|
26
|
+
|
|
27
|
+
### Bug Fixes
|
|
28
|
+
|
|
29
|
+
- **cli:** export an alias into a hidden collection as `#missing#` ([8f1ac2d](https://github.com/tokens-bruecke/figma-plugin/commit/8f1ac2d2220d4f613223aa08513652bef7baa8ca))
|
|
30
|
+
- export bound shadow blur as an alias ([688d568](https://github.com/tokens-bruecke/figma-plugin/commit/688d5684f12e13c9ee47e3ad44c9dc52d36263d0))
|
|
31
|
+
- **export:** keep styles separate when their collection is missing ([7249e82](https://github.com/tokens-bruecke/figma-plugin/commit/7249e8239f2d1c9b633b85039bc13baf6788141a))
|
|
32
|
+
- **export:** leave the collection out of style aliases with omitCollectionNames ([5346526](https://github.com/tokens-bruecke/figma-plugin/commit/534652616d70549a694b9e8ea4b4c3cb21010d29))
|
|
33
|
+
- **export:** skip styles that cannot be exported instead of failing ([fdeb4f3](https://github.com/tokens-bruecke/figma-plugin/commit/fdeb4f36599d46d580293f405fbd17fce93504a5))
|
|
34
|
+
- **import:** resolve names with dots and skip tokens of another type ([3692fd7](https://github.com/tokens-bruecke/figma-plugin/commit/3692fd7b17d272b0afc53603f27b43d945804756))
|
|
35
|
+
- **import:** write opacity into an existing opacity variable as percent ([3eae585](https://github.com/tokens-bruecke/figma-plugin/commit/3eae5856d719356d0d4bf39e36f9f3202e35b04c))
|
|
36
|
+
- **plugin:** accept GitLab hosts with a scheme and owners with subgroups ([f68988f](https://github.com/tokens-bruecke/figma-plugin/commit/f68988fd9c52b43ea659e868e0b344a46d75d56f))
|
|
37
|
+
- **plugin:** fill "Add styles to" with the open file's collections ([da444f0](https://github.com/tokens-bruecke/figma-plugin/commit/da444f06543c33f74cd42ac3838d608c363d9011))
|
|
38
|
+
- **plugin:** report export, import and push errors in the UI ([ff510fe](https://github.com/tokens-bruecke/figma-plugin/commit/ff510fed70754d77612962634e160ed7936e966b))
|
|
39
|
+
|
|
40
|
+
Thanks to [@skraegelin](https://github.com/skraegelin), whose fork these fixes come from ([#132](https://github.com/tokens-bruecke/figma-plugin/pull/132)).
|
|
41
|
+
|
|
42
|
+
## [3.20.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.19.0...v3.20.0) (2026-10-18)
|
|
43
|
+
|
|
44
|
+
### Features
|
|
45
|
+
|
|
46
|
+
- **cli:** print a notice when a newer version is on npm ([01d9fb6](https://github.com/tokens-bruecke/figma-plugin/commit/01d9fb6699ceb6bd4bb6d40d2e3287a1ef193033))
|
|
47
|
+
|
|
1
48
|
## [3.19.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.18.0...v3.19.0) (2026-10-14)
|
|
2
49
|
|
|
3
50
|
### Features
|
package/README.md
CHANGED
|
@@ -116,10 +116,13 @@ The plugin supports both **exporting** and **importing** design tokens:
|
|
|
116
116
|
|
|
117
117
|
**What to know before importing:**
|
|
118
118
|
|
|
119
|
-
-
|
|
119
|
+
- Tokens without their own `$type` take it from the closest group, as DTCG allows; an alias without a type takes the type of the token it references.
|
|
120
|
+
- Every top-level key becomes a collection. Files exported with [Omit collection names](#omit-collection-names) don't map back to the original collections.
|
|
121
|
+
- A file of a [split-by-mode export](#split-modes-into-separate-files) carries its mode in the meta, so its values go into that mode of the collection, which is added if it's missing. Import the files one by one; the first one imported into a new collection becomes its default mode.
|
|
120
122
|
- An existing collection's first mode is renamed to the first mode in the tokens.
|
|
121
123
|
- Units are dropped from dimensions, since Figma number variables have no unit: `1rem` imports as `1`.
|
|
122
|
-
- Extended collections are imported as regular collections.
|
|
124
|
+
- Extended collections are imported as regular collections when they don't exist in the file yet. If the extended collection exists, its tokens update the variables it inherits: the values become overrides for its modes. New variables and modes can't be added to an extended collection, so those tokens are reported as errors.
|
|
125
|
+
- An existing variable keeps its type. A token of another type, for example a `dimension` token for a color variable, is skipped and listed in the import result.
|
|
123
126
|
|
|
124
127
|
> [!WARNING]
|
|
125
128
|
> **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.
|
|
@@ -141,6 +144,8 @@ Allows you to choose the color mode for the generated JSON. Default value is `HE
|
|
|
141
144
|
- `HSL DTCG` — HSL color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#hsl)
|
|
142
145
|
- `OKLCH DTCG` — OKLCH color format in object syntax matching the [DTCG specification](https://www.designtokens.org/tr/2025.10/color/#oklch)
|
|
143
146
|
|
|
147
|
+
The DTCG color objects carry the opacity in `alpha` and a 6-digit `hex` fallback, as the specification requires. Older exports wrote an 8-digit `hex` for translucent colors; the import reads both.
|
|
148
|
+
|
|
144
149
|
### Include styles
|
|
145
150
|
|
|
146
151
|
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.
|
|
@@ -151,7 +156,7 @@ There is an option to rename each style's group and give it a custom name for be
|
|
|
151
156
|
|
|
152
157
|
### Add styles to
|
|
153
158
|
|
|
154
|
-
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).
|
|
159
|
+
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). If that collection isn't in the export (for example in another file, or with [Omit collection names](#omit-collection-names)), the styles are kept separate.
|
|
155
160
|
|
|
156
161
|

|
|
157
162
|
|
|
@@ -229,6 +234,7 @@ Is `on` by default. Aligns the output with the [DTCG 2025.10 specification](http
|
|
|
229
234
|
- All token keys are prefixed with the `$` symbol (`$value`, `$type`, `$description`).
|
|
230
235
|
- 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.
|
|
231
236
|
- The root `$extensions["tokens-bruecke-meta"]` includes a `spec` field with the canonical spec URL, so downstream tools know which format to expect.
|
|
237
|
+
- A variable named like a group of other variables (`border/brand` next to `border/brand/subtle`) becomes the group's root token per DTCG 2025.10 §6.2: `border.brand.$root`. References to it point at `{….border.brand.$root}`. With the format off, the token and the group share one object, as before. The import reads both shapes.
|
|
232
238
|
|
|
233
239
|
```json
|
|
234
240
|
// Off — native Figma format
|
|
@@ -393,7 +399,7 @@ Is `off` by default. When enabled, the plugin drops the top-level collection nam
|
|
|
393
399
|
}
|
|
394
400
|
```
|
|
395
401
|
|
|
396
|
-
Alias references are also rewritten so they point to the flat path (the collection prefix is removed).
|
|
402
|
+
Alias references, including the ones in styles, are also rewritten so they point to the flat path (the collection prefix is removed).
|
|
397
403
|
|
|
398
404
|
> [!WARNING]
|
|
399
405
|
> If two variables in different collections share the same name, the last one wins and a collision warning is logged to the console. Rename conflicting variables (or keep this option off) to avoid losing values.
|
|
@@ -567,6 +573,8 @@ The REST API returns variables, collections and styles in no fixed order, so the
|
|
|
567
573
|
|
|
568
574
|
In REST mode the CLI exports the file's own styles, published or not, the same set the plugin exports. This also works for a branch, which can't publish styles. Styles that come from a library are left out, as in the plugin.
|
|
569
575
|
|
|
576
|
+
The REST API reports letter spacing in pixels only, so a text style with percentage letter spacing exports as `{ "value": -0.32, "unit": "px" }` in REST mode, where the plugin writes `"-2%"`. Snapshot mode keeps the plugin's unit.
|
|
577
|
+
|
|
570
578
|
### Snapshot input
|
|
571
579
|
|
|
572
580
|
`--input <path>` transforms a local JSON snapshot of a Figma file's variables and styles instead of calling the REST API. `--input -` reads stdin, so it composes with anything that can dump the data:
|
|
@@ -606,7 +614,6 @@ Things worth knowing when building a snapshot:
|
|
|
606
614
|
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
607
615
|
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
608
616
|
- [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.
|
|
609
|
-
- Unlike REST mode, snapshot mode doesn't drop collections hidden from publishing. Leave out anything you don't want exported.
|
|
610
617
|
- 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.
|
|
611
618
|
- 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).
|
|
612
619
|
|
|
@@ -746,7 +753,7 @@ Snapshot mode ignores `FIGMA_API_KEY` / `FIGMA_FILE_KEY`, so a token exported in
|
|
|
746
753
|
On a bad snapshot the CLI exits `1` and names the offending key — for example `variables[3] is missing a string "variableCollectionId"` — so an agent can correct its dump and retry without guesswork.
|
|
747
754
|
|
|
748
755
|
> [!NOTE]
|
|
749
|
-
> Aliases pointing at variables outside the snapshot
|
|
756
|
+
> Aliases pointing at variables outside the snapshot export as `"#missing#"`. To resolve aliases to library variables from another file, include those variables in the `variables` array and their collections in `variableCollections`, with `"remote": true`: they resolve the aliases, as in the plugin and in REST mode, but aren't exported.
|
|
750
757
|
|
|
751
758
|
---
|
|
752
759
|
|
|
@@ -775,6 +782,7 @@ const fromRest = await convertTokens(restResponse); // GET /v1/files/:key/variab
|
|
|
775
782
|
- **`convertTokens`** accepts a [snapshot](#snapshot-input), or the raw response of the Figma REST variables endpoint (detected by its `meta` key). That response has no styles, so enabling any `includedStyles` with it throws `INVALID_ARGUMENT`.
|
|
776
783
|
- **Module formats:** the package ships an ESM and a CommonJS build of `tokens-bruecke/api`, so both `import` and `require` work. Each build has its own `TokensBrueckeError` class, so check `error.code` rather than `instanceof` if your code mixes the two.
|
|
777
784
|
- **No side effects:** the API does not write files, read environment variables, log or exit the process.
|
|
785
|
+
- **Warnings** (skipped variables and styles, aliases to variables missing from the data, name collisions) are not printed. Pass `onWarning` to receive them: `fetchTokens({ …, onWarning })` or `convertTokens(input, options, { onWarning })`.
|
|
778
786
|
- **Errors** are `TokensBrueckeError`s with a `code` (`INVALID_ARGUMENT`, `INVALID_SNAPSHOT`, `FIGMA_FORBIDDEN`, `FIGMA_NOT_FOUND`, `FIGMA_RATE_LIMITED`, `FIGMA_REQUEST_FAILED`, `CONVERSION_FAILED`) and the original error as `cause`. `FIGMA_FORBIDDEN` usually means the file is not on an Enterprise plan, or the token lacks the `file_variables:read` scope.
|
|
779
787
|
|
|
780
788
|
### Split results
|
|
@@ -789,7 +797,7 @@ for (const [key, tree] of Object.entries(tokens)) {
|
|
|
789
797
|
```
|
|
790
798
|
|
|
791
799
|
- **Aliases** inside a tree are qualified with the collection name (for example `{Semantic.spacing.md}`), so the tree has to be wrapped in `{ [collection]: tree }` for references to resolve.
|
|
792
|
-
- **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names.
|
|
800
|
+
- **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are, except that `.`, `{` and `}` in a collection name become `-` (`1. Primitives` is keyed as `1- Primitives`), because references use them. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names. Match the key against the collection names in `$extensions["tokens-bruecke-meta"].variableCollections`, with those characters replaced, instead, as the CLI does.
|
|
793
801
|
|
|
794
802
|
---
|
|
795
803
|
|
|
@@ -840,9 +848,9 @@ If a pull request from that branch is already open, the plugin updates it instea
|
|
|
840
848
|
|
|
841
849
|
### [GitLab](https://gitlab.com)
|
|
842
850
|
|
|
843
|
-
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`.
|
|
851
|
+
1. You need to create a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` scope. To push to a protected branch such as `main`, the token needs the Maintainer role; otherwise use a branch of its own and merge it with a merge request. For a self-hosted GitLab, fill in the host field, e.g. `gitlab.acme.com` (a leading `https://` and a trailing `/` are ignored); it defaults to `gitlab.com`.
|
|
844
852
|
2. In the plugin settings paste the token into the `Project access token` field.
|
|
845
|
-
3. Add
|
|
853
|
+
3. Add the owner, the repository name and a branch name. The owner is the user or group from the project URL, including subgroups: for `https://gitlab.acme.com/acme/frontend/design-system` it is `acme/frontend` and the repository is `design-system`. The branch must exist.
|
|
846
854
|
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`.
|
|
847
855
|
5. You can also specify a commit message.
|
|
848
856
|
|
|
@@ -852,7 +860,7 @@ If a pull request from that branch is already open, the plugin updates it instea
|
|
|
852
860
|
|
|
853
861
|
### Custom server
|
|
854
862
|
|
|
855
|
-
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.
|
|
863
|
+
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, written as a JSON object, e.g. `{"Authorization": "Bearer <token>"}`.
|
|
856
864
|
|
|
857
865
|
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.
|
|
858
866
|
|
|
@@ -924,6 +932,8 @@ Supported styles:
|
|
|
924
932
|
- Shadows (including `inset` shadows)
|
|
925
933
|
- Blur (including `background` and `layer` blur)
|
|
926
934
|
|
|
935
|
+
A style the plugin can't export, such as an image fill or a color style with several paints, is left out and the rest of the export continues. The plugin logs a `[tokens-bruecke] Skipped style …` warning to the console (`Plugins → Development → Open console`, or stderr for the CLI).
|
|
936
|
+
|
|
927
937
|
### Typography
|
|
928
938
|
|
|
929
939
|
```json
|
|
@@ -950,7 +960,7 @@ Supported styles:
|
|
|
950
960
|
|
|
951
961
|
### Colors
|
|
952
962
|
|
|
953
|
-
The plugin supports solid colors and gradients (linear, radial, angular, diamond). Color styles are converted to DTCG format with support for variable aliases.
|
|
963
|
+
The plugin supports solid colors and gradients (linear, radial, angular, diamond). Color styles are converted to DTCG format with support for variable aliases. A solid style bound to a color variable with its own opacity below 100% is exported like a [color alias with opacity](#color-aliases-with-opacity): `{ "components": "{color.brand}", "alpha": 0.5 }`.
|
|
954
964
|
|
|
955
965
|
```json
|
|
956
966
|
// Solid color
|
|
@@ -995,7 +1005,7 @@ DTCG has no direction or type for a gradient, only the stops, so they are export
|
|
|
995
1005
|
|
|
996
1006
|
### Grids
|
|
997
1007
|
|
|
998
|
-
In Figma you can add as many grids in the style as you want.
|
|
1008
|
+
In Figma you can add as many grids in the style as you want. The plugin exports the first `Columns` grid as `column*` values and the first `Rows` grid as `row*` values; further grids of the same kind are left out. A square `Grid` only has a cell size, which is exported as `columnWidth` when the style has no columns. Sizes of `0` are kept, and an `Auto` count is left out.
|
|
999
1009
|
|
|
1000
1010
|
```json
|
|
1001
1011
|
// Column grid
|
|
@@ -1036,6 +1046,8 @@ In Figma you can add as many grids in the style as you want. But the plugin will
|
|
|
1036
1046
|
|
|
1037
1047
|
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.
|
|
1038
1048
|
|
|
1049
|
+
The first effect of a style decides its type: a style that starts with a shadow is exported as a `shadow` token, and blur effects in it are left out with a warning. A style that starts with a blur is exported as a `blur` token.
|
|
1050
|
+
|
|
1039
1051
|
```json
|
|
1040
1052
|
"xl": {
|
|
1041
1053
|
"type": "shadow",
|
|
@@ -1054,7 +1066,7 @@ The plugin supports `drop-shadow` and `inner-shadow` effects. If the effect is `
|
|
|
1054
1066
|
|
|
1055
1067
|
### Blur
|
|
1056
1068
|
|
|
1057
|
-
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,
|
|
1069
|
+
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. Like all other tokens, blur tokens use the `$type` / `$value` keys with the [DTCG 2025.10 format](#dtcg-202510-format) setting on, and `type` / `value` with it off.
|
|
1058
1070
|
|
|
1059
1071
|
```json
|
|
1060
1072
|
// Background blur
|
|
@@ -1172,6 +1184,8 @@ All aliases are converted into the alias string format from the [Design Tokens s
|
|
|
1172
1184
|
}
|
|
1173
1185
|
```
|
|
1174
1186
|
|
|
1187
|
+
References use `.` as separator, so DTCG forbids `.`, `{` and `}` in token and group names. A collection whose name contains them, like `1. Primitives`, is exported as `1- Primitives`, with a warning; the meta keeps the original name, and the [import](#import-json--variables) uses it to recreate the collection under its Figma name.
|
|
1188
|
+
|
|
1175
1189
|
### Include `.value` string for aliases
|
|
1176
1190
|
|
|
1177
1191
|
You can switch on the `Include .value string for aliases` option in [the plugin settings](#include-value-string-for-aliases).
|
|
@@ -1245,7 +1259,7 @@ The plugin will generate the alias name anyway, but it will be a path to the var
|
|
|
1245
1259
|
}
|
|
1246
1260
|
```
|
|
1247
1261
|
|
|
1248
|
-
The plugin wouldn't include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files.
|
|
1262
|
+
The plugin wouldn't include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files. The CLI and the library API do the same in REST mode. In snapshot mode, add the library variables and their collections with `"remote": true`: they resolve aliases but aren't exported.
|
|
1249
1263
|
|
|
1250
1264
|
So you will need to merge the file with the base variables from one file with another where you use them. Otherwise tools like Style Dictionary wouldn't be able to resolve the aliases.
|
|
1251
1265
|
|
|
@@ -1322,7 +1336,7 @@ Figma variables have no font weight, font family or opacity type, so the plugin
|
|
|
1322
1336
|
|
|
1323
1337
|
- 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`.
|
|
1324
1338
|
- A string variable whose only scope is `FONT_FAMILY` becomes a `fontFamily` token. With any other scope next to it, it stays a `string`.
|
|
1325
|
-
- 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`.
|
|
1339
|
+
- 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`. Unless [scopes are included](#include-variable-scopes), such a token carries its scopes in `$extensions.figmaScopes`, so the [import](#import-json--variables) recreates an opacity variable (50, not 0.5).
|
|
1326
1340
|
|
|
1327
1341
|
---
|
|
1328
1342
|
|
package/api.d.ts
CHANGED
|
@@ -99,7 +99,16 @@ export interface LocalVariablesResponse {
|
|
|
99
99
|
[key: string]: any;
|
|
100
100
|
}
|
|
101
101
|
|
|
102
|
-
export interface
|
|
102
|
+
export interface WarningOptions {
|
|
103
|
+
/**
|
|
104
|
+
* Receives the warnings of the export: variables and styles that were
|
|
105
|
+
* skipped, aliases to variables that are not in the data (`#missing#`),
|
|
106
|
+
* name collisions. Without it they are dropped: the API prints nothing.
|
|
107
|
+
*/
|
|
108
|
+
onWarning?: (message: string) => void;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export interface FetchTokensParams extends WarningOptions {
|
|
103
112
|
fileKey: string;
|
|
104
113
|
/** Figma personal access token. Either this or `oauthToken` is required. */
|
|
105
114
|
personalAccessToken?: string;
|
|
@@ -148,5 +157,6 @@ export declare function fetchTokens(
|
|
|
148
157
|
*/
|
|
149
158
|
export declare function convertTokens(
|
|
150
159
|
input: TokensSnapshot | LocalVariablesResponse,
|
|
151
|
-
options?: ExportOptions
|
|
160
|
+
options?: ExportOptions,
|
|
161
|
+
warnings?: WarningOptions
|
|
152
162
|
): Promise<TokenTree>;
|