CI: enforce Figma `codeSyntax` coverage on shipped tokens

[eddiman]

What

Add a CI check that fails when a token shipped as a CSS custom property is missing its Figma Code syntax value, or carries one that no longer matches what the export actually emits.

Why

We've just stamped $extensions["com.figma"].codeSyntax.Web onto 1185 tokens so Figma Dev Mode shows the real custom property (var(--eds-background-canvas)) instead of the variable name (background/canvas), giving developers something they can copy directly. That data pass is a point-in-time snapshot. Two things rot it, both silently:

1. New tokens ship blank. Every token added after the pass has no code syntax, and nothing flags it. This is not hypothetical — equinor/design-system#5284 added 36 new CSS variables in a single release (--eds-text-interactive-{info,success}-*, --eds-icon-interactive-{info,success}-*, --eds-icon-accent, plus --eds-dark-*-6/12). Had the pass run the day before, all 36 would be in Figma today with an empty field. At that rate the coverage decays within weeks, and the failure is invisible: the field just isn't there.

2. Stale values are worse than missing ones. The names are derived from the saved platform export EDS-CSS (id 39d37416-632b-4f04-b49b-cfaec63e3baa, naming.prefix: "eds"), which lives server-side in the Studio UI. Anyone changing the prefix or naming there leaves 1185 confidently-wrong strings pointing at properties that no longer exist. A developer copying one gets a value that silently does nothing. That is strictly worse than never having done this — a blank field makes people look it up; a wrong one doesn't.

Neither failure mode surfaces in review. review/changes doesn't even count extensions-only writes, so there's no signal from the normal token diff either.

What the check should do

Run against the generated packages/eds-tokens/src/tokens/ outputs on every tokens release PR:

1. Derive the expected variable name for every token in src/tokens/raw/. The transform is currently '--eds-' + name.replace(/\./g, '-').toLowerCase(), verified exact against the shipped bundle: 923 CSS vars, 923 matched, 0 orphans.
2. Re-prove the transform rather than trusting it — every shipped variable in src/tokens/css/variables.css must have exactly one owning token. An orphan means the export config changed and the derived names are no longer trustworthy; fail loudly at that point rather than emitting wrong values.
3. Fail if any token that maps to a shipped variable is missing codeSyntax.Web, or has one that differs from the derived name.
4. Skip the algorithm-input sets, which correctly export nothing: foundation/anchor, foundation/gaussian, input/palette, input/scale (85 tokens).
5. Report a hand-authored value that disagrees with the derived name as a distinct outcome, not a generic failure — that's a deliberate override and needs a human decision, not an automatic rewrite.

The logic already exists in verify-only form and can be lifted more or less as-is; it currently reads the two sides and asserts the mapping in both directions.

Notes

• The data pass itself is applied to Tokens Studio branch code-syntax (52f4edda-496f-457e-b0f1-28c2de24991a) and is awaiting human merge — this guard should ideally land alongside that merge rather than after it.
• Related: the token redefinition epic equinor/design-system#4740 and the pipeline rebuild equinor/design-system#5108.

[claude]

These existing issues may be related to this one:

• bug(eds-tokens): per-appearance Disabled color tokens are zombie variables in Figma #4824 — bug(eds-tokens): per-appearance Disabled color tokens are zombie variables in Figma (closed as completed): its verification steps note that "Figma has historically had wrong values" for codeSyntax.WEB which the generator corrects — concrete prior evidence of the stale-value failure mode described here.
• Update codeSyntax of the spacing variables in Figma #4223 — Update codeSyntax of the spacing variables in Figma (closed as completed): earlier codeSyntax pass on the spacing variables, which deliberately replaced a mode-placeholder syntax with a generic/abstraction variable — exactly the kind of hand-authored override this check needs to report as a distinct outcome rather than auto-rewrite.
• ADR: Token variable architecture — code / output layer #5140 — ADR: Token variable architecture — code / output layer (open): scopes the path → naming transform, CSS output shape and "CLI / local validation; CI sync" that the derived-name assertion in step 1–2 depends on.
• Require tests for new build and pipeline scripts #5210 — Require tests for new build and pipeline scripts (open): notes that the Tokens Studio release workflow currently has no CI on its PRs, and would make tests a requirement for the new check script proposed here.

(#4740 and #5108 are already linked in the description.)

This comment was generated by an LLM and may be inaccurate. Please verify that the linked issues are actually relevant.

[eddiman]

Correction to the shape in the issue body, found while applying the data pass.

The platform key is uppercase WEB, not Web:

"$extensions": { "com.figma": { "codeSyntax": { "WEB": "var(--eds-background-canvas)" } } }

A PascalCase Web key is silently not recognised — the Studio UI files it under a read-only "Preserved from import" block, its own editable field stays empty, and nothing reaches Figma. No error at any point: the API accepts the write and reads it back intact, so an API-only round-trip appears to confirm a value the product ignores. Confirmed by setting the field by hand in the UI and diffing the token, which briefly carried both keys.

So the CI check should assert on codeSyntax.WEB specifically, and additionally fail on a stray Web key — that's the signature of a write that looked successful but is inert.

Two related notes for whoever picks this up:

• token.attributes.syntaxes shows up in the Tokens Studio plugin's REST mapping and looks like the canonical field. It isn't writable — PATCH accepts and ignores it, there's no sub-resource, and it always reads back null. Red herring.
• Code syntax is documented as a Variable-based project feature, while EDS is Token-based. Storage now works, but whether the companion plugin pushes it to Figma for token-based projects is still unverified. Worth confirming before the guard is treated as protecting something end-to-end.