tokens-bruecke 3.4.4 → 3.5.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
@@ -35,8 +35,10 @@ The plugin converts Figma variables into design-tokens JSON that are compatible
35
35
  - [Installation](#installation)
36
36
  - [Usage](#usage)
37
37
  - [Options](#options)
38
+ - [Snapshot input](#snapshot-input)
38
39
  - [CLI Configuration File](#cli-configuration-file)
39
40
  - [For AI agents](#for-ai-agents)
41
+ - [Agentic usage without the REST API](#agentic-usage-without-the-rest-api)
40
42
  - [Push to server](#push-to-server)
41
43
  - [JSONBin](#jsonbin)
42
44
  - [GitHub](#github)
@@ -351,8 +353,17 @@ Alias references are also rewritten so they point to the flat path (the collecti
351
353
 
352
354
  ## Use as cli tool
353
355
 
356
+ The CLI is published on npm: [tokens-bruecke](https://www.npmjs.com/package/tokens-bruecke)
357
+
358
+ The CLI can get its data two ways:
359
+
360
+ - **From the Figma REST API** — pass `--file-key` and a token. Requires a Figma Enterprise plan.
361
+ - **From a local snapshot** — pass `--input`. No token, no Enterprise plan; see [Snapshot input](#snapshot-input).
362
+
363
+ Both modes produce identical output and share every other flag.
364
+
354
365
  > [!WARNING]
355
- > ⚠️ You need a Figma Enterprise plan to use the Figma REST API for variables.
366
+ > ⚠️ You need a Figma Enterprise plan to use the Figma REST API for variables. Use `--input` if you don't have one.
356
367
 
357
368
  ### Installation
358
369
 
@@ -381,26 +392,30 @@ tokens-bruecke --api-key $FIGMA_TOKEN --file-key $FIGMA_FILE --config config.jso
381
392
 
382
393
  # Using an OAuth token
383
394
  tokens-bruecke --oauth-token $FIGMA_OAUTH_TOKEN --file-key $FIGMA_FILE --config config.json --output out/tokens.json
395
+
396
+ # From a local snapshot — no token required
397
+ tokens-bruecke --input snapshot.json --output out/tokens.json
384
398
  ```
385
399
 
386
400
  This will fetch figma variables and export them in `out/tokens.json`
387
401
 
388
402
  ### Options
389
403
 
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 |
404
+ | Option | Alias | Description | Required |
405
+ | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
406
+ | `--api-key` | `-a` | Figma personal access token (PAT) | One of `--api-key` or `--oauth-token`, unless `--input` |
407
+ | `--oauth-token` | `-t` | Figma OAuth token | One of `--api-key` or `--oauth-token`, unless `--input` |
408
+ | `--file-key` | `-f` | Figma file key | Yes, unless `--input` is used |
409
+ | `--input` | `-i` | Read a local tokens snapshot instead of calling the REST API (`-` reads stdin) | No |
410
+ | `--output` | `-o` | Path to output file, or output directory when `--split-by-collection` or `--split-by-mode` | Yes, unless `--stdout` is used |
411
+ | `--stdout` | | Print tokens JSON to stdout instead of writing a file (mutually exclusive with `--output` and split flags) | No |
412
+ | `--config` | `-c` | Path to configuration file | No |
413
+ | `--split-by-collection` | `-s` | Write each collection as a separate `.tokens.json` file in `--output` | No |
414
+ | `--split-by-mode` | `-m` | Write each mode as a separate `.tokens.json` file under its collection directory in `--output` | No |
415
+ | `--omit-collection-names` | | Drop top-level collection names and merge all variables into one flat namespace | No |
416
+ | `--quiet` | `-q` | Suppress progress logs (errors are still printed) | No |
417
+ | `--help` | `-h` | Show usage help | No |
418
+ | `--version` | | Show the CLI version | No |
404
419
 
405
420
  Progress logs are printed to **stderr**, so stdout stays clean for piping:
406
421
 
@@ -420,6 +435,49 @@ tokens-bruecke -f $FIGMA_FILE -o out/tokens.json
420
435
 
421
436
  Other export settings are available through a JSON configuration file (see [CLI Configuration File](#cli-configuration-file) below).
422
437
 
438
+ ### Snapshot input
439
+
440
+ `--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:
441
+
442
+ ```bash
443
+ # From a file
444
+ tokens-bruecke --input snapshot.json --output out/tokens.json
445
+
446
+ # From a pipe
447
+ my-figma-dumper | tokens-bruecke --input - --stdout --quiet > tokens.json
448
+ ```
449
+
450
+ 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.
451
+
452
+ 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.
453
+
454
+ #### Snapshot shape
455
+
456
+ Objects use the **raw Figma Plugin API shapes, verbatim** — serialize what the API returns rather than reshaping it, so nothing is lost in translation:
457
+
458
+ ```js
459
+ const snapshot = {
460
+ variableCollections: await figma.variables.getLocalVariableCollectionsAsync(),
461
+ variables: await figma.variables.getLocalVariablesAsync(),
462
+ paintStyles: await figma.getLocalPaintStylesAsync(),
463
+ textStyles: await figma.getLocalTextStylesAsync(),
464
+ effectStyles: await figma.getLocalEffectStylesAsync(),
465
+ gridStyles: await figma.getLocalGridStylesAsync(),
466
+ };
467
+ ```
468
+
469
+ 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).
470
+
471
+ Things worth knowing when building a snapshot:
472
+
473
+ - `valuesByMode` is keyed by **`modeId`**, not mode name — names come from the collection's `modes` array.
474
+ - Colors are 0..1 float channels (`{ r, g, b, a }`), as the Plugin API returns them.
475
+ - `collection.variableIds` preserves the ordering shown in Figma's Variables panel.
476
+ - 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.
477
+
478
+ > [!NOTE]
479
+ > 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.
480
+
423
481
  ### CLI Configuration File
424
482
 
425
483
  You can use a JSON configuration file to specify the export options for the CLI.
@@ -457,9 +515,81 @@ This repository and the npm package ship agent-friendly docs:
457
515
  - [llms.txt](llms.txt) — entry point for LLM-based tools
458
516
  - [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
517
  - [schemas/cli-options.schema.json](schemas/cli-options.schema.json) — machine-readable config schema
518
+ - [schemas/tokens-snapshot.schema.json](schemas/tokens-snapshot.schema.json) — machine-readable input schema for `--input`
460
519
 
461
520
  For scripted/agent usage prefer `--stdout --quiet` (pure JSON on stdout, logs on stderr) and pass tokens via environment variables.
462
521
 
522
+ #### Agentic usage without the REST API
523
+
524
+ 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:
525
+
526
+ | | REST API (`--file-key`) | Snapshot (`--input`) |
527
+ | ---------------------------------------------- | ----------------------- | ----------------------------------- |
528
+ | Figma Enterprise plan | Required | Not required |
529
+ | Personal access / OAuth token | Required | Not required |
530
+ | File must be published / shared with the token | Yes | No — works on whatever file is open |
531
+ | Network calls | Several per export | None |
532
+
533
+ 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.
534
+
535
+ **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:
536
+
537
+ ```js
538
+ const snapshot = {
539
+ variableCollections: (
540
+ await figma.variables.getLocalVariableCollectionsAsync()
541
+ ).map((c) => ({
542
+ id: c.id,
543
+ name: c.name,
544
+ defaultModeId: c.defaultModeId,
545
+ modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
546
+ variableIds: c.variableIds,
547
+ })),
548
+ variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({
549
+ id: v.id,
550
+ name: v.name,
551
+ variableCollectionId: v.variableCollectionId,
552
+ resolvedType: v.resolvedType,
553
+ description: v.description,
554
+ scopes: v.scopes,
555
+ codeSyntax: v.codeSyntax,
556
+ valuesByMode: v.valuesByMode,
557
+ })),
558
+ // Optional — only needed if the config enables the matching style type
559
+ paintStyles: (await figma.getLocalPaintStylesAsync()).map((s) => ({
560
+ id: s.id,
561
+ name: s.name,
562
+ description: s.description,
563
+ paints: s.paints,
564
+ boundVariables: s.boundVariables,
565
+ })),
566
+ };
567
+
568
+ const json = JSON.stringify(snapshot, null, 2);
569
+ ```
570
+
571
+ 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.
572
+
573
+ **2. Pipe it through the CLI.**
574
+
575
+ ```bash
576
+ # From a file the agent wrote
577
+ npx tokens-bruecke --input snapshot.json --output tokens.json
578
+
579
+ # Or straight from stdin, no temp file
580
+ my-figma-agent dump-tokens | npx tokens-bruecke --input - --stdout --quiet > tokens.json
581
+
582
+ # All the usual options still apply
583
+ npx tokens-bruecke --input snapshot.json --config config.json --split-by-mode --output ./tokens
584
+ ```
585
+
586
+ 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.
587
+
588
+ 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.
589
+
590
+ > [!NOTE]
591
+ > 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.
592
+
463
593
  ---
464
594
 
465
595
  ## Push to server