Figma From Code Build Screens

Skill: Build Screens (Phase 4)

Builds full-page screen frames in Figma by composing built component instances into screenBodySize layouts (default 1440x900). Each screen assembles navigation, list panels, and detail/form panels using instances of components already created in Phase 3, then validates them visually against an app screenshot — iterating up to 3 fix passes to converge on visual fidelity.

All Figma MCP tools (use_figma, get_screenshot, etc.) are available. This skill runs its entire workflow — analyze, build, screenshot, compare, fix — inline when dispatched by the orchestrator.

When to Use

• When figma-from-code reaches Phase 4
• Standalone to rebuild screen layouts after component changes
• To add new screens after adding pages to the app

Required Inputs

Optional Inputs

Config placeholders like {pagesRoot} resolve from state.json → config (fields: devServerUrl, devServerStart, sourceDir, componentsRoot, pagesRoot, cssPath, tailwindConfigPath, iconLibrary, skillRoot).

Pre-Existing Screens Rule

Before doing any work that resolves to a node ID in preExistingScreens, stop. That node existed in Figma before this run; modifying it (rebuild, resize, delete + recreate, restructure) requires explicit user authorization.

Concretely:

• If screenName itself maps to a node in preExistingScreens and the caller's intent is to rebuild that node: write a result file with "status": "needs_authorization" and "preExistingTouched": ["<name>"], then return. Do not call use_figma to delete, replace, resize, or restyle the existing node. Building a fresh screen with the same name into the same screensFrameId is also a modification (creates a duplicate the orchestrator must reconcile) — don't do it without authorization.
• Instancing a component that is itself in preExistingComponents is fine — that's reuse, not modification.
• The fix-loop in Step 5 must never edit a node in preExistingScreens. If the comparison says you need to, escalate to the orchestrator instead.

This rule overrides Steps 2–5 of the workflow when in conflict.

Execution Mode

The orchestrator dispatches one subagent per screen. Each subagent runs the entire workflow (Steps 1–7) independently — analyze, build via use_figma, screenshot via get_screenshot, compare, fix loop, and return results.

The subagent writes its result to .temp/figma-from-code/build-results/screens/{screenName}.json. The orchestrator collects results after all subagents complete using collect-screen-results.js.

Screens can run in parallel — they only instantiate (not modify) already-built Phase 3 components.

Agent Prompt Template

The orchestrator dispatches one agent per screen. Send all agents in a single message so they run in parallel.

Build a Figma screen frame by composing built component instances, then validate visually.

Follow this skill's workflow (all 7 steps):
0. Verify all referenced components exist in builtComponents
1. FIRST study the app screenshot to understand what the default view shows,
   THEN analyze the page source — only include components visible in the screenshot.
   Exclude components behind conditional branches (ternaries, state guards, URL params)
   and portal-rendered overlays (Dialog, Sheet, etc.) that aren't visible by default.
2. Build the screen in Figma via use_figma (`screenBodySize` frame, default 1440x900)
3. Screenshot the result via get_screenshot
4. Structural check (content must match), then sizing check, then pixel diff
5. If mismatch, diagnose and fix (up to 3 iterations)
6. Write figma-screen.json tracking file
7. Write results to .temp/figma-from-code/build-results/screens/{screenName}.json

Inputs:
- Screen name: {screenName}
- Route: {route}
- Page source file: {pageSourceFile}
- Figma file key: {fileKey}
- Screens frame node ID: {screensFrameId}
- App screenshot: .temp/figma-from-code/screenshots/screens/{screenName}/app.png
- Text content: .temp/figma-from-code/screenshots/screens/{screenName}/text.json
- Screenshot dir: .temp/figma-from-code/screenshots/screens/{screenName}/
- Built components (for instance reuse): .temp/figma-from-code/builtComponents.json
- Pre-existing screens (DO NOT MODIFY): {JSON.stringify(preExistingScreens)}

Read plugins/figma-from-code/skills/figma-from-code/8-build-screens/SKILL.md for the full workflow,
fixSizing() function, variant resolution, and common pitfalls.

Workflow

Step 0    Prereqs       Verify all referenced components exist in builtComponents
Step 1    Analyze       Study appScreenshot first, then read page source; filter out non-default conditional branches
Step 2    Build         Create the screen frame in Figma via use_figma
Step 3    Screenshot    Capture the Figma result via get_screenshot
Step 4    Compare       Structural check + sizing sanity check + pixel diff against the app screenshot
Step 5    Fix Loop      If mismatch, diagnose and fix (up to 3 iterations)
Step 6    Track         Write figma-screen.json into the page folder
Step 7    Return        Report result with node ID, match score, and any remaining issues

Step 0: Verify all components exist (prerequisite gate)

Before building any screen, verify that every component referenced by the screen exists in builtComponents from state.json.

Identify the screen's key components from component-map.json → tree (the top-level components on that route and all their descendants). Check each one against builtComponents. Also check every icon imported by the page source (e.g., Icon/Check).

If any component or icon is missing from builtComponents:

STOP — do not proceed to Step 1. Return immediately with a rejection result:

{
  "screenName": "CasesPage",
  "status": "rejected",
  "reason": "missing_components",
  "missingComponents": ["CaseDetails", "MenuList"],
  "missingIcons": ["Icon/Trash"],
  "availableComponents": ["AppHeader", "Sidebar", "Button"]
}

Write this to .temp/figma-from-code/build-results/screens/{screenName}.json so the orchestrator can see what's missing.

Standalone (no orchestrator) — if the caller is the user directly, surface the rejection in the conversation and ask how to proceed. Don't fall back to inlining the missing components, building stubs, or downgrading the build into "best effort" — those produce a different artifact than the skill is supposed to produce. The right options are: (a) build the missing components first via plugins/figma-from-code/skills/figma-from-code/7-build-component/SKILL.md, (b) abandon the screen, or (c) get explicit user authorization to deviate.

Only proceed to Step 1 if every required component and icon is confirmed present.

Step 1: Analyze the Screen

Before writing any use_figma code, analyze all inputs to plan the screen structure.

Pre-flight: dev server is required for Step 1f (live inspection). Step 1f — inspecting the rendered page in a browser via inspect-styles.js — is the authoritative source for colors, spacing, and layout on the page chrome (the elements the page itself renders, outside of component children). Do not silently skip it. If you don't already have a dev server URL (from the orchestrator state ledger, project memory, or the caller's arguments), pause and ask the user for one before proceeding past Step 1. Only skip Step 1f if the user explicitly says no dev server is available.

1-pre. Screenshot-first composition (MANDATORY)

Before reading source code, look at appScreenshot (app.png). This screenshot shows the ACTUAL default view of the page as rendered in the browser with no user interaction. It is the ground truth for what the screen should look like.

Study the screenshot and identify:

• Which regions are visible (sidebar, main content area, detail panels, headers, footers)
• Whether the main content area shows populated data or an empty/placeholder state (e.g., "No case selected", "Select an item")
• Which component instances are actually rendered vs hidden by conditional logic
• Whether any overlays, dialogs, or menus are open (they should not be in the default state)

The source code analysis in Steps 1a–1b must MATCH what the screenshot shows, not the full component tree from the JSX. If the source code contains components behind conditional branches that are not visible in the screenshot, those components must be excluded from composition.

1a. Identify the page composition

Read the page source file and determine:

• Layout direction: Is the page root a vertical stack (flex-col), horizontal row (flex, flex-row), or a grid (grid)?
• Sizing: Screens are always fixed at screenBodySize (default 1440x900; read from state.json → screenBodySize). The outermost screen frame is primaryAxisSizingMode='FIXED' and counterAxisSizingMode='FIXED'. Capture this explicitly — Step 4a verifies it.
• Container children: What is the top-level region structure? Typical pages have: top nav (full width), sidebar (fixed width), main content (fill), or a hero + sections stack. Identify each region and which built component instance lives there.
• Spacing: gap-* classes on the page root map to itemSpacing. p-*, px-*, py-* map to padding.
• Background: bg-* class on the page root. Resolve through CSS variables if needed (see Step 1g of plugins/figma-from-code/skills/figma-from-code/7-build-component/step-1-analyze.md for the full chain).

1b. Identify component instances (default state only)

Walk the page source JSX and list component references, but only include components visible in the default state (as shown in appScreenshot from Step 1-pre).

For each included component:

• Map it to builtComponents[name] — that's the node ID to instantiate
• Note the variant props passed in code (e.g., <Button variant="primary" size="lg">) — these resolve to a specific variant inside the component set
• Note any sizing classes applied at the call site (className="w-full", className="flex-1") — these translate to layoutSizingHorizontal='FILL' etc. on the instance

// Source has: <Sidebar className="w-64" />
// builtComponents has: { "Sidebar": "230:5" }
// → Instantiate Sidebar at fixed width 256 inside the page frame

