Next.js → Figma Conversion

Turn a running web app into a native, editable Figma file. The strategy is capture, then reconstruct: there is no automatic code→Figma exporter, so we drive the rendered app to extract exact geometry, then rebuild it in Figma via the Plugin API. This produces real Figma variables, components, and frames — not flat screenshots.

Prerequisites

• The Figma MCP server is connected (see mcp__plugin_figma_figma__* tools). If

not, call its authenticate tool and have the user approve the OAuth URL.

• Always load the `figma-use` skill before every `use_figma` call — it is a

hard requirement and prevents common failures.

• The app builds and runs locally (npm/pnpm/yarn dev).
• A real Chrome is installed (the scripts drive it via playwright-core with

channel: 'chrome', avoiding a ~150 MB browser download).

The pipeline (run in order)

Copy scripts/ into the project (e.g. scripts/figma-export/) and create a figma-export.config.json from assets/figma-export.config.example.json. All scripts read that config (path overridable as argv[2]).

1. Explore & confirm scope. Read package.json, app//pages/, the global

CSS (design tokens / :root CSS variables), components.json, and the shared components. List every route. For dynamic routes ([id]) find a real id from fixture/seed data. Decide scope with the user: full (tokens + components + all screens), key screens, or tokens-only.

1. Run the app. pnpm install then start the dev server in the background.

Verify each route returns 200 (curl -o /dev/null -w "%{http_code}").

1. Install the capture dep. pnpm add -D playwright-core.
2. Screenshot every route — node scripts/figma-export/screenshot.mjs.

These are your fidelity reference (and what you compare Figma output against).

1. Extract DOM geometry — node scripts/figma-export/extract-layout.mjs.

Walks the rendered DOM and emits, per element, absolute x/y/w/h, background, border, radius, opacity, and text (content, color, font size/weight/family). Colors are resolved through a <canvas> so Tailwind v4 oklch/color-mix values come back as sRGB, and alpha is preserved separately.

1. Flatten — node scripts/figma-export/flatten.mjs. Converts each DOM tree

into a preorder, absolutely-positioned node list (parents before children → correct paint/z-order when appended flat to one frame).

1. Generate renderer scripts — node scripts/figma-export/gen-figma.mjs.

Writes one self-contained use_figma script per route (renderer + inline data), laid out left-to-right on the canvas, each under the 50 KB code limit.

Build the Figma file

1. Create the file with mcp__plugin_figma_figma__create_new_file

(editorType design). If the user has multiple plans, ask which team. Make three pages: 🎨 Tokens, 🧩 Components, 📐 Screens.

1. Tokens — create one variable collection from the CSS variables. Colors get

color-usage scopes (FRAME_FILL, SHAPE_FILL, TEXT_FILL, STROKE_COLOR); radii are FLOAT with scope CORNER_RADIUS. Bind each to a swatch so it doubles as a living reference. See references/figma-build.md.

1. Components — build the repeated UI (nav/sidebar, badges, chips, buttons,

list rows, panels) as variant sets (combineAsVariants) bound to the token variables. SVG logos/icons import cleanly via figma.createNodeFromSvg — substitute currentColor with a real hex in the string first.

1. Screens — for each generated script, Read it and pass its contents as the

code arg to use_figma. The renderer is idempotent (it removes any existing frame of the same name first), so re-running a single screen is safe.

1. Validate — screenshot one representative screen with

get_screenshot, compare to the reference PNG, fix the renderer if needed, regenerate, re-run. The demo/first screen is the canary: once it matches, the rest use the identical renderer.

Critical gotchas (these will bite you)

Read references/figma-gotchas.md for the full list. The highest-impact ones:

• Tailwind v4 colors are `oklch`/`color-mix`. getComputedStyle returns them

literally; naive RGB parsing yields garbage (e.g. a primary/10 tint becomes #010000). The extractor resolves every color via a 1×1 canvas → sRGB.

• Preserve alpha as fill opacity. A semi-transparent bg flattened to an opaque

hex hides its own text. Capture alpha separately and set it as the Figma paint's opacity (and capture element opacity too).

• `setBoundVariableForPaint` drops opacity. Set opacity on the returned

paint, not the input: {...figma.variables.setBoundVariableForPaint(p,'color',v), opacity: o}.

• Render box AND text for combined nodes. An element with both a background and

direct text (buttons, badges, chips) must produce a frame and a text node, or you lose the background. Center the text within the box.

• Hug single-line text; fix width only for paragraphs. Figma's font metrics are

slightly wider than the browser's, so a fixed-width single-line label wraps. Use WIDTH_AND_HEIGHT for single lines (heuristic: h <= fontSize*1.7) and HEIGHT (fixed width) only for true multi-line text.

• Clamp radius. border-radius: 9999px arrives as a huge number; clamp to

min(r, w/2, h/2).

• `use_figma` `code` is capped at 50 KB. Keep per-screen payloads small

(compact JSON, short keys); split very large screens across calls if needed.

• Switch pages with `await figma.setCurrentPageAsync(page)` — the sync setter

throws. Set it at most once per call.

Figma MCP rate limits (plan ahead)

Only read tools (get_screenshot, get_metadata, get_design_context, get_variable_defs) count against limits. Write tools (use_figma, create_new_file, whoami) are exempt. Caps by plan/seat:

Implication: spend screenshots sparingly. On Starter you get ~6 reads/month — verify the canary screen, then trust the validated renderer for the rest. You can keep building/editing freely because writes don't count.

Files in this skill

• scripts/ — _config.mjs, screenshot.mjs, extract-layout.mjs,

flatten.mjs, gen-figma.mjs.

• references/figma-build.md — variable/component/screen build details & snippets.
• references/figma-gotchas.md — every known pitfall with the fix.
• assets/figma-export.config.example.json — config template.