Round trip: preserve Figma names through lossy key formats (ADR-066)

[nathanacurtis]

Subissue of #204.

ADR-066 makes format.keys reversible so a spec produced with a lossy key format can be rendered back into Figma. Today every value other than SAFE is a one-way projection: Icon leading, Icon-leading, and Icon_leading all become icon-leading under KEBAB, and Cut & paste becomes cutPaste with nothing recording that a & was ever there. Since Figma layer and property names are the identity used to match existing nodes, render has no reliable way back.

The schema side gives the engine three things to consume:

• format.figmaKeys (NONE | SENTENCE | TITLE, default NONE) — the convention the Figma file uses, and the target a formatted key reverses into. NONE declares no convention: the grammar is not evaluated, no com.figma.name is emitted for format divergence, and reversal is undefined. Everything below is opt-in.
• SafeKeySentence / SafeKeyTitle — the grammar for names that survive every format.keys value: ASCII letters and digits, single-space separators, each word all letters or all digits, never digit-initial, casing matching figmaKeys
• $extensions['com.figma'].name on anatomy elements and props — the Figma name, emitted only when the key cannot reconstruct it

Scope

Emit side (specs-from-figma)

• Evaluate each anatomy element name and prop name against the safe key grammar for the declared format.figmaKeys, and emit com.figma.name only when it diverges
• Read format.figmaKeys through config resolution rather than assuming sentence case
• Keep well-formed catalogs extension-free — a name inside the grammar must emit nothing

Render side (figma-from-specs)

• Reconstruct Figma names by re-formatting the spec key into format.figmaKeys, preferring com.figma.name whenever it is present
• Resolve reference sites (elements, propConfigurations) through the definition — references stay in formatted key space and are not duplicated

Rename

• $extensions['com.figma'].originalName is renamed to .name. figma-from-specs/src/Elements/Elements.ts:131 reads it through an inline structural type, not the published type, so the rename will not fail compilation — it will silently read undefined and fall back to 'Icon'/'Text' for collapsed roots. Update that call site explicitly.
• specs-from-figma/src/Component/Anatomy/AnatomyElement.ts writes the field and will fail to compile, which is the caught case.

Round-trip check

A component whose Figma names fall outside the safe grammar — inner capitals, symbols, hyphens, digit-leading words — should survive Figma → spec → Figma with layer and property names intact, under a lossy format.keys value.

Depends on