Conditional rendering analysis

When walking the JSX, identify and handle conditional patterns:

1. Ternary expressions (condition ? <A /> : <B />): Determine which branch is visible when the page first loads with no user interaction and no URL params beyond the base route. Cross-reference with appScreenshot — only include the branch that matches.

   // Example: {id ? <CaseDetails /> : <EmptyState />}
   // If appScreenshot shows "No case selected" → include EmptyState, EXCLUDE CaseDetails

2. URL-param-gated components: For components guarded by useParams() values (e.g., id ? <Detail /> : <Fallback />), use the param-absent branch as default since the screen captures the base route.

3. State-hook-gated components: Components behind useState(false) or useState(null) guards are hidden by default — exclude them.

   // Example: const [isOpen, setIsOpen] = useState(false);
   // {isOpen && <Modal />}  → EXCLUDE Modal from default screen

4. Logical AND guards ({flag && <C />}): Exclude unless the guard's initial value is truthy.

DO NOT compose components from non-default conditional branches. Those belong in separate screen variants if the pipeline supports them.

Portal-rendered overlay exclusion

Portal-rendered overlays — Dialog, Sheet, ConfirmationDialog, DropdownMenu, Popover, Drawer, AlertDialog, Tooltip, etc. — are NEVER visible in the default resting state. Exclude them from screen composition unless the appScreenshot explicitly shows them open.

These components are already handled by the component-level State axis in Phase 3 (see 7-build-component/step-1-analyze.md → "Conditional rendering of overlays"). Do not duplicate them in the screen frame.

1c. Identify icon usage on the page chrome

If the page renders any Lucide icons directly (not via a child component), map each to its builtComponents entry (Icon/{Name}) and size from the className. See Step 1c of plugins/figma-from-code/skills/figma-from-code/7-build-component/step-1-analyze.md for the size mapping table.

1d. Plan text content

Use textContent (from text.json) for any text the page itself renders (page titles, section headings, empty states). Never use generic placeholders. Text rendered inside a component instance is handled by that component's own master — don't try to override it from the screen.

1e. Identify pre-existing screen conflicts

Check whether screenName is in preExistingScreens. If yes — apply the Pre-Existing Screens Rule above and stop.

1f. Inspect the live page in Playwright

Before building, inspect the actual rendered page in the browser to capture computed styles on the page chrome. This provides ground-truth values for the page-level background, padding, and layout — more reliable than inferring from Tailwind classes alone.

Run inspect-styles.js against the page root selector on the dev server:

node {skillRoot}/scripts/inspect-styles.js \
  "{devServerUrl}/{route}" \
  --selector "[data-page='{ScreenName}'], main, #root > div" \
  --output ".temp/figma-from-code/screenshots/screens/{ScreenName}/"

This produces:

How to use the outputs:

Use exact padding and gap values to set Figma properties — these are the authoritative values for the page chrome. For colors, the computed RGB values are authoritative for what the color is, but not for how to apply it: reverse-match each one against the variable index first (node {skillRoot}/scripts/resolve-color.js 'rgb(...)' --context fill) and bind the matched variable (see §2e). Hardcode the RGB only when the match is "none".

Dev server is required — don't silently skip this step.

See Step 1g of plugins/figma-from-code/skills/figma-from-code/7-build-component/step-1-analyze.md for the full decision tree: orchestrator-dispatched vs standalone vs auto/non-interactive, how to derive selectors, and when escalation to the user is required.

Step 2: Build the Screen in Figma

2a. Create the screen frame

// use_figma
const screensFrame = figma.getNodeById('{screensFrameId}');
screensFrame.layoutWrap = 'WRAP';
screensFrame.counterAxisSpacing = 80;

const screen = figma.createFrame();
screen.name = '{screenName}';
screen.resize(1440, 900); // or screenBodySize values
screen.layoutMode = '{VERTICAL or HORIZONTAL}'; // from page root direction
screen.primaryAxisSizingMode = 'FIXED';
screen.counterAxisSizingMode = 'FIXED';
screen.itemSpacing = { gapValue };
screen.paddingTop = { pt };
screen.paddingBottom = { pb };
screen.paddingLeft = { pl };
screen.paddingRight = { pr };
screen.fills = [{ type: 'SOLID', color: { ...pageBackground } }];
// Bind the background variable when §2e reverse-match found one (it almost always does):
// screen.setBoundVariable('fills', 0, await figma.variables.getVariableByIdAsync('{backgroundVariableId}'));
screen.clipsContent = true;

