Skip to content

figma-transformer: resolve component instances in ScenegraphNormalizer #298

Description

@chubes4

Problem

Component instances render as empty containers. In the FSE Pilot Build Theme, the nav bar, logo, all blog post cards, the search input, the footer — everything that uses a Figma component — produces correct CSS (dimensions, colors, flex layout) but no children in the HTML.

Root cause: INSTANCE nodes in the Kiwi scenegraph are thin shells pointing to a COMPONENT definition via `componentId`. The definition carries the actual children; the instance carries only layout + overrides. The normalizer doesn't resolve instances, so they emit as empty `

`.

What the Figma scenegraph looks like

INSTANCE node {
  componentId: "some-id",
  children: [],          // empty — children live in the component definition
  overrides: [...]       // text/style overrides per child path
}

COMPONENT node {
  id: "some-id",
  children: [...]        // the actual content
}

Proposed fix

In `ScenegraphNormalizer`, add a component resolution pass:

  1. First pass: collect all COMPONENT-type nodes into an id → node map
  2. Second pass: for each INSTANCE node, look up the component definition and copy its children subtree into the instance
  3. Apply instance overrides on top of the copied subtree (text content, fill colors, visibility)

Phase 1 (basic child copy, no overrides) unblocks the majority of content — nav bars, cards, footers appear with component default content. Phase 2 (override application) gets correct text and style variations per instance.

Evidence

FSE Pilot Build Theme homepage (index.html, 66 lines):

  • <header> — empty (nav component instance)
  • <div class="...featured-posts"> — empty (post card component instances)
  • <div class="...input"> — empty (search input component instance)

Only raw primitive TEXT nodes rendered. Everything component-based is empty.

Impact

This is the highest-leverage fix in figma-transformer. Every real Figma design file uses components for nav, cards, buttons, footers, forms. Without resolution, the HTML artifact is structurally correct but visually ~10% complete.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions