Variables that cannot be named produce unresolvable spec tokens

[nathanacurtis]

Follow-up from #278, which decided a spec token references a variable by name and nothing else. Render looks that name up in the fetched variables data to find the actual variable. A token whose name is a placeholder therefore resolves to nothing and binds nothing.

The problem

When a spec is generated, each variable-bound value is looked up in the fetched variables data to find its name. When that lookup misses, the token is written with a placeholder instead of a real name:

• Unavailable variable — the bound variable was not found in the variables data
• [collection-name-unresolved]/… — the variable was found, but its collection was not
• [unresolved] — no name at all
• Variable (no loader) — no variables data was supplied to the run

Why the lookup misses

The variables data comes from Figma's local-variables endpoint, which returns only the variables defined in that file. A component bound to a variable subscribed from another library has an id that appears nowhere in the fetched data, so it cannot be named. The same applies to a collection that lives outside the fetched files.

So this is not a rare edge case — it is the normal outcome for any design system that splits variables across more than one file and does not fetch all of them.

What resolving this looks like

1. Establish how often it actually happens against real libraries — count placeholder tokens across a generated spec set.
2. Decide the fix for each cause. Fetching every contributing library is the obvious one; there may be others.
3. Decide what generate does when a name genuinely cannot be found. Silently writing a placeholder that will fail at render time is the current behavior and is the thing to replace — a warning, an explicit unresolved marker, or a hard failure.

Why it matters

A token that cannot be named cannot be bound when the spec is rendered back into Figma. The component still renders, using the value cached in the spec, so the result looks correct while being quietly disconnected from the design system.

Worth being precise about the exposure, because it varies by token profile and it is not new:

• Specs generated with the default TOKEN profile carry $token and $type only. They have never carried an id, so a placeholder name has always been unresolvable. This is live today.
• Specs generated with TOKEN_FIGMA_EXTENSIONS or CUSTOM also carry $extensions.com.figma.id. Render used to fall back to that id, which masked the problem for those specs when rendering into the file the spec came from. Render no longer reads it — per Design: spec tokens carry a token name — resolution is a lookup concern #278, the name is the only reference — so those specs now behave like the rest.

[nathanacurtis]

Closing — unfounded.

The only occurrences of the placeholder in the workspace are two deliberate dead-variable fixtures (testColorValues, testStyleVariablesVTokenStudio), which are supposed to fail. A dead variable producing a placeholder name, and render then warning and binding nothing, is correct behavior rather than a defect.

This was filed from reading the placeholder strings in the code and inferring consequences, without checking whether the placeholder occurs for any reason other than a variable genuinely being gone. No evidence it does.