Schema side ships in @directededges/specs-schema 0.30.0 (PR #296). Emit side is implemented on specs-from-figma branch feat/lossless-keys; plugin settings on specs-plugin-2 branch feat/lossless-keys.

Test fixtures

The parity-test workspace in specs-testing exercises every branch of the rule. Generated with format.keys: CAMEL, format.figmaKeys: SENTENCE — 948 names across 69 components, 75 divergent in 52 of them. Run specs analyze keys for the current inventory at workspaces/<workspace>/specs/_analysis/keys.yaml.

One fixture per cause

Component	Surface	Figma name	Emitted key	Exercises
avatar	prop	A11y label	a11yLabel	mixed letter-digit — the boundary in a11y is unrecoverable. Also the highest-volume case: 42 components
alert	prop	Full Bleed	fullBleed	casing on a prop — Title-cased in a Sentence-case file
toolbar	anatomy	ACME Toolbar / Action	acmeToolbarAction	symbol — / deleted along with its word boundary
paymentCardInput	anatomy	ACME Asset / Mark, ACME Icon glyph	acmeAssetMarkAcmeIconGlyph	symbol, multiple — / and , in one name
paymentCardInput	anatomy	0000 0000 0000 0000	0000000000000000	digit-initial — a name that is entirely digits
dialog.iosPrimaryAction	anatomy	Label␣␣␣	label	separator — trailing whitespace, invisible in the Figma UI
textArea	anatomy	x-figmacollapse	xFigmacollapse	already-a-key — kebab name, CAMEL destination, so it reformats and records rather than being retained

Collapsed roots — the ADR-058 path

These emit com.figma.name on the root key regardless of figmaKeys, including under the NONE default, because wrapper-collapse provenance is an independent trigger. This is the render-side hazard: figma-from-specs/src/Elements/Elements.ts:131 reads this through an inline structural type, so the originalName → name rename fails silently rather than at compile time.

Component	Figma name	Collapsed leaf type
icon	Icon glyph	glyph root — the icon-glyph-as-root case
text	Text	text root
body	Text	text root
heading	Text	text root

Shape coverage

• dialog — 4 divergent names, anatomy only (no props key in the report)
• badge — props only (no anatomy key)
• menu, pill, rating — 3 divergent each, spanning both surfaces in one component
• button and most others — zero divergence, and must stay extension-free

Config sweep

Regenerate the same catalog at each figmaKeys value and diff:

Value	Expected
NONE	4 preserved names — the collapsed roots only. No format-divergence extensions anywhere
SENTENCE	149 preserved names. Keys identical to the NONE run — only extensions are added, never a changed key
TITLE	~500 preserved names. The library is sentence case, so declaring the wrong convention floods the output — this is the "declare the right convention or drown in noise" case

Round-trip assertions

For each fixture above, Figma → spec → Figma must return the original layer or property name, not the reversal of the key:

• A11y label must come back as A11y label, never A 11 y label
• ACME Toolbar / Action must come back with its / intact
• Label␣␣␣ must come back with trailing spaces preserved — a renderer that trims silently renames the layer
• x-figmacollapse must come back as x-figmacollapse, not X figmacollapse
• icon's collapsed root must recreate a leaf named Icon glyph, not the 'Icon' fallback

[nathanacurtis]

Render-side reversal is implemented on specs-from-figma branch feat/figma-from-specs (31fefef).

KeyReversal inverts the emit-side grammar: prefer the recorded $extensions['com.figma'].name, otherwise split the key per format.keys and re-case per format.figmaKeys. Applied at every naming surface that reaches Figma:

• anatomy layer names
• component properties
• variant properties, through the variant frame name combineAsVariants parses
• slot properties
• boolean visibility properties folded into a paired content prop
• code-only properties

Internal maps stay keyed by the spec key, so element bindings and propConfigurations references are unchanged — references stay in formatted key space as the scope required.

Two findings beyond the described scope

Code-only properties need the rename applied after their layers are bound. Minting one under its final name succeeds, but setting componentPropertyReferences against it then fails with "Could not create a new component property reference". Verified on a live file that editComponentProperty preserves the numeric id across a rename (a11yLabel#58085:213479 → A11y label#58085:213479), so the reference stays valid.

Subcomponent renders were losing the naming config entirely. A subcomponent spec is a nested fragment of its parent's document and carries no metadata, so the recursion read no format.keys/figmaKeys and rendered every subcomponent layer and property under raw keys. It now inherits the parent's metadata.

The rename

Elements.ts:131 read originalName through an inline structural type, exactly as this issue predicted — no compile error, silently falling back to Icon/Text for collapsed roots. Fixed to read through the schema's own AnatomyElement type so a future rename breaks the build, with regression coverage that fails against the old reader.

Verification

A rendered component's own componentPropertyDefinitions confirmed every name lands correctly, including a code-only property and a slot:

Children#…, Label#…, Start visual visible#…, A11y label#…,
Children anyOf#…, Appearance, Emphasized, Label Visible, Size

Reading that component back produces the expected spec — the divergent code-only prop carries name: A11y label, and label carries no extension at all, since Label is inside the safe grammar. Reversal stays opt-in: under the NONE default nothing is declared and keys are used as names.

specs-testing gains scripts/validate-key-names.mjs, which classifies every name in a round trip as preserved / drifted / gained / lost.

Correction to this issue's description

The counts reconcile rather than being stale — analyze keys reports 71 divergent names in 49 components, and the description's 75 in 52 includes the four collapsed roots the analyzer excludes because root is synthetic. One component named in the description as having zero divergence does carry a divergent accessibility-label prop, which contradicts the note that the same prop spans 42 components; 26 components are genuinely extension-free if a control is needed.

Follow-up

anyOf values are component names, a naming surface with no Figma provenance and no reversal path — out of scope here, filed as #304 under #281.