Apply a non-image prop binding on render, or settle that it cannot be

[nathanacurtis]

Problem

When render places a nested instance, a prop configuration that is a $binding — the instance's property staying wired to the host component's own prop — is not applied. The instance renders at its main component's default instead, so a pass-through is silently converted into a hardcoded value.

A $nested deep configuration, addressing an instance further down a chain, is likewise not applied.

Both now emit a warning naming the element and prop, so they are visible rather than silent, but neither is implemented.

Potential solution(s)

• Apply the bindings the platform supports: a nested layer's visibility, its text content, and its swapped component can each be wired to a host property by reference
• Establish whether a nested instance's variant property can be bound at all, and if not, decide what the spec should mean for one — refuse it, warn once per run, or record it as unrenderable
• Apply $nested by walking the instance chain the path names

Acceptance criteria

• A binding whose target is a nested layer's visibility, text content, or swapped component renders bound, not at the default
• A binding whose target is a nested instance's variant property either renders bound, or is reported as unsupported with a reason a reader can act on
• A $nested deep configuration is applied, or reported with the path it could not reach
• No binding is dropped without the element and prop being named

Case data

• Fixture: Slot Passthrough, Slot Non Default Nested
• Workspace: specs-testing
• Territory: figma-from-specs
• Size: m

Notes

Split from #673, which covered this together with the slot-fill half. That half is done and round-trip verified; this one is unstarted and gated on a platform question, so they no longer belong together.

What the platform offers, read from the Plugin API typings rather than inferred. A node property can be wired to a containing component's property through componentPropertyReferences, and the admissible keys are exactly three: visible, characters, and mainComponent. Those correspond to a boolean pass-through, a text pass-through, and an instance-swap pass-through, and they apply to a sublayer's node property.

A nested instance's own component property — its size variant, say — is not in that set. So the general case this issue describes has no setter in the API as typed, and the three cases that do are narrower than the spec's $binding is. That is the question to settle before implementing: which bindings a spec can actually carry through a render, and what the contract should say about the rest.

Worth confirming against the current Plugin API documentation rather than the typings alone before building anything.

---

Implementation details are tracked internally.

[nathanacurtis]

Correcting this issue's framing, because the premise I filed it on was wrong.

Specs do not forward an enum from a parent to a child. A parent can set an enum value on a nested instance through its prop configurations — a fixed value, in the default or in a variant — and render already applies that; it is the scalar path and it works. But nothing in the spec flows a parent's enum into a composed element inside the parent's slot. That kind of wiring only appears in roles emitted through the React and Web Components transforms, not in the Figma direction at all.

So the API finding I recorded, that componentPropertyReferences admits only visible, characters and mainComponent and therefore cannot bind a nested instance's variant property, is answering a question the spec never asks. It is not the gap.

What is actually unresolved

Two things, and neither is the enum case:

1. What a $binding in a nested instance's prop configurations means. The one shape I can see it taking is a slot forwarded to the host's own slot prop — the host passing its content through to a nested instance's slot. That is a different mechanism from an enum pass-through and needs its own answer.

2. Whether the fixture reproduces it at all. Slot Passthrough, named on the issue this was split from, declares props: {} and carries no $binding anywhere in its generated spec. With no props on the host there is nothing to forward, so whatever that fixture was authored to exercise is not reaching the spec. Worth settling whether the fixture is incomplete or the passthrough is simply not captured.

One API note that may matter for the slot case and is not yet resolved: the typed keys for componentPropertyReferences are the three above, but its documented errors mention slot properties specifically, which suggests slot handling exists beyond what the types express. That needs reading against the live documentation rather than the bundled typings.

Status

Not implemented, deliberately. The $nested half is also untouched. Both now warn rather than failing silently, which is where they should sit until the above is settled.

Parked for a conversation rather than a guess.

[nathanacurtis]

One more correction, on my own speculation above.

Where I wrote that a $binding might be "a slot forwarded to the host's own slot prop", that must not be read as a parent and a nested instance sharing a property name means the parent forwards to the child. It does not, and nothing should be built on that. A matching name is a coincidence of vocabulary, not a declaration of wiring — the same reason selection and promotion read declared shapes rather than names everywhere else in this contract.

If forwarding exists at all it has to be something the spec says explicitly, and the open question is what that statement is — not which names happen to line up.

Nothing implemented here relies on that inference. The slot fill that did land in #673 matches a configuration key to the slot that key names, which is the key's own identity in the spec, not two components agreeing on a word.

[nathanacurtis]

Measured what $binding actually is in practice, which settles most of this.

It occurs twice in three libraries, and always in one shape

I walked every spec in the three workspaces for a $binding nested inside propConfigurations:

Workspace	Occurrences
specs-testing	1
eg	1
de-library	0

Both are identical in shape — a host's image-source prop forwarded to a nested image instance, carrying an authoring-default example:

image:
  instanceOf: egdsImage
  propConfigurations:
    imageSource:
      $binding: "#/props/imageSource"
      examples: [{ $image: "#/components/egdsAvatar/images/egdsAvatar__image" }]

So this is not the enum case. Specs do not forward an enum, and nothing here does. It is a host property that a nested instance's property follows — declared explicitly by the binding, not inferred from the two happening to share a name.

It is a real loss, not noise

I checked whether the image reaches the canvas another way, since $image elsewhere is handled as a style fill. It does not: the element carries the image only in this prop configuration, and the host's imageSource is a genuine Figma TEXT property. So a rendered avatar shows the image component's own default and the spec's image never arrives.

