Declare which slot is a component's children, rather than inferring it from the prop name

[nathanacurtis]

Problem

A component's primary slot is treated as "children" only when Figma happens to name the prop children. Any other name — items, content — is treated as a secondary slot, which is an accident of authoring rather than a statement of intent.

Consequences on both surfaces:

• React consumers pass a fragment to a named prop instead of nesting children:

  <AvatarGroup items={<><Avatar/><Avatar/></>} /> // today
  <AvatarGroup><Avatar/><Avatar/></AvatarGroup> // intended

• Web Components emit a NAMED slot, so projected content must sit inside a holder carrying slot="items". The holder is then the only assigned node, and ::slotted() cannot style a slotted node's descendants — so the component cannot style its own projected children at all.

That last point already forced a workaround: a component whose slot children overlap (negative item spacing) cannot express it in its stylesheet, so the margin is inlined onto generated example content and is absent for real consumers.

Solution

The workspace declares which slot prop is a component's children. One declaration, two platform behaviours:

• Web Components emit an unnamed <slot>; consumers write plain children, and every child is an assigned node reachable by ::slotted()
• React emits the prop as children; consumers nest

Likely per-component rather than one workspace-wide name, since components name their primary slot differently.

Acceptance criteria

• A slot declared as children projects through the default slot in web components
• The same slot is exposed as children in React
• Undeclared slots keep today's named behaviour
• A component with declared children can style its projected children from its own stylesheet
• Overlapping slot content works for a real consumer, not only generated examples

Workspace

Surfaced during component-by-component polish of React and web component output, reviewing both builds side by side in one Storybook.

Impacted code

• conventions config and its schema
• slot emission in both transform packages
• slot content composition in both packages
• the css transform's overlap rule, which can drop its inline workaround once children are reachable

Notes

Inferring from the prop name is the same class of fragility as keying off how many slots a component has: both make consumer markup depend on something unrelated to intent.

---

Implementation details are tracked internally.

[nathanacurtis]

Found while working around this: generated web component scaffolds set :host { display: contents } so the inner root participates in the parent's layout directly.

A display: contents element generates no box, so it cannot take a margin. That means no approach that styles the host works — not an inline margin on the projected child, not ::slotted(), and not the default slot this issue proposes. Any spacing applied to a generated component from outside is inert unless the host is first given a box.

This qualifies the acceptance criterion "a component with declared children can style its projected children from its own stylesheet": true only once the host generates a box. Whether that means changing the :host default, or emitting a box-generating display alongside any outside-in spacing, is part of this issue rather than separate from it.

Current workaround in the transforms: overlapped example content is emitted with display: inline-flex alongside the negative margin, inline on each composed child after the first. React is unaffected — its root is a real element, so the > * + * rule in the generated stylesheet reaches it.

[nathanacurtis]

Attempted the inline workaround and reverted it — recording why, because it rules out the whole approach.

Giving an overlapped child a box (display: inline-flex) so its margin applies also makes the HOST the flex item instead of the inner root. Any child sized Fill then stops growing, because flex lives on the inner root and does not transfer to the host. In a bottom bar whose items all fill, boxing the second and third items left the first (still display: contents) absorbing the row.

Boxing all of them is no better: they all lose Fill together.

So outside-in spacing on generated web components is not merely awkward, it is incompatible with :host { display: contents } plus Fill sizing. Whatever this issue lands on has to reconcile those two, not just decide slot naming. Overlap is currently unsupported in the web components build; React is unaffected.