figma-from-code-setup-structure

name	figma-from-code-setup-structure
description	Subagent for figma-from-code Phase 2. Creates the Figma file page skeleton, foundations documentation frames, and container frames needed by later phases. Requires variable collections to already exist.
model	claude-sonnet-4-5

Skill: Setup File Structure (Phase 2)

Creates the Figma file page skeleton, foundations documentation frames, and container frames needed by later phases. Runs as a subagent dispatched by the orchestrator, or standalone to set up a fresh Figma file for a code-to-Figma rebuild.

When to Use

• When figma-from-code orchestrator reaches Phase 2
• Standalone to set up a fresh Figma file after variable collections exist

Prerequisites

• Variable collections (Palette, Semantic, Spacing) must already exist in the file (Phase 1 complete)
• Load figma:figma-use (mandatory) before any use_figma call

Required Inputs

Input	Description	Source
fileKey	Figma file key	State ledger
existingPages	Pages already present in the Figma file	Phase 0a Figma inspection

Placeholders like {skillRoot} resolve from state.json → config.

Output Files

File	Contents	Consumed by
.temp/figma-from-code/structure-summary.json	All page and frame node IDs	Orchestrator (merges into state.json -> figmaNodes)

Workflow

1. Create Pages

Rename/create pages in this exact order. If a page with the target name already appears in existingPages, skip its creation.

Page Name	Purpose
🎨 Foundations	Color swatches, type specimens, spacing scale
📦 Components	All component sets (built in Phase 3)
📄 Screens	Assembled page screens (built in Phase 4)

2. Build Foundations Page Content

On the 🎨 Foundations page, create three documentation frames stacked vertically with 80px gaps. All content is driven by the Figma variables created in Phase 1 — never hardcode color values.

Work in separate incremental use_figma calls (one per frame) to stay under the size limit. After each call, capture the returned node IDs and take an inline screenshot for verification.

Frame 1: Color Palette (y=0)

Name: Color Palette Width: 1200, height: auto Background: white, padding: 48px all sides Layout: VERTICAL, gap 40px

Building the palette dynamically:

1. Query all variables in the Palette collection via figma.variables.getLocalVariablesAsync()
2. Group by color family (the prefix before / in the variable name, e.g., gray, teal)
3. For each family, create a horizontal row:
   • Scale label: Inter Semi Bold 12px, #64748b, width 60px (family name)
   • One swatch per step (50→950): 40×40px rectangle, cornerRadius 6, filled with the bound Palette variable
   • Tooltip text below showing the step number

Bind swatch fills to variables rather than hardcoding hex values:

const vars = await figma.variables.getLocalVariablesAsync();
const colorVar = vars.find(v => v.name === "Palette/{family}/{step}");
const swatch = figma.createRectangle();
swatch.fills = [figma.variables.setBoundVariableForPaint(
  { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", colorVar
)];

Frame 2: Semantic Colors (y = Frame1.height + 80)

Name: Semantic Colors Width: 1200, height: auto Background: white, padding: 48px, layout: VERTICAL, gap: 32px

Building semantic swatches dynamically:

1. Query all variables in the Semantic collection
2. Group by the token's first path segment (e.g., background, primary, border, sidebar)
3. For each group, create a horizontal row with a label and swatches
4. Each swatch: 48×48px, cornerRadius 6, filled with the bound Semantic variable, label below (12px, #64748b, truncated to 14 chars)

Frame 3: Spacing Scale (y = Frame2.y + Frame2.height + 80)

Name: Spacing Scale Width: 1200, height: auto Background: white, padding: 48px, layout: VERTICAL, gap: 20px

Title: "Spacing Scale" (Inter Bold 24px)

Two sub-sections side by side (horizontal layout):

Spacing: Query all spacing/* variables from the Spacing collection. For each value:

• Horizontal row: colored rectangle (width = value px, height 24px), label spacing/{n} = {value}px (Inter Regular 13px, #334155)

Border Radius: Query all radius/* variables from the Spacing collection. For each value:

• Row: 32×32px white rectangle with border (#e2e8f0), cornerRadius = value, label radius/{name} = {value}px

3. Create Icons and Screens Container Frames

Create only the Icons frame (on the Components page) and the Screens container frame (on the Screens page). Tier frames are created on-demand at the start of each tier build in Phase 3.

await figma.setCurrentPageAsync(componentsPage);

const iconsFrame = figma.createFrame();
iconsFrame.name = 'Icons';
iconsFrame.layoutMode = 'HORIZONTAL';
iconsFrame.primaryAxisSizingMode = 'AUTO';
iconsFrame.counterAxisSizingMode = 'AUTO';
iconsFrame.layoutWrap = 'WRAP';
iconsFrame.itemSpacing = 24;
iconsFrame.counterAxisSpacing = 24;
iconsFrame.paddingTop = 24;
iconsFrame.paddingBottom = 24;
iconsFrame.paddingLeft = 24;
iconsFrame.paddingRight = 24;
iconsFrame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
iconsFrame.x = 0;
iconsFrame.y = 0;
componentsPage.appendChild(iconsFrame);

await figma.setCurrentPageAsync(screensPage);
const screensFrame = figma.createFrame();
screensFrame.name = 'Screens';
screensFrame.layoutMode = 'HORIZONTAL';
screensFrame.primaryAxisSizingMode = 'AUTO';
screensFrame.counterAxisSizingMode = 'AUTO';
screensFrame.itemSpacing = 80;
screensFrame.paddingTop = 80;
screensFrame.paddingBottom = 80;
screensFrame.paddingLeft = 80;
screensFrame.paddingRight = 80;
screensFrame.fills = [{ type: 'SOLID', color: { r: 0.973, g: 0.973, b: 0.98 } }];
screensFrame.x = 0;
screensFrame.y = 0;
screensPage.appendChild(screensFrame);

return { iconsFrameId: iconsFrame.id, screensFrameId: screensFrame.id };

4. Screenshot for Verification

Take a screenshot of the Foundations page and the Components page:

get_screenshot(fileKey, foundationsPageId)
get_screenshot(fileKey, componentsPageId)

5. Write Summary

Write the page and container frame node IDs to the summary file:

{
  "foundationsPageId": "...",
  "componentsPageId": "...",
  "screensPageId": "...",
  "foundationsFrameId": "...",
  "iconsFrameId": "...",
  "screensFrameId": "...",
  "foundationsScreenshot": ".temp/figma-from-code/screenshots/foundations.png"
}

Write to .temp/figma-from-code/structure-summary.json.

6. Report

Phase 2 complete:
- 3 pages created (Foundations, Components, Screens)
- Foundations page: Color Palette, Semantic Colors, and Spacing Scale frames created
- Icons frame + Screens container frame created
- Tier frames will be created on-demand at the start of each Phase 3 tier build

Skip / Resume

Skip the entire phase if .temp/figma-from-code/structure-summary.json exists and all page IDs, iconsFrameId, and screensFrameId in the summary are verified to exist in Figma (use get_metadata or use_figma to check).

If the summary file exists but some node IDs are missing or invalid, create only the missing pages/frames (all steps are idempotent — skip creation of any page or frame that already exists).

Error Handling

Scenario	Action
Page/foundations frame creation fails	Report error; page creation is required for downstream phases
use_figma container frame fails	Retry once; if still failing, report which frames were created
Pages already exist but frames don't	Create only the missing frames (idempotent)