prototype-to-figma
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.
alima-max · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add alima-max/prototype-to-figma-skill --skill prototype-to-figmaAbout this 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:
- 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.
- 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):
- Ensure the dev server is running — start it in the background if needed. Determine the route URLs from the codebase.
- Launch a headless browser from the terminal and run the
generate_figma_designcapture script (navigate to the LOCAL dev URL → strip CSP → injectcapture.js→window.figma.captureForDesign( { captureId, endpoint, selector:'body' })). Prefer the machine's already-installed Chrome (puppeteer-core, or Playwright withchannel:'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/ fullpuppeteer). Never launch a new visible instance, never attach to the user's live browser, never useopen "<url>#figmacapture=…"or the in-app preview — all of those put a window/tab on screen. - Poll
generate_figma_design(fileKey + captureId) untilcompleted. 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
Read the complete source ↗