How it works · question 2

How are nested components addressed?

Contracts stay per-component; a parent embeds its children by reference, never by copying their definition. The chain below — Dialog → Button-Brand Primary → Icon, from a real enterprise kit — is replayed through the actual import engine at site-build time, from the committed captures.

Composition is by reference

In a contract, a nested component is a component ref — the child’s contract id plus applied props, mapped through the child’s own bindings. The child’s anatomy, tokens, and API live in the child’s contract only; cycles and unknown references fail the build by name. That one rule is what makes the rest of this page mechanical.

When the child isn’t known yet: honest stubs

Import the CBDS Dialog on its own — before any of its children have been imported — and the engine refuses to guess. Every unknown child becomes a stub contract carrying the observed applied props and the observed geometry, and each stub says what it is in its own description. The Dialog-alone replay produced 6 stubs:

ds.button-brand-primary
ds.button-brand-secondary
ds.button-danger-primary
ds.button-neutral-tertiary
ds.icon
ds.slot-dialog

{
  "id": "ds.button-brand-primary",
  "name": "ButtonBrandPrimary",
  "version": "0.1.0",
  "props": [
    {
      "name": "text",
      "type": {
        "enum": [
          "action1"
        ]
      },
      "default": "action1",
      "bindings": {
        "figma": {
          "kind": "VARIANT",
          "property": "✏️text",
          "values": {
            "action1": "Action 1"
          }
        },
        "code": {
          "prop": "text"
        }
      }
    }
  ],
  "anatomy": {
    "root": {
      "tokens": {
        "width": "{imported.stub-button-brand-primary.root.width}",
        "height": "{imported.stub-button-brand-primary.root.height}",
        "border-radius": "{imported.stub-button-brand-primary.root.border-radius}",
        "background-color": "{bg.brand.default}"
      },
      "parts": {}
    }
  }
}
…

The stub’s own description states the deal plainly: “STUB contract auto-proposed for the nested "Button-Brand Primary" instances of Dialog — the child set was not imported. Props are the observed applied values ONLY; anatomy and styling are NOT captured (dump v1 stops at instance boundaries); the root renders th…”

Children first: session linking

Now the same fixtures in a working session, children first — Icon (from the committed whole-kit capture), then Button-Brand Primary, then Dialog. Each import registers its contract in the session; later imports resolve drawn instances against it. Real engine, real captures, at build time:

Even the “leaf” is honest about its own edge: the Icon set itself draws a Placeholder instance, so the Icon import carries one stub of its own.

Per-ref resolution of the Dialog import — its action button now links to the session’s real contract; only the never-imported children stay stubs:

{
  "buttonBrandPrimary": {
    "component": {
      "id": "ds.button-brand-primary",
      "props": {
        "text": "Action 1",
        "iconRight": false,
        "iconLeft": false,
        "size": {
          "prop": "size",
          "map": {
            "large": "large",
            "medium": "medium",
            "smallVertical": "small",
            "small": "small"
          }
        }
      }
    }
  }
}

Linked by key, not by luck

Names collide in real kits (the live capture holds 1,514 duplicate-named components). So resolution prefers the design tool’s stable component key: the drawn instance carries the key of the set it points at, and the proposed child contract carries the same key in its anchors. From the committed v1.6 whole-kit capture, at build time:

drawn instance of "Icon" inside the "Accordion" set:
  instanceSetKey  = c1c68aeb7b95222cf0755a02f63751df49e3af30
proposed ds.icon contract:
  anchors.figma.componentSetKey = c1c68aeb7b95222cf0755a02f63751df49e3af30
// equal — the link is keyed identity, and a CONTRADICTING key refuses to link

The upgrade: stub today, link tomorrow

Compare the two replays above: imported alone, Dialog stubbed ds.button-brand-primary; re-imported after the button entered the session, the same ref resolved to the real contract. Nothing is silently rewritten — the upgrade is a re-import through the same door. The standing 10-set receipt is the live gauntlet’s mega-session: ten sets imported in deliberately wrong order (composites before some of their children), then every composite re-imported once the whole scope exists — zero refs left stubbed despite their set being in scope:

Loaded from the committed receipt extract/figma/gauntlet/live/mega-session.json (npm run extract:figma:gauntlet:live). The Dialog dedup and linking behavior is separately pinned by npm run extract:figma:dialog:check, and the linked child’s minted-token scope by npm run extract:figma:cross:check — the owner’s exact two-import session, replayed.