// ... add region frames and component instances (Step 2b) ...

screensFrame.appendChild(screen); // do NOT set x/y — wrap layout positions it
return JSON.stringify({ name: screen.name, id: screen.id });

2b. Add component instances

For each component identified in Step 1b:

const comp = figma.getNodeById(builtComponents['{ComponentName}']);

// If component is a COMPONENT_SET, resolve the target variant
let master = comp;
if (comp.type === 'COMPONENT_SET') {
  const targetProps = { Variant: 'primary', Size: 'regular' }; // from source props
  master =
    comp.children.find((child) =>
      Object.entries(targetProps).every(
        ([k, v]) => child.variantProperties?.[k]?.toLowerCase() === v.toLowerCase()
      )
    ) ?? comp.children[0];
}

const instance = master.createInstance();
// Apply call-site sizing classes
if (callSiteHasWFull) instance.layoutSizingHorizontal = 'FILL';
if (callSiteHasFlex1) instance.layoutSizingHorizontal = 'FILL';
if (callSiteHasHFull) instance.layoutSizingVertical = 'FILL';
parent.appendChild(instance);

2c. Add region frames for nested layout

When the page source nests multiple components inside a layout container (e.g., a sidebar + main content row), create a region frame:

const row = figma.createFrame();
row.layoutMode = 'HORIZONTAL';
row.primaryAxisSizingMode = 'FIXED';
row.counterAxisSizingMode = 'FIXED';
row.layoutSizingHorizontal = 'FILL';
row.layoutSizingVertical = 'FILL';
row.itemSpacing = 0;
row.fills = [];
// ... append child instances ...
screen.appendChild(row);

2d. Tailwind-to-Figma mapping

Read {skillRoot}/7-build-component/figma-utils.md for the canonical fixSizing() definition and the Tailwind→Figma mapping table.

2e. Resolving page background colors

When the page root uses semantic colors (bg-background, bg-muted), resolve and bind the Figma variable — page chrome colors are exactly the colors that should stay coupled to tokens. The reverse-match-before-hardcode rule from 7-build-component/step-2-build.md §2e Step 0 applies to screens too:

1. Resolve the class or the computed RGB from computed-styles.json (Step 1f) via the lookup CLI:

   node {skillRoot}/scripts/resolve-color.js 'bg-background' --context fill
   # or, from computed styles:
   node {skillRoot}/scripts/resolve-color.js 'rgb(255, 255, 255)' --context fill

2. On match: "exact" or "tolerance", set the fill then bind: screen.setBoundVariable('fills', 0, await figma.variables.getVariableByIdAsync('{id}')).
3. Only on match: "none", hardcode the RGB from computed-styles.json.

(If tailwindConfigPath is null in state, class-based lookups still work — the CLI falls back to stripping known prefixes and matching CSS variable names directly.)

Step 3: Screenshot the Figma Result

get_screenshot(fileKey, screenFrameId)

Save to {screenshotDir}/figma.png:

curl -sL "{image_url}" -o "{screenshotDir}/figma.png"

Step 4: Compare Against App Screenshot

4-pre. Structural match check (run BEFORE sizing or pixel checks)

Before running any automated comparison, visually inspect both app.png and figma.png side by side. Check whether the two images show the same content structure:

• Do both show the same regions filled with the same type of content (list, detail, empty state)?
• Does one show an empty state ("No case selected") while the other shows a populated detail view?
• Are there overlays, dialogs, or menus visible in the Figma screenshot that don't appear in the app screenshot?
• Are there entire sections present in one but missing in the other?

If the two images show fundamentally different content — not just styling differences, but different components or states entirely — flag as structural_mismatch. This indicates the composition in Step 1b included wrong conditional branches and the screen must be rebuilt, not patched.

A structural_mismatch overrides any pixel score. Do not accept a high match percentage as valid when the content is visibly different — structural similarity in shared chrome (headers, sidebars) can inflate pixel scores even when the main content area is completely wrong.

"comparison": {
  "structuralCheck": {
    "verdict": "pass" | "structural_mismatch",
    "issues": ["Figma shows case detail view but app shows empty state 'No case selected'"]
  }
}

If structural_mismatch: enter Step 5 fix loop, but the fix is to re-run Step 1b with stricter screenshot-informed filtering, not to patch colors or spacing.