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 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` is required |
393
- | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token` is required |
394
- | `--file-key` | `-f` | Figma file key | Yes |
395
- | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
396
- | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
397
- | `--config` | `-c` | Path to configuration file | No |
398
- | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
399
- | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
400
- | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
401
- | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
402
- | `--help` | `-h` | Show usage help | No |
403
- | `--version` | | Show the CLI version | No |
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