/prototype-to-figma-skill

name: prototype-to-figma
description: >
  Converts a working Claude Code prototype into a structured Figma design file — exploding each
  interaction flow into separate frames, using the target file's design system components, and
  annotating interaction details natively in Figma. Use this skill whenever the user asks to
  turn a prototype into Figma frames, generate design specs from a prototype, create a Figma
  handoff from code, explode a prototype into states, or make a prototype reviewable by
  cross-functional partners. Also trigger when the user mentions "prototype to Figma",
  "design review from prototype", "async feedback on prototype", "break prototype into flows",
  "Figma specs from code", or wants to make a working prototype legible to non-technical
  stakeholders. Even if the user just says "put this in Figma" or "make this reviewable" in the
  context of a prototype, use this skill.

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](#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