Design: spec tokens carry a token name — resolution is a lookup concern

[nathanacurtis]

Raised while fixing #260 and #265, as "should a spec token carry the Figma key instead of the node id?"

Decided 2026-08-06: neither. A spec token carries a token name. Resolution is a lookup concern, not something the spec records.

The model

• The spec names a token. That name is the whole reference.
• The foundations / variables data — the fetched *.variables.json, outside the spec — maps that name onto whatever a consumer needs: the Figma key for importing, the variable id, the resolved value.
• Resolution happens against that data at render time. Nothing about which Figma file a token came from, or how a given runtime imports it, belongs in the spec.

This also settles the provenance question the original framing raised. The name traces back to the foundations data, which is where the id and key live; the spec does not need to carry a second copy of either.

Already built

Render resolves by name and nothing else. The bridge builds a manifest from the fetched variables data mapping each token name to the handles it needs — the library key, and the id the variable has in the file it was fetched from — and resolution tries the key first, then the id.

Two things are deliberately not done, and both matter:

• The spec's $extensions.com.figma.id is never read. Specs generated with TOKEN_FIGMA_EXTENSIONS or CUSTOM still carry it, but render ignores it, so every profile resolves identically.
• The target file is never searched by name. A file copied from the library holds duplicate variables under identical collection/name paths; matching those would bind the designer's copies instead of the library's own variables. The id fallback exists precisely so that rendering into the source file still works without name matching.

Open

• The reader must always emit a real token name. With name-only references this is a correctness precondition, not a quality goal. Every variable the reader cannot name is currently written as [collection-name-unresolved]/Unavailable variable; a token carrying that path has nothing to resolve with and is simply unbindable. Today the recorded id rescues those cases — under this model nothing does. Needs a pass over why the reader fails to name a variable, and either a fix or an explicit, warned degradation.
• Styles. Renderer.resolveStyleIds already resolves by name from the bridge manifest and imports by key, which makes it the accidental prototype of this model rather than an inconsistency. What remains is confirming REST exposes a usable key for every style type, and that the spec's inert id: 202:12 can be dropped without a consumer depending on it.

Out of scope

Token name collisions. Two collections sharing a name, or the same collection name across libraries, produce colliding paths. This is the responsibility of whoever authors or maintains the spec and the variable set, not something the pipeline will guard against.

Part of #204.

[nathanacurtis]

Resolution moved bridge-side

Removed from scope above. The variables manifest the bridge sends with renderComponent is now indexed on both axes rather than by token path alone:

• buildVariablesIndex (new, packages/cli/src/utilities/variablesIndex.ts) makes one pass over the fetched *.variables.json and emits { byId, byPath }. The previous builder iterated Object.values(), which discarded the variable id — the one identifier a spec reliably carries.
• VariableResolver accepts either the new indexed shape or the older path-only map, and resolves identifier-first: live getVariableByIdAsync → byId[id] key import → local path → byPath key import.

Two things that follow:

• Rendering into a file that has never seen the variables now works for variables. The id maps to a key, and the key imports.
• The silent mis-resolution described above is gone. An unresolvable id no longer falls through to a token-path match, so the variables sharing the path [collection-name-unresolved]/Unavailable variable no longer all bind to whichever one matched first. They now fail with a warning instead of binding something wrong.

No schema change, no spec-shape change, so no ADR was needed for this part. packages/specs-from-figma is untouched, and the generate direction is unaffected — the manifest rides only the renderComponent message.

Note on the manifest-shrink argument that was listed as a complication: it inverts. The bridge manifest now carries more, not less, and is load-bearing for id-based resolution. Putting the key in the spec would be what shrinks it — which is the remaining open question, not something this change settled.

Work is on feat/figma-from-specs in both specs and specs-from-figma, unmerged and interleaved with other changes on that branch.

[nathanacurtis]

Decision recorded: a spec token carries a token name, and resolution is a lookup against the foundations data.

The two consequences that are still real work moved out to sub-issues of #281:

• Variables that cannot be named produce unresolvable spec tokens #285 — variables the reader cannot name produce placeholder tokens, which become unresolvable once the id is gone
• Align styles to name-only references and drop the inert style id #286 — align styles to name-only references and drop the inert style id

Closing as decided.

[nathanacurtis]

Correcting the "Already built" section above, which described an earlier and wrong implementation.

Render now resolves a variable from the token name alone:

1. Look the name up in the manifest built from the fetched variables data → {key, id, published}
2. Import by key from the team library — authoritative for any file
3. Fall back to the id from that data, which resolves when rendering into the file the variables were fetched from, where there is no library import to make
4. Otherwise warn and bind nothing

Two routes were removed rather than kept for compatibility:

• Resolving from the spec's $extensions.com.figma.id. The parameter is gone from the resolver API and no render code reads that field. TOKEN_FIGMA_EXTENSIONS and CUSTOM specs now resolve exactly like default TOKEN specs.
• Matching variables in the target file by name. This was the first thing tried, and it is unsafe: a file copied from the library carries duplicates under identical collection/name paths, so a designer building in a copy and rendering components into it would silently bind the copies rather than the library's variables. The local-variable load is deleted, and a test asserts it is never called.

Consequence worth flagging for round-trip testing: a binding that previously worked only because the spec carried an id — a placeholder-named token in its origin file — now fails with a warning. That is #285 becoming visible, not a new defect.

On feat/figma-from-specs in both repos.