That makes the warning correct and worth keeping. It now names the host prop that was meant to drive it:

[render] propConfig "image.imageSource": follows the host's `#/props/imageSource`
and cannot be wired on render — the instance keeps its main component's default
for "imageSource"

• no binding is dropped without the element and prop being named

What remains blocked, and on what

Figma exposes a nested instance's property on its host. The Plugin API's only route for wiring a property to a containing component's is componentPropertyReferences, and it addresses a node property — visible, characters, mainComponent — not an instance's component property. The forwarding this shape needs has no setter as the API is typed.

That is the one question left, and it is a platform question rather than a design one: can a nested instance's component property be bound to its host's property from a plugin? If yes, this is implementable and small. If no, the contract should say a $binding is not rebuildable on render and the warning is the permanent answer.

Worth checking against Figma's published API docs rather than the bundled typings, which may lag.

$nested is untouched and separate: it needs the instance chain walked, not a property wired.

Fixture note

The fixture named on the issue this was split from, Slot Passthrough, declares props: {} and carries no binding at all — so it does not exercise this. The two components that do are an image wrapper in specs-testing and an avatar in eg. Worth repointing the issue's case data at those.

[nathanacurtis]

Image props now render. The rest is scoped down to one open question.

What landed

Your rule — image props wire from the main component to a nested instance, but not across a slot boundary — is what made this actionable, and it turned out not to need the API I was stuck on.

Render paints the binding's example as a fill rather than wiring a property. That is not a new interpretation: static content shows the example (ADR-063), which is exactly the reading both emitters already take for this same shape. An image source was never something setProperties could carry, so the property question was the wrong one.

Confirmed on the real case:

$ SPECS_RENDER_WARNINGS=1 specs render ./testImageWrapperRt
  ⚠ [render] "testDsImage.imageSource": painted the bound prop's example image —
    the property itself cannot be wired on render
✓ Rendered

And the round trip holds — the binding, its example, and the images registry entry all come back identical.

Not across a slot boundary, as you specified. The three places that build slot content now mark themselves, so the distinction is made where it is known rather than inferred from the shape of what is being built. A binding inside composed content belongs to whoever composed it.

• a binding whose target is an image source renders with that image

One escape added to make this verifiable

Render warnings are withheld by default, and that is still right — they are dominated by known defects. But it meant a render that silently did nothing was indistinguishable from one that worked, so a render-side fix could not be confirmed without editing a constant and rebuilding. SPECS_RENDER_WARNINGS=1 now prints them.

What is left

A non-image $binding still cannot be rebuilt, and $nested deep configs are untouched. Both report themselves.

The open question is narrower than when this was filed, and it is only about the non-image case: Figma exposes a nested instance's property on its host, but the Plugin API's only route for wiring a property to a containing component's is componentPropertyReferences, which addresses a node property — visible, characters, mainComponent — not an instance's component property.

Given that image props were the real case and they are now handled, it is worth asking whether a non-image binding needs rebuilding at all, or whether the warning is the permanent answer for it.

[nathanacurtis]

The $nested half also landed, verified on the multi-hop fixture.

A deep configuration now resolves its own target and is handled exactly as a directly-placed instance would be — same prop application, same slot fill, same bound-image paint. Nothing about what a configuration means changes with depth.

The walk follows instances in each one's own anatomy and never crosses a slot, matching the boundary capture drew when it recorded the path. A path that resolves to nothing is reported with the chain it could not follow.

Round trip on the fixture is identical: path, reference, and the content two boundaries down. That closed #682's last criterion.

• a $nested deep configuration is applied, or reported with the path it could not reach

So what remains on this issue is only the non-image $binding, and the question of whether it needs rebuilding at all now that image props work.

[nathanacurtis]

Closing. Both halves that had a real case are done, and the half that remains has no case in any library.

What was implemented

Image props — painted from the binding's example, for an instance in the component's own anatomy, never across a slot boundary. Verified on the real case; the round trip preserves the binding, its example, and the registry entry.

$nested deep configurations — the path is resolved and the configuration applied to the instance it names, handled exactly as a directly-placed instance would be. Verified on the multi-hop fixture, which closed #682's last criterion.

Why the rest is closed rather than carried

I measured every spec in the three testing workspaces. $binding inside propConfigurations occurs twice, and both are image props:

Workspace	Occurrences	Shape
specs-testing	1	image source → nested image instance
eg	1	image source → nested image instance
de-library	0	—

So a non-image binding is not a gap being left open — it is a shape nothing produces. Designing for it now would mean guessing at both the spec's intent and the platform's capability, with no example to check either against.

If one appears it announces itself. Render reports it by name:

[render] propConfig "<element>.<prop>": follows the host's `#/props/<prop>` and cannot be
wired on render — the instance keeps its main component's default for "<prop>"

That is a deliberate permanent answer rather than a placeholder: the instance keeps its default, and the run says which element and prop it happened to.

The platform note, recorded for whoever meets that case

Figma exposes a nested instance's property on its host, but the Plugin API's only route for wiring a property to a containing component's is componentPropertyReferences, and the keys it admits are visible, characters and mainComponent — all node properties, not an instance's component property. Read from the bundled typings, which may lag the platform, so worth confirming against the live documentation before concluding it is impossible.

One correction worth keeping with this, since the issue was originally filed on it: specs do not forward an enum from a parent to a child. A parent sets a fixed value on a nested instance through propConfigurations, which render has always applied. Enum flow-through appears only in roles emitted by the React and Web Components transforms, not in the Figma direction. And a parent and a nested instance sharing a property name implies nothing about wiring.