Imported from alima-max/prototype-to-figma-skill (SKILL.md). Install upstream with npx skills add alima-max/prototype-to-figma-skill. Copyright stays with the author.

Prototype → Figma

This skill takes a working Claude Code prototype and produces a structured Figma file that cross-functional partners can review asynchronously. The output has two equal goals:

1. True 1:1 visual parity — layout, colors, spacing, typography, content, and icons match the rendered prototype exactly, because the base is produced by a headless render → serialize (Rule 0), not a hand-reconstruction. Runs entirely in the terminal — no visible browser or tab.
2. A design-system-native, reviewable result — captured elements are reconciled to DS component instances / bound variables / text styles wherever the DS is published to Figma (Rule 2), and every state transition is annotated on its node.

This skill works across all Figma MCP clients. The output format adapts to what your client supports — see Client Compatibility below.

Five non-negotiable rules

Rule 0: Capture headlessly (render → serialize), never open a visible browser; then reconcile to the DS

True 1:1 requires rendering the code — but rendering does NOT require a visible browser. Use a headless browser (Playwright) so the whole run stays in the terminal: no window, no tab. That is the point for the target user — designers working exclusively in code who must not be pulled out of the IDE.

Three options; only one is right:

• ❌ Read source and hand-build (no render). An LLM re-deriving a browser's layout/render engine element-by-element is lossy, incomplete, and buggy on any non-trivial page. It is not 1:1 — it only looks faithful on small, static UIs, and it drifts badly on real ones (collapsed grids, missing elements, half-built SVGs). Do not pretend this is 1:1.
• ❌ Visible capture — open "<url>#figmacapture=…", the in-app preview, or the GUI Figma extension. Correct fidelity, but it pops windows/tabs and drags the designer out of the terminal (and the bare extension gives no DS instances).
• ✅ Headless capture. A headless browser renders the running app in the background and serializes the DOM 1:1 straight to Figma (data goes browser→Figma, never through the model — so it's fast and cheap). The model then adds the design-system layer. Terminal-native, 1:1, invisible.

"Headless" = a separate Chrome process launched with --headless: no window, no tab, nothing on screen. It does NOT attach to the designer's open browser and does NOT require Chrome to be open — only installed. It spins up invisibly, renders the localhost page in memory, serializes to Figma, and exits. The designer never leaves the terminal and sees nothing happen in their browser.

The capture (headless, terminal-only):

1. Ensure the dev server is running — start it in the background if needed. Determine the route URLs from the codebase.
2. Launch a headless browser from the terminal and run the generate_figma_design capture script (navigate to the LOCAL dev URL → strip CSP → inject capture.js → window.figma.captureForDesign( { captureId, endpoint, selector:'body' })). Prefer the machine's already-installed Chrome (puppeteer-core, or Playwright with channel:'chrome', or raw CDP) so there's no download and no MCP — Chrome need only be installed, not open. Only if no Chrome/Chromium is found, fall back to a one-time bundled-Chromium download (npx playwright install chromium / full puppeteer). Never launch a new visible instance, never attach to the user's live browser, never use open "<url>#figmacapture=…" or the in-app preview — all of those put a window/tab on screen.
3. Poll generate_figma_design (fileKey + captureId) until completed. You get a fully-layered 1:1 base (frames / text / vectors) with tokens bound (bindVariables=true).

Then reconcile to the DS + annotate (use_figma, Rule 2): swap repeated captured elements for DS component instances, bind variables / text styles where the DS is actually published to Figma, and attach Dev Mode annotations + flow arrows. This is the cheap, surgical layer — it touches a handful of components, not the whole page.

Requirements / honesty: needs (a) a headless browser — ideally the machine's installed Chrome driven headless (no download, no MCP required); a bundled Chromium download is the fallback — and (b) a runnable dev server. No Playwright MCP is required; a headless Chrome runtime is. If there's genuinely no browser at all, say so and stop — do not fall back to a visible tab, and do not hand-build from source and call it 1:1 (it won't be). If the design system isn't published to Figma as components/variables, reconciliation is limited to what exists — flag that DS gap, don't swap in a foreign library's components.

Rule 1: Never create new Figma components

Do not call figma.createComponent() or figma.createComponentSet(). These pollute the design system with components that don't belong there.

When a prototype element has no component of any kind in the DS (see Rule 2 for the bar): build it from primitives (figma.createFrame(), figma.createRectangle(), figma.createText()), add a DS Drift annotation explaining what was missing, and list it in the Phase 6 summary.

Rule 2: Always use a DS component / variable / style when one exists — the capture does NOT relax this

The capture (Rule 0) gives parity; this rule makes the file design-system-native. It applies as you reconcile each captured element — the captured node tells you where, how big, and how it looks, but the structure should come from the DS wherever a match exists. Walk the captured frame and reconcile every element to the linked library:

1. Components — always instance, never shadow. If a captured element matches a DS component, replace it with an instance and override props (fill, text, size) to match the captured pixels. If the component exists but lacks the exact variant, still instance it + override, and add a DS Drift annotation. Only when there is no matching component does the element stay a primitive — flagged DS Drift. Repeated elements especially: 60 badges = 60 instances, never 60 frames. A frame full of primitives that shadow real components is a failed run even if the pixels are perfect.
2. Color variables — always bind. Every fill/stroke whose value matches a DS color variable MUST bind that variable. Never leave a raw hex where a color variable exists.
3. Number variables — always bind. Every spacing, gap, padding, corner radius, border width, size, and font-size that matches a DS number/dimension variable MUST bind it. Never leave a raw number where a number variable exists.
4. Text styles — always apply. Body/label/heading text binds to the library text style, not raw fontSize/fontName.

The rule in one line: prefer the component / color variable / number variable / text style over any literal whenever a match exists. Raw hex, ad-hoc numbers, and shadow-primitives are drift — not parity — even when they look right. Phase 2 discovers the components, variables, and styles; Phase 4 swaps and binds them onto the captured base.

Rule 3: Never omit a prototype element

Every visible element must appear in the Figma output — DS instance or primitive. Skipping elements because you couldn't find a DS match is the most common cause of incomplete outputs.

Rule 4: Annotations must be attached to nodes, and must be flow-critical only

Annotations are what make this output useful for review. A frame with no annotations is just a static image. But annotating every tap target creates noise that buries the actual flow.

Annotate using node.annotations = [...] on the actual layer — this surfaces in Figma Dev Mode on the correct element. Never create floating text boxes or separate annotation frames as a substitute. If the native API fails, fall back to figma-patterns.md Section 11.

Two categories only:

• Interaction (blue) — state transitions, primary CTAs, grouped controls
• DS Drift (orange) — missing DS component, missing variant, or unbound color/spacing

Annotate (Interaction):

• Frame-level — one annotation per frame: what state this is and what the primary action does / where it goes next
• State-advancing CTAs — the action(s) that trigger a state change (e.g., Submit, Confirm, Create goal, Move to completed)
• Grouped controls — annotate the container once, not each item (annotate the amount picker row, not each chip; annotate the story pill rail, not each pill)
• Non-obvious tap targets — elements that open a new state but don't look like buttons (e.g., a goal card that opens a detail sheet)

Do not annotate:

• Close / cancel / dismiss buttons
• Nav bar buttons and tab items
• Secondary utility actions (settings, prototype controls)
• Individual chips or pills within a grouped picker
• Backdrops and overlays
• Decorative elements

Target: 2–4 Interaction annotations per frame. A reviewer should be able to read all annotations on a frame in under 30 seconds and understand the complete flow.

Every element with a DS Drift note from Phase 2 must have a DS Drift annotation.

Client Compatibility

Figma MCP tools

Inspect: get_design_context (primary), get_metadata (structure overview), search_design_system (components + variables), get_variable_defs (exact token values), get_screenshot (only if user explicitly requests a visual preview).

Capture (primary path — Rule 0): generate_figma_design driven by a headless browser — ideally the machine's installed Chrome run headless (puppeteer-core / Playwright channel:'chrome' / CDP; no download, no MCP), bundled Chromium only as a fallback — against the local dev server. Renders + serializes 1:1 to Figma with no visible window/tab. NEVER the open-a-tab flow or the in-app preview (visible), and never attach to the user's open browser.

Write: use_figma (reconcile captured nodes to DS instances + variables, annotate, assemble the flow), whoami, create_new_file.

Code Connect: get_code_connect_map, get_code_connect_suggestions, get_context_for_code_connect, send_code_connect_mappings.

The workflow

Phase 0: Resolve file and detect capabilities

File: Extract fileKey from a user-provided URL (figma.com/design/:fileKey/...). If no URL is given, call whoami then create_new_file — never block on a missing URL.

Capabilities: Attempt get_metadata to confirm Inspect tools. Check tool list for use_figma (Write) and get_code_connect_map (Code Connect). Announce what you have.

Route: Write tools available → Phases 1–6. Write tools unavailable → Phases 1–3, then Prototype Spec Document.

Phase 1a: Analyze the prototype

Read all prototype source files before touching Figma.

Component inventory — for every UI component, record: name, props/variants in use, visual structure (what's inside it), and whether it is interactive. This list is the completeness checklist for Phase 4.

Interaction flows — for each flow, map: trigger → state change → before/after states → branching paths (success / error / edge cases). Include state count.

Layout structure — note what's fixed vs. scrollable, what persists across states (nav, header), and the viewport dimensions. For the phone/device frame: if the prototype wraps screens in a .phone, .device-frame, or similar shell, extract only the content dimensions and use those for Figma frame size — do not recreate the shell as a wrapper frame in Figma.

Source read (for inventory + structure, NOT for pixel values) — read the CSS modules, Tailwind config, and inline styles to understand each element's structure, variants, and which are interactive. Do not treat source CSS values as the pixel source of truth: responsive/ computed CSS (grid fr, clamp(), min/max, vw, transforms, theme scopes) resolves to formulas, not pixels. The pixel source of truth is the computed measurement from the running app (Rule 0 / Phase 4). Use source reading only to know what to measure and match to the DS.

Phase 1b: Present scope, get selection, confirm

Skip if the prototype has ≤ 2 flows. Proceed directly to Phase 2 with all flows.

For 3+ flows, present a categorized flow list with state counts, ask "which flows and how much detail (happy path / all states)?", and wait for a reply before proceeding. Confirm the interpretation explicitly before starting Phase 2.

Phase 2: Discovery pass — map to the design system before drawing anything

Do a full discovery pass against the linked library first, then map every element. Do not start building until this table exists. The default is instance, not primitive (Rule 2).

2a. Enumerate the library once, up front. Before searching per component, pull the catalog so you know what exists:

• Components: search_design_system(fileKey, includeComponents=true) with broad queries, plus category sweeps ("input", "navigation", "feedback", "card", "badge", "avatar", "table") to surface the full set — not just the names your code happens to use.
• Variables: search_design_system(..., includeVariables=true) and get_variable_defs for color, spacing, radius, and border-width tokens. Record the keys.
• Text styles: capture the library's typography styles (name → font, size, weight, line height) from search_design_system / get_variable_defs. These are what body copy, labels, and headings must bind to — not hardcoded hex + ad-hoc fontSize.

2b. Match each inventory element (try in order before declaring "no match"):

1. search_design_system(fileKey, query="ComponentName", includeComponents=true)
2. Alternate names: Alert/Banner/Toast/Notification, Dropdown/Select/Menu, Tag/Chip/Badge, Nav/Sidebar/TabBar, TextField/Input, TextArea/Multiline, Avatar/UserPill, etc.
3. Visual category: "input", "navigation", "feedback", "card"
4. Parent component coverage (e.g., "Card" covers Card.Header)

For found components: call get_context_for_code_connect to get exact variant prop names before setting properties in Phase 4.

When a component exists but the exact variant does not: do not drop to a primitive. Instantiate the component and override the differing property per-instance (fill, text, size), then add a DS Drift annotation for the missing variant. Only elements with no matching component at all become primitives.

Build the mapping table — every row needs a build approach and drift note:

Also record, for each element, which text style and color/spacing/radius/border-width variables it should bind to in Phase 4. Any row with ⚠️ must get a DS Drift annotation in Phase 4. A row that says "Primitives" is only valid if 2b found nothing — not because a variant was missing.

2c. Resolve themed / runtime-remapped CSS-variable tokens — never trust the raw var(). When colors, spacing, or radii come from CSS custom properties (var(--token-…)) that a runtime theme provider remaps — e.g. a ThemeScope / data-theme / class-based provider that changes what --token-color-purple-100 resolves to per brand or per light/dark scheme — the raw CSS value is not the rendered value. Reading the stylesheet alone yields the variable name or its top-of-file default, not what the user actually sees in that themed context. This is a silent parity killer: the most common symptom is a themed surface (a dark footer, an inverted hero) rendering blank/white in Figma because its fill was never resolved and set.

Resolve the rendered value, then bind it — three steps, in order:

1. Get the true value from the running app, not the source. Read the element's computed style in the browser (getComputedStyle / an inspect tool → background-color, color, gap, border-radius, …) so the theme remap collapses to a concrete rgb() / px. If no running app is available, resolve the variable chain manually through the active theme's mode, not the :root default.
2. Match it to a native Figma variable. Search the linked library (search_design_system with includeVariables=true, get_variable_defs) for a variable whose resolved value equals it under the corresponding mode/theme. If found, bind the variable (Phase 4 §3.2) so the node stays theme-aware — this is always preferred over a literal.
3. If no Figma variable matches, apply the resolved literal as a primitive value AND add a DS Drift annotation. The token exists in code but has no design-system variable counterpart — a real gap for the design team to close. Record it as a ⚠️ row in the mapping table.

Never leave a themed token unresolved (raw var() name, :root default, or an unset fill). "I read it from the CSS" is not sufficient when a theme scope sits between the token and the pixel.

Phase 3: Plan the page structure

Page: "[Feature Name] — Prototype Flows"
  Section: "Flow 1: [Flow Name]"
    Frame: "1.1 — [State description]"   ← left-to-right within a flow
    Frame: "1.2 — [State description]"
    Frame: "1.3a — Success"
    Frame: "1.3b — Error"               ← branches stacked vertically
  Section: "Flow 2: [Flow Name]"
    ...

Frame size: match the CSS-measured viewport (e.g., 390×844 mobile, 1440×900 desktop). For scrollable states, set frame height to full content height — never clip at viewport height. Add a fold marker line at the viewport height. ~200px gaps between frames, ~400px between sections.

Phase 4: Headless-capture the pixels, then reconcile to the DS

Step 1 — Capture headlessly (Rule 0). Make sure the dev server is running (start it in the background if needed) and resolve the route URLs from the codebase. For each route/state, call generate_figma_design (fileKey) to get a captureId + the capture script, then run the headless Playwright variant of that script against the LOCAL dev URL — navigate, strip CSP, inject capture.js, window.figma.captureForDesign({...}). No open, no visible tab, no in-app preview. Poll generate_figma_design(fileKey, captureId) until completed. Result: a fully layered 1:1 base per state, sent browser→Figma directly.

Step 2 — Reconcile to the DS (Rule 2). Walk each captured frame and, for every element with a Phase 2 match, swap it for a DS component instance (override to match the captured pixels), bind color + number variables and text styles where the DS is published to Figma. Elements with no match stay as the captured node, flagged DS Drift. This is the cheap surgical layer — a handful of components, not the whole page. If the DS isn't in Figma at all, keep the capture as-is and flag it.

Step 3 — Assemble + annotate (Phase 5). Arrange the state frames into the flow, add arrows, and attach Dev Mode annotations.

If there's no headless browser or no dev server: stop and tell the user what's missing. Do NOT fall back to a visible tab, and do NOT hand-build from source and label it 1:1.

Placement: scan the target page with get_metadata first. If matching frames/sections exist for this feature, insert beside them. If not, create a named section: [Prototype] <feature name>. Never place frames at an arbitrary far-Y without reporting coordinates and a deep-link in the Phase 6 summary.

DS component instances — see figma-patterns.md Section 3 for importComponentByKeyAsync

• setProperties.

Primitives — see figma-patterns.md Section 4. Use the computed measured values (Rule 0) for all dimensions, radii, and colors.

Fixed-size square/circle containers (avatars, number badges, icon chips): set both axes to fixed sizing — never let auto-layout hug. A hugging container collapses to the width of its glyph, so a 32×32 avatar renders 32px tall but ~10px wide. Use primaryAxisSizingMode = 'FIXED' and counterAxisSizingMode = 'FIXED' after resize(size, size), or skip auto-layout and center the child manually. See figma-patterns.md Section 4.1.

DS variable + text-style binding — for every fill, radius, spacing, and border-width where a variable key was found in Phase 2, bind it instead of hardcoding. Bind body/label/heading text to the library text style instead of setting raw fontSize/fontName. The variables API lives under figma.variables.* (NOT the figma global), and setBoundVariableForPaint takes a paint and returns a new one you must reassign:

// Color fill → variable. setBoundVariableForPaint returns a NEW paint — reassign node.fills.
const colorVar = await figma.variables.importVariableByKeyAsync(colorVarKey);
let fills = node.fills;
if (fills && fills !== figma.mixed && fills.length && fills[0].type === 'SOLID') {
  fills = [...fills];                        // copy — assigning into the live array is a no-op
  fills[0] = figma.variables.setBoundVariableForPaint(fills[0], 'color', colorVar);
  node.fills = fills;                        // reassign — required
}

// Scalar fields (radius / border-width / spacing) → node.setBoundVariable
const radiusVar = await figma.variables.importVariableByKeyAsync(radiusVarKey);
node.setBoundVariable('cornerRadius', radiusVar);   // fallback: pass radiusVar.id
const borderVar = await figma.variables.importVariableByKeyAsync(borderWidthVarKey);
node.setBoundVariable('strokeWeight', borderVar);   // not a raw strokeWeight

// Typography → library text style (styles use figma.importStyleByKeyAsync, NOT the variables API)
const textStyle = await figma.importStyleByKeyAsync(textStyleKey);
await textNode.setTextStyleIdAsync(textStyle.id);   // font/size/weight/lineHeight; fill stays separate

⚠ figma.importVariableByKeyAsync(...) (no .variables) and node.setBoundVariableForPaint('fills', 0, ...) THROW in the Figma MCP runtime — use the forms above. Cache imports (one per key), then bind.

Page and surface backgrounds must bind to the surface/wash color variable too — never a raw page-background hex. Fall back to raw CSS values only when Phase 2 found no DS variable or text style for that role (and note it as drift).

Annotations — attach to nodes during build, not after

Set up two annotation categories once at the start of your first use_figma call:

let interactionCat = null, dsDriftCat = null;
try {
  const existing = await figma.annotations.getAnnotationCategoriesAsync();
  interactionCat = existing.find(c => c.label === 'Interaction')
    ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'Interaction', color: 'blue' });
  dsDriftCat = existing.find(c => c.label === 'DS Drift')
    ?? await figma.annotations.addAnnotationCategoryAsync({ label: 'DS Drift', color: 'orange' });
} catch(e) { /* native API unavailable — use layer name fallback below */ }

As you build each node, annotate it immediately — do not defer annotation to a separate pass. Keeping the node reference in scope is the only reliable way to attach to the right layer:

// Interaction annotation — on the node itself, right after creating it
const ctaButton = figma.createFrame(); // ...build it...
ctaButton.name = 'CTA: Submit';
ctaButton.annotations = [{
  label: 'Tap → submits form; on 200 navigates to success screen; on 4xx shows inline error',
  ...(interactionCat ? { categoryId: interactionCat.id } : {})
}];

// DS Drift annotation — on any primitive or mismatched DS component
const customCard = figma.createFrame(); // ...build it...
customCard.name = 'Card: Goal (primitive)';
customCard.annotations = [{
  label: 'DS Drift: no Card/Goal component found in library (searched: Card, Panel, Tile). DS gap for design team.',
  ...(dsDriftCat ? { categoryId: dsDriftCat.id } : {})
}];

// Fallback if native API failed: encode in layer name
if (!interactionCat) ctaButton.name += ' [Interaction: tap → submit form]';
if (!dsDriftCat) customCard.name += ' [DS Drift: no Card/Goal in DS]';

Annotation checklist per frame:

• Frame itself has one annotation: current state + what the primary action does / where it leads
• Each state-advancing CTA has an annotation (trigger → result)
• Grouped controls (pickers, pill rails, option lists) have one annotation for the group, not per item
• Every primitive or mismatched DS component has a DS Drift annotation

Completeness check: before moving to the next frame, verify every row from the Phase 2 mapping table that belongs in this frame is present in the layer tree.

Phase 5: Add a flow overview frame

One frame at the top of the page:

• Feature name, flow list, frame count
• Annotation legend: blue = Interaction, orange = DS Drift (filterable in Dev Mode)
• DS gaps: list all primitives and mismatched components for the design team
• Open questions: flag any ambiguous prototype behavior
• Scope note if flows were omitted (offer to re-run skill to add them)

Phase 6: Verify and present

6a. Completeness check — via get_metadata on the output, verify:

• Every row in the Phase 2 mapping table has a named layer in the correct frame
• Every element with a DS match is an instance, not a primitive — including repeated elements (badges, nav, inputs, textareas, avatars). Primitives appear only for rows Phase 2 confirmed had no match; each such primitive carries a DS Drift annotation.
• Frame dimensions match the CSS-measured viewport
• No new master components were created in local assets
• DS variable bindings are present on color fills, border-radii, and border-widths; text binds to library text styles; page/surface backgrounds bind to a surface variable
• Square/circle containers render square — width equals height (no hug collapse)
• Inline SVGs survived — if the app has any <svg> (logo, icons, decorative blobs) the output must contain VECTOR nodes for them. A frame with 0 vectors means every inline SVG was dropped (wrong/placeholder logo, empty footer, blob-less card art) — go back and add them via createNodeFromSvg.

Fix anything missing with a follow-up use_figma call before presenting.

6b. Code Connect (optional) — get_code_connect_suggestions → review → send_code_connect_mappings.

6c. Present to user:

• Figma file URL (always) + deep-link to the section node if not at the canvas origin
• Flow count, frame count
• DS instances vs. primitives used
• Full list of DS gaps (primitives) for the design team
• Any deviations from CSS measurements and why
• Steps skipped due to capability limits

Prototype Spec Document — Inspect-only output

When Write tools are unavailable, produce a structured markdown document using the template in figma-patterns.md Section 12.

Important principles

Instance first, primitive last. The value of this skill is not rebuilding by hand. If the DS has a component — even without the exact variant — use it with an override. Bind typography, color, spacing, radius, and border-width to DS styles and variables. A pixel-accurate frame made of primitives that shadow real components is still a failed run.

Render, then serialize — headlessly. True 1:1 comes from a headless browser rendering the code and serializing the result to Figma, not from an LLM re-deriving layout from source (lossy on any real page) and not from a visible capture (pulls the designer out of the terminal). Headless = same fidelity, invisible, terminal-native. The model's job is the DS + annotation layer on top, not reproducing the pixels by hand.

Annotate on the node, not the canvas. node.annotations = [...] is what surfaces in Dev Mode. Floating text boxes and separate annotation frames are noise, not annotations.

Name everything. "Frame 47" is useless. "2.3a — Save success with toast" tells a reviewer exactly where they are.

Annotate flows, not tap targets. The goal is for a reviewer to read all annotations on a frame in under 30 seconds and understand the complete flow. Annotate the state transition, not the mechanism — one annotation on the amount picker row beats four identical annotations on each chip inside it.

Be explicit about DS gaps. List every primitive in the summary so the design team knows what components are missing from the DS. This turns unmatched elements from a silent failure into actionable signal.

Reference: Figma Plugin API patterns

See figma-patterns.md for Plugin API patterns — frame creation, component importing, primitive helpers, addNoDsMatchBadge, auto-layout, text nodes, annotation setup, and the Prototype Spec Document template. Read this before your first use_figma call. (Write-tier clients only.)