MVP: Validate the default-slot gate matrix across CLI and plugin

[nathanacurtis]

Problem

Default-slot nesting is implemented across every surface — the CLI reads the convention, the engine captures the nesting, both transforms emit it, the render direction puts it back, and the plugin panel now declares it (#665, #668). What has actually been run is narrower than that: one CLI path, against one library, on components whose siblings happen to be distinctly named.

The behaviour is also gated in a way that is easy to misread as broken. Three independent conditions decide whether nesting happens, one of them differs between a component and a composition, and a fourth output — the defaultSlot: true marker — is deliberately ungated and appears even when nesting does not. So "I turned it on and nothing changed" is an expected outcome in several cells of the matrix, and there is currently no way to tell that apart from a defect.

Two specific gaps that make this urgent rather than tidy:

• The two switches live in different places and neither mentions the other. Naming the default slot is necessary but not sufficient for a component: spec.defaultSlotContent must also be on. In the plugin those are two checkboxes in two different sections (Props and Examples). Nothing in either surface tells you the other exists.
• Nothing has compared the two surfaces. The parity claim — same node, same declared convention, same spec whether generated by the CLI or the plugin — is the whole point of the plugin change, and it has never been checked.

Potential solution(s)

• Walk the gate matrix below on one component and one composition, recording actual output per cell, so each "nothing changed" is either confirmed as designed or becomes a bug report.
• Compare CLI and plugin output for the same node under the same declared convention, and diff them.
• Where a cell's expected outcome is surprising on reflection, treat that as a finding about the design rather than only about the implementation — particularly the component/composition asymmetry.

Acceptance criteria

The gate matrix

Each row is a configuration; the last two columns are what the spec should contain. defaultSlot: true on the slot prop and the nesting itself are separate outputs with different gates — that separation is the thing most likely to read as a bug.

Convention declared	Pro	defaultSlotContent	Host kind	defaultSlot: true?	Nesting?
no	—	—	either	no	no
yes, empty list	—	—	either	no	no
yes	no	on	either	yes	no
yes	yes	off	component	yes	no
yes	yes	on	component	yes	yes
yes	yes	off	composition	yes	yes
yes	yes	on	composition	yes	yes

• Every row above produces the stated output, on the CLI
• The two bolded "yes marker, no nesting" rows are confirmed as designed, and a reader of the spec can tell why — or filed as a usability defect if they cannot
• The composition rows confirm the exemption: a composition nests regardless of defaultSlotContent, because composed content is the reason it exists

Structural preconditions

These decide whether a given slot flattens, independently of the gates above:

• A nested instance's default slot, filled → nests as that instance's children
• The host's own default slot, filled → unchanged, still a slotContentExamples entry pointed at from the binding. The host declares that slot, so content in it is the slot's authored default
• A nested instance's non-default slot, filled → unchanged, still an explicit reference
• An instance filling both kinds → both shapes in one spec, side by side
• A hidden nested instance with a filled default slot → nothing captured
• An instance whose default slot is bound to a prop rather than filled → the binding survives; no content is substituted for it
• A default slot reached only by passing through a non-default slot's content → nests inside that entry, not into the host
• A chain two instances deep where the inner one fills a non-default slot → the reference anchors on the inner instance, not as a $nested path on the outer one

CLI ↔ plugin parity

• The same component, with the same declared convention and the same two switches, produces the same spec through specs generate and through the plugin
• metadata.conventions.platforms.figma.slots is present in both, so the render direction can resolve the slot either way
• A diff of the two specs is empty, or every difference is explained and expected

Round trip

• A spec carrying a nested hierarchy renders back into Figma with the content in the right slot
• Regenerating from the rendered node reproduces the nesting rather than flattening it back out
• A multi-slot component's nested children land in the slot the convention names, not in a sibling slot

Case data

• Fixture: an action-list component and a card component for the component rows — both verified through the CLI and both carry a nested instance with a filled default slot. A composition for the composition rows; one of the canonical screens works, though its layout levels are frames rather than instances
• Workspace: eg for the CLI side and the plugin side; a test library for the structural rows that need deliberately odd frames
• Territory: testing, crossing cli / specs-from-figma / plugin-settings
• Size: m

Notes

Several structural rows need frames no design file currently contains — the hidden instance, the bound-rather-than-filled slot, the two-deep chain. #656 is the authoring work and already carries most of them; this issue is the verification that consumes them, so the two are worth sequencing together rather than merging.

What is already known, so nobody re-derives it: the engine behaviour is proven on the CLI path against a real library, where one screen's slot-content entries dropped from 20 to 3 and an action-list component's from 24 to 8. Every gate has unit coverage. What has never run is the plugin path, the render round trip, and every structural row above except the plain nested-instance case.

One known limitation that will show up while testing and is not this issue's to fix: sibling instances sharing a Figma name collapse to a single anatomy element, because anatomy and elements key by layer name. ADR-044 is the accepted answer and is unimplemented. Expect three identically-named cards to read as one, and do not file it again.

[nathanacurtis]

Gate matrix walked on the CLI, against a component. Every row I could run produces the stated output.

Method: four copies of the workspace config, varied one gate at a time, each run with --config so the workspace's own config was never touched. Component: Slot Non Default Nested, whose nested instance has both a default and a non-default slot filled — so one component exercises both structural shapes at once.

Convention	defaultSlotContent	defaultSlot: true?	Nesting?	Entries	Verdict
absent	on	no	no	3	as stated
declared, empty list	on	no	no	3	as stated
declared	off	yes	no	0	as stated
declared	on	yes	yes	1	as stated

The two separate outputs behave as designed: the marker follows the convention alone, and the nesting additionally needs the opt-in. The bolded row is the one this issue flagged as easy to misread, and it is confirmed — declaring the convention marks the slot prop and changes nothing else.

Worth noting what that row actually produces: zero entries, not "the old shape". With the convention declared and the opt-in off, no composed slot content is emitted at all, which is the ADR-050 gate rather than anything about default slots. So the observable difference between rows three and four is not "flat versus nested" but "nothing versus nested" — a reader comparing those two specs sees the marker appear in both and content appear only in the fourth.

Structural preconditions — all four confirmed

Precondition	Result
nested instance's default slot, filled	nests as that instance's children
nested instance's non-default slot, filled	explicit reference retained, bound on the instance
an instance filling both kinds	both shapes in one spec, side by side
host's own default slot, filled	unchanged

The third row is the fixture itself: root > levelZeroText > level1 > twoSlots > aChild in the layout, with aside bound to its own entry. That shape also round-trips through Figma identically now.

Two rows I could not run, and why

• Free tier. The activation cache is working-directory scoped, and this workspace carries a cached Pro activation, so a run with the dev-tier escape removed is still licensed. Testing it honestly needs a clean working directory, which is a separate setup rather than a config toggle.
• The composition rows. This workspace holds no composition — there is no compositions/ output — so the exemption (a composition nests regardless of the opt-in) is unverified here. The library that does have compositions now declares the convention, so it could carry those two rows.

Parity

Not done. CLI and plugin output for the same node under the same declared convention have still never been diffed. Everything above is the CLI path only.

Leaving this open for those three gaps.

[nathanacurtis]

Free-tier row now run, and it passes. Two of the three gaps I left are closed or reassigned.

Free tier — yes, unsetting the key is enough

It works, with one condition: the run also has to start from a working directory that carries no cached activation. From a clean temporary directory with both SPECS_LICENSE_KEY and the dev-tier escape unset, the run genuinely resolves as free — license: { status: none, level: FREE } in the run metadata, not a silently licensed Pro run.

Convention	Pro	defaultSlotContent	defaultSlot: true?	Nesting?
declared	no	on	yes	no

Confirmed as designed. The marker is ungated and appears; the nesting does not. The host spec came back with an api and a variants concern and no examples concern at all, which is the composed-content gate rather than anything default-slot specific.

So the full CLI matrix is now walked, with every row producing the stated output:

Convention	Pro	defaultSlotContent	Marker	Nesting	Verdict
absent	yes	on	no	no	as stated
declared, empty list	yes	on	no	no	as stated
declared	no	on	yes	no	as stated
declared	yes	off	yes	no	as stated
declared	yes	on	yes	yes	as stated

Parity — this belongs to a different issue than I thought, and neither is quite it

#659 is about emit parity: that React and Web Components agree with each other on a composition's story count, nav titles, prune behaviour and index group. That is a different claim from the one this issue makes.

What this issue asks for is producer parity: the same Figma node, under the same declared convention, generating the same spec whether the CLI or the plugin captured it. Nothing I can find tracks that specifically. It is the stated point of the plugin-side change, and it remains unchecked.

Worth deciding whether that belongs here as the last open criterion, or as its own issue — it needs a diff harness rather than a matrix walk, and the two surfaces now definitely diverge in one respect worth checking first: the CLI resolves conventions and sends them to the plugin in the bridge payload, so a plugin run driven through the bridge shares the CLI's resolution and would not catch a resolution difference. A plugin run driven from its own panel would.

Composition rows — still open, and fixture work

Still the one gap. This workspace holds no composition, so the exemption — that a composition nests regardless of the opt-in — is unverified. Addressed separately: the fixtures need authoring as components first and then detaching to frames, which is a Figma step.

[nathanacurtis]

Composition fixture is authored, rendered, and verified — one Figma step left for you

I built it as a component so it could be validated before becoming a frame.

TEST Composition Slots — node 1675:816, on the same page as the other slot fixtures.

Its structure is deliberately the same as Slot Non Default Nested, because that one shape exercises every structural precondition at once: a nested instance whose default slot is filled, and a second non-default slot filled on the same instance.

TEST Composition Slots
├── a text layer
└── Slot Level 1                 (instance)
    └── slot "Children"
        └── Slot Two Slots       (instance)
            ├── slot "children" → text        (consolidates into the tree)
            └── slot "aside"    → text        (stays an explicit reference)

Round trip as a component is clean — anatomy, layout, the aside binding, and the referenced entry all come back identical.

What I need from you

1. Detach it so it becomes a frame.
2. Mark it ready for dev, or it will not be picked up — a frame earns a manifest row by being marked, which is what keeps the section readable in a library of many frames (ADR-095).

Then the two composition rows can run. One fixture covers both, since the only difference between them is the defaultSlotContent setting, which I toggle from the config side:

Convention	Pro	defaultSlotContent	Expected marker	Expected nesting
declared	yes	off	yes	yes — the exemption
declared	yes	on	yes	yes

The first row is the one worth having: a composition should nest regardless of the opt-in, because composed content is the reason it exists. Nothing has ever confirmed that.

Keeping it as a component as well would be useful — the same structure as both a component and a composition is the cleanest way to show the asymmetry is deliberate. So detaching a duplicate rather than the original is probably the better move.

[nathanacurtis]

Composition rows run — the exemption holds, and the last cells turned up a defect

The fixture is a frame and marked, so it scans as a composition (FRAME, selected). Both rows:

Convention	Pro	defaultSlotContent	Nesting?	Slot-content entries
declared	yes	off	yes	0
declared	yes	on	yes	1

The exemption is confirmed. A composition nests regardless of the opt-in, which is what this issue asked to verify and what nothing had ever checked.

The off row also found a defect, filed as #685: the composition keeps the content that consolidates and silently loses every non-default slot fill, because the exemption applies to the decision to consolidate but not to the decision to record a reference. Same class as #677 — captured, registered, never referenced, no warning.

That is the matrix doing its job: the cell nobody had run is the cell with the bug in it.

Where this issue now stands

Every CLI row is walked:

Convention	Pro	defaultSlotContent	Host	Marker	Nesting	Verdict
absent	yes	on	component	no	no	as stated
declared, empty	yes	on	component	no	no	as stated
declared	no	on	component	yes	no	as stated
declared	yes	off	component	yes	no	as stated
declared	yes	on	component	yes	yes	as stated
declared	yes	off	composition	yes	yes	as stated, but see #685
declared	yes	on	composition	yes	yes	as stated

Structural preconditions: all four confirmed, on both a component and a composition of the same structure.

• every row produces the stated output, on the CLI
• the "yes marker, no nesting" rows are confirmed as designed
• the composition rows confirm the exemption
• CLI and plugin output compared for the same node — still the one gap

Leaving open for producer parity only. As noted, a plugin run driven through the bridge receives the CLI's resolved conventions, so only a run from the plugin's own panel can catch a resolution difference — which makes this a harness question rather than a matrix one.