tokens-bruecke 3.4.4 → 3.6.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 +60 -0
- package/README.md +196 -16
- package/bin/cli.js +1 -1
- package/examples/tokens-snapshot.json +89 -0
- package/llms.txt +8 -1
- package/package.json +2 -1
- package/schemas/tokens-snapshot.schema.json +253 -0
- package/skills/tokens-bruecke/SKILL.md +104 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,65 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [3.5.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.4...v3.5.0) (2026-08-21)
|
|
4
|
+
|
|
5
|
+
### Features
|
|
6
|
+
|
|
7
|
+
- **cli:** add --input to transform a local tokens snapshot ([6fa80be](https://github.com/tokens-bruecke/figma-plugin/commit/6fa80be2ea3b83984bd751ef4d1317a517c121e7))
|
|
8
|
+
|
|
9
|
+
### Bug Fixes
|
|
10
|
+
|
|
11
|
+
- **cli:** keep --stdout output parseable when color styles are included ([717824f](https://github.com/tokens-bruecke/figma-plugin/commit/717824f0c34dec5b9dfdffe792d2b7a600fb5689))
|
|
12
|
+
|
|
13
|
+
## [3.4.4](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.3...v3.4.4) (2026-08-20)
|
|
14
|
+
|
|
15
|
+
### Bug Fixes
|
|
16
|
+
|
|
17
|
+
- **cli:** preserve variable aliases on bound color styles ([d93415f](https://github.com/tokens-bruecke/figma-plugin/commit/d93415fc6912e710077952c8e07ad8afa875dec1))
|
|
18
|
+
|
|
19
|
+
## [3.4.3](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.2...v3.4.3) (2026-07-20)
|
|
20
|
+
|
|
21
|
+
## [3.4.2](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.1...v3.4.2) (2026-07-18)
|
|
22
|
+
|
|
23
|
+
## [3.4.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.4.0...v3.4.1) (2026-07-17)
|
|
24
|
+
|
|
25
|
+
### Bug Fixes
|
|
26
|
+
|
|
27
|
+
- variables silently missing from export when a variable has the same name as a group ([#83](https://github.com/tokens-bruecke/figma-plugin/issues/83)) ([5c5acd3](https://github.com/tokens-bruecke/figma-plugin/commit/5c5acd377985a5820a1524b5475c538d103eb271))
|
|
28
|
+
|
|
29
|
+
## [3.4.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.3.1...v3.4.0) (2026-07-13)
|
|
30
|
+
|
|
31
|
+
### Features
|
|
32
|
+
|
|
33
|
+
- **cli:** support FIGMA\_\* env vars and add docs epilogue to --help ([127b272](https://github.com/tokens-bruecke/figma-plugin/commit/127b27258c886677ceaf69ade5b64a267d7f2ea1))
|
|
34
|
+
|
|
35
|
+
## [3.3.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.3.0...v3.3.1) (2026-07-13)
|
|
36
|
+
|
|
37
|
+
### Bug Fixes
|
|
38
|
+
|
|
39
|
+
- **cli:** restore shebang in bundled bin so npx tokens-bruecke is executable ([d29a53e](https://github.com/tokens-bruecke/figma-plugin/commit/d29a53e9fd42320966c4f3cee096cc735d72afed))
|
|
40
|
+
|
|
41
|
+
## [3.3.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.2.0...v3.3.0) (2026-07-13)
|
|
42
|
+
|
|
43
|
+
### Features
|
|
44
|
+
|
|
45
|
+
- **cli:** add --stdout/--quiet flags, agent skill, llms.txt and config JSON schema ([94f6b71](https://github.com/tokens-bruecke/figma-plugin/commit/94f6b71de5ca30de87865a57f0f91bbdffd6a3cf))
|
|
46
|
+
|
|
47
|
+
### Bug Fixes
|
|
48
|
+
|
|
49
|
+
- import variables ([0a61725](https://github.com/tokens-bruecke/figma-plugin/commit/0a61725b49c7a5cd7a0f6799717675d56078ce10))
|
|
50
|
+
|
|
51
|
+
## [3.2.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.1.0...v3.2.0) (2026-07-11)
|
|
52
|
+
|
|
53
|
+
### Features
|
|
54
|
+
|
|
55
|
+
- new code preview ([46206ff](https://github.com/tokens-bruecke/figma-plugin/commit/46206ff618455881d819a0cdcd243958c1bb93be))
|
|
56
|
+
|
|
57
|
+
## [3.1.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.0.0...v3.1.0) (2026-07-11)
|
|
58
|
+
|
|
59
|
+
### Features
|
|
60
|
+
|
|
61
|
+
- sort variables by collection order ([1ef8b7b](https://github.com/tokens-bruecke/figma-plugin/commit/1ef8b7b8683bf2ae5ddbc1e81ae4fc3875efb652))
|
|
62
|
+
|
|
3
63
|
## [3.0.0](https://github.com/tokens-bruecke/figma-plugin/compare/v2.19.0...v3.0.0) (2026-07-11)
|
|
4
64
|
|
|
5
65
|
### Features
|
package/README.md
CHANGED
|
@@ -34,9 +34,12 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
|
|
|
34
34
|
- [Use as cli tool](#use-as-cli-tool)
|
|
35
35
|
- [Installation](#installation)
|
|
36
36
|
- [Usage](#usage)
|
|
37
|
+
- [Quick setup](#quick-setup)
|
|
37
38
|
- [Options](#options)
|
|
39
|
+
- [Snapshot input](#snapshot-input)
|
|
38
40
|
- [CLI Configuration File](#cli-configuration-file)
|
|
39
41
|
- [For AI agents](#for-ai-agents)
|
|
42
|
+
- [Agentic usage without the REST API](#agentic-usage-without-the-rest-api)
|
|
40
43
|
- [Push to server](#push-to-server)
|
|
41
44
|
- [JSONBin](#jsonbin)
|
|
42
45
|
- [GitHub](#github)
|
|
@@ -351,8 +354,17 @@ Alias references are also rewritten so they point to the flat path (the collecti
|
|
|
351
354
|
|
|
352
355
|
## Use as cli tool
|
|
353
356
|
|
|
357
|
+
The CLI is published on npm: [tokens-bruecke](https://www.npmjs.com/package/tokens-bruecke)
|
|
358
|
+
|
|
359
|
+
The CLI can get its data two ways:
|
|
360
|
+
|
|
361
|
+
- **From the Figma REST API** — pass `--file-key` and a token. Requires a Figma Enterprise plan.
|
|
362
|
+
- **From a local snapshot** — pass `--input`. No token, no Enterprise plan; see [Snapshot input](#snapshot-input).
|
|
363
|
+
|
|
364
|
+
Both modes produce identical output and share every other flag.
|
|
365
|
+
|
|
354
366
|
> [!WARNING]
|
|
355
|
-
> ⚠️ You need a Figma Enterprise plan to use the Figma REST API for variables.
|
|
367
|
+
> ⚠️ You need a Figma Enterprise plan to use the Figma REST API for variables. Use `--input` if you don't have one.
|
|
356
368
|
|
|
357
369
|
### Installation
|
|
358
370
|
|
|
@@ -381,26 +393,79 @@ tokens-bruecke --api-key $FIGMA_TOKEN --file-key $FIGMA_FILE --config config.jso
|
|
|
381
393
|
|
|
382
394
|
# Using an OAuth token
|
|
383
395
|
tokens-bruecke --oauth-token $FIGMA_OAUTH_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json
|
|
396
|
+
|
|
397
|
+
# From a local snapshot — no token required
|
|
398
|
+
tokens-bruecke --input snapshot.json --output out/tokens.json
|
|
384
399
|
```
|
|
385
400
|
|
|
386
401
|
This will fetch figma variables and export them in `out/tokens.json`
|
|
387
402
|
|
|
403
|
+
### Quick setup
|
|
404
|
+
|
|
405
|
+
`tokens-bruecke init` asks a few questions and writes a config file you can commit:
|
|
406
|
+
|
|
407
|
+
```bash
|
|
408
|
+
tokens-bruecke init
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
```
|
|
412
|
+
? Color mode (↑↓ to move, enter to select)
|
|
413
|
+
❯ HEX "#3366ff"
|
|
414
|
+
RGBA CSS "rgba(51, 102, 255, 1)"
|
|
415
|
+
RGBA Object { r, g, b, a }
|
|
416
|
+
sRGB DTCG DTCG color object
|
|
417
|
+
HSLA CSS "hsla(225, 100%, 60%, 1)"
|
|
418
|
+
HSLA Object { h, s, l, a }
|
|
419
|
+
HSL DTCG DTCG color object
|
|
420
|
+
OKLCH DTCG DTCG color object
|
|
421
|
+
|
|
422
|
+
? Styles to include (space to toggle, a for all, enter to confirm)
|
|
423
|
+
❯ ◉ Color styles
|
|
424
|
+
◯ Typography styles
|
|
425
|
+
◉ Effect styles
|
|
426
|
+
◯ Grid styles
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
Each answered question collapses to a single line, so you end up with a short summary rather than a wall of text:
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
? Color mode › OKLCH DTCG
|
|
433
|
+
? Styles to include › Color styles, Effect styles
|
|
434
|
+
? Use DTCG 2025.10 format? › No
|
|
435
|
+
? Output layout › One file per collection
|
|
436
|
+
|
|
437
|
+
✨ Created tokens-bruecke.config.json
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
**Keys:** `↑`/`↓` (or `j`/`k`, or `Tab`) to move, `1`–`9` to jump straight to a row, `Space` to toggle in multi-select, `a` to toggle all, `Enter` to confirm, `Ctrl+C` / `Esc` to cancel without writing anything. Selection wraps at both ends. Set `NO_COLOR=1` to drop the colour codes.
|
|
441
|
+
|
|
442
|
+
The four questions cover the settings people change most often, but the generated file contains **every** option with its default, plus a `$schema` link — so your editor autocompletes and documents the rest as you edit it.
|
|
443
|
+
|
|
444
|
+
| Option | Alias | Description |
|
|
445
|
+
| --------- | ----- | --------------------------------------------------------- |
|
|
446
|
+
| `--yes` | `-y` | Skip the questions and write the default config |
|
|
447
|
+
| `--force` | | Overwrite an existing config file |
|
|
448
|
+
| `--path` | `-p` | Where to write it (default: `tokens-bruecke.config.json`) |
|
|
449
|
+
|
|
450
|
+
When stdin is not a terminal — CI, a pipe, an agent — `init` skips the questions and writes the defaults instead of hanging.
|
|
451
|
+
|
|
388
452
|
### Options
|
|
389
453
|
|
|
390
|
-
| Option | Alias | Description | Required
|
|
391
|
-
| ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- |
|
|
392
|
-
| `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token
|
|
393
|
-
| `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token
|
|
394
|
-
| `--file-key` | `-f` | Figma file key | Yes
|
|
395
|
-
| `--
|
|
396
|
-
| `--
|
|
397
|
-
| `--
|
|
398
|
-
| `--
|
|
399
|
-
| `--split-by-
|
|
400
|
-
| `--
|
|
401
|
-
| `--
|
|
402
|
-
| `--
|
|
403
|
-
| `--
|
|
454
|
+
| Option | Alias | Description | Required |
|
|
455
|
+
| ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
456
|
+
| `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
|
|
457
|
+
| `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
|
|
458
|
+
| `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
|
|
459
|
+
| `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
|
|
460
|
+
| `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
|
|
461
|
+
| `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
|
|
462
|
+
| `--config` | `-c` | Path to configuration file | No |
|
|
463
|
+
| `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
|
|
464
|
+
| `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
|
|
465
|
+
| `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
|
|
466
|
+
| `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
|
|
467
|
+
| `--help` | `-h` | Show usage help | No |
|
|
468
|
+
| `--version` | | Show the CLI version | No |
|
|
404
469
|
|
|
405
470
|
Progress logs are printed to **stderr**, so stdout stays clean for piping:
|
|
406
471
|
|
|
@@ -420,9 +485,52 @@ tokens-bruecke -f $FIGMA_FILE -o out/tokens.json
|
|
|
420
485
|
|
|
421
486
|
Other export settings are available through a JSON configuration file (see [CLI Configuration File](#cli-configuration-file) below).
|
|
422
487
|
|
|
488
|
+
### Snapshot input
|
|
489
|
+
|
|
490
|
+
`--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:
|
|
491
|
+
|
|
492
|
+
```bash
|
|
493
|
+
# From a file
|
|
494
|
+
tokens-bruecke --input snapshot.json --output out/tokens.json
|
|
495
|
+
|
|
496
|
+
# From a pipe
|
|
497
|
+
my-figma-dumper | tokens-bruecke --input - --stdout --quiet > tokens.json
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
This is the path for **agents and plugins running inside Figma**: they already have Plugin API access to the open file, so they can dump the local variables and styles and pipe them straight through — no personal access token, and no Enterprise plan.
|
|
501
|
+
|
|
502
|
+
Snapshot mode ignores the `FIGMA_API_KEY` / `FIGMA_FILE_KEY` environment variables. Passing `--api-key`, `--oauth-token` or `--file-key` explicitly alongside `--input` is an error. Everything else — `--config`, `--split-by-collection`, `--split-by-mode`, `--omit-collection-names`, `--stdout` — behaves exactly as it does in REST mode.
|
|
503
|
+
|
|
504
|
+
#### Snapshot shape
|
|
505
|
+
|
|
506
|
+
Objects use the **raw Figma Plugin API shapes, verbatim** — serialize what the API returns rather than reshaping it, so nothing is lost in translation:
|
|
507
|
+
|
|
508
|
+
```js
|
|
509
|
+
const snapshot = {
|
|
510
|
+
variableCollections: await figma.variables.getLocalVariableCollectionsAsync(),
|
|
511
|
+
variables: await figma.variables.getLocalVariablesAsync(),
|
|
512
|
+
paintStyles: await figma.getLocalPaintStylesAsync(),
|
|
513
|
+
textStyles: await figma.getLocalTextStylesAsync(),
|
|
514
|
+
effectStyles: await figma.getLocalEffectStylesAsync(),
|
|
515
|
+
gridStyles: await figma.getLocalGridStylesAsync(),
|
|
516
|
+
};
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
Only `variables` and `variableCollections` are required; the style arrays are optional and read only when the matching `includedStyles.*` config flag is on. The full contract is in [schemas/tokens-snapshot.schema.json](schemas/tokens-snapshot.schema.json), with a ready-to-copy example in [examples/tokens-snapshot.json](examples/tokens-snapshot.json).
|
|
520
|
+
|
|
521
|
+
Things worth knowing when building a snapshot:
|
|
522
|
+
|
|
523
|
+
- `valuesByMode` is keyed by **`modeId`**, not mode name — names come from the collection's `modes` array.
|
|
524
|
+
- Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
|
|
525
|
+
- `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
|
|
526
|
+
- 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.
|
|
527
|
+
|
|
528
|
+
> [!NOTE]
|
|
529
|
+
> Plugin API objects are live proxies, so `JSON.stringify` may not enumerate their properties. Copy the fields listed in the schema onto plain objects before serializing.
|
|
530
|
+
|
|
423
531
|
### CLI Configuration File
|
|
424
532
|
|
|
425
|
-
You can use a JSON configuration file to specify the export options for the CLI.
|
|
533
|
+
You can use a JSON configuration file to specify the export options for the CLI. Run [`tokens-bruecke init`](#quick-setup) to generate one, or write it by hand:
|
|
426
534
|
|
|
427
535
|
```json
|
|
428
536
|
{
|
|
@@ -457,9 +565,81 @@ This repository and the npm package ship agent-friendly docs:
|
|
|
457
565
|
- [llms.txt](llms.txt) — entry point for LLM-based tools
|
|
458
566
|
- [skills/tokens-bruecke/SKILL.md](skills/tokens-bruecke/SKILL.md) — an [agent skill](https://code.visualstudio.com/docs/copilot/customization/agent-skills) covering CLI usage, auth, config and exit codes; copy the `skills/tokens-bruecke` folder into your project's skills directory to teach your agent the CLI
|
|
459
567
|
- [schemas/cli-options.schema.json](schemas/cli-options.schema.json) — machine-readable config schema
|
|
568
|
+
- [schemas/tokens-snapshot.schema.json](schemas/tokens-snapshot.schema.json) — machine-readable input schema for `--input`
|
|
460
569
|
|
|
461
570
|
For scripted/agent usage prefer `--stdout --quiet` (pure JSON on stdout, logs on stderr) and pass tokens via environment variables.
|
|
462
571
|
|
|
572
|
+
#### Agentic usage without the REST API
|
|
573
|
+
|
|
574
|
+
If your agent can run code inside Figma — a Figma agent, an MCP server with `evaluate_script`, or your own plugin — it already has Plugin API access to the open file. In that case it should **not** go through the REST API at all:
|
|
575
|
+
|
|
576
|
+
| | REST API (`--file-key`) | Snapshot (`--input`) |
|
|
577
|
+
| ---------------------------------------------- | ----------------------- | ----------------------------------- |
|
|
578
|
+
| Figma Enterprise plan | Required | Not required |
|
|
579
|
+
| Personal access / OAuth token | Required | Not required |
|
|
580
|
+
| File must be published / shared with the token | Yes | No — works on whatever file is open |
|
|
581
|
+
| Network calls | Several per export | None |
|
|
582
|
+
|
|
583
|
+
The agent's job is only to dump data; the CLI still owns every transform, so aliases, modes, scopes and DTCG formatting behave exactly as they do in REST mode.
|
|
584
|
+
|
|
585
|
+
**1. Extract the snapshot from inside Figma.** Plugin API objects are live proxies, so `JSON.stringify` on them may serialize as empty — copy the fields onto plain objects first:
|
|
586
|
+
|
|
587
|
+
```js
|
|
588
|
+
const snapshot = {
|
|
589
|
+
variableCollections: (
|
|
590
|
+
await figma.variables.getLocalVariableCollectionsAsync()
|
|
591
|
+
).map((c) => ({
|
|
592
|
+
id: c.id,
|
|
593
|
+
name: c.name,
|
|
594
|
+
defaultModeId: c.defaultModeId,
|
|
595
|
+
modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
|
|
596
|
+
variableIds: c.variableIds,
|
|
597
|
+
})),
|
|
598
|
+
variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({
|
|
599
|
+
id: v.id,
|
|
600
|
+
name: v.name,
|
|
601
|
+
variableCollectionId: v.variableCollectionId,
|
|
602
|
+
resolvedType: v.resolvedType,
|
|
603
|
+
description: v.description,
|
|
604
|
+
scopes: v.scopes,
|
|
605
|
+
codeSyntax: v.codeSyntax,
|
|
606
|
+
valuesByMode: v.valuesByMode,
|
|
607
|
+
})),
|
|
608
|
+
// Optional — only needed if the config enables the matching style type
|
|
609
|
+
paintStyles: (await figma.getLocalPaintStylesAsync()).map((s) => ({
|
|
610
|
+
id: s.id,
|
|
611
|
+
name: s.name,
|
|
612
|
+
description: s.description,
|
|
613
|
+
paints: s.paints,
|
|
614
|
+
boundVariables: s.boundVariables,
|
|
615
|
+
})),
|
|
616
|
+
};
|
|
617
|
+
|
|
618
|
+
const json = JSON.stringify(snapshot, null, 2);
|
|
619
|
+
```
|
|
620
|
+
|
|
621
|
+
Text, effect and grid styles follow the same pattern — see [schemas/tokens-snapshot.schema.json](schemas/tokens-snapshot.schema.json) for the fields each one needs.
|
|
622
|
+
|
|
623
|
+
**2. Pipe it through the CLI.**
|
|
624
|
+
|
|
625
|
+
```bash
|
|
626
|
+
# From a file the agent wrote
|
|
627
|
+
npx tokens-bruecke --input snapshot.json --output tokens.json
|
|
628
|
+
|
|
629
|
+
# Or straight from stdin, no temp file
|
|
630
|
+
my-figma-agent dump-tokens | npx tokens-bruecke --input - --stdout --quiet > tokens.json
|
|
631
|
+
|
|
632
|
+
# All the usual options still apply
|
|
633
|
+
npx tokens-bruecke --input snapshot.json --config config.json --split-by-mode --output ./tokens
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
Snapshot mode ignores `FIGMA_API_KEY` / `FIGMA_FILE_KEY`, so a token exported in the environment won't get in the way. Passing `--api-key`, `--oauth-token` or `--file-key` explicitly alongside `--input` is rejected as a conflict.
|
|
637
|
+
|
|
638
|
+
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.
|
|
639
|
+
|
|
640
|
+
> [!NOTE]
|
|
641
|
+
> Aliases pointing at variables outside the snapshot (typically library variables from another file) export as `"#missing#"`, the same as in REST mode. To resolve them, include those variables in the `variables` array.
|
|
642
|
+
|
|
463
643
|
---
|
|
464
644
|
|
|
465
645
|
## Push to server
|