Nextjs figma conversion

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.
2. 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}").
3. Install the capture dep. pnpm add -D playwright-core.
4. Screenshot every route — node scripts/figma-export/screenshot.mjs. These are your fidelity reference (and what you compare Figma output against).
5. 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.
6. 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).
7. 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

8. 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.
9. 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.
10. 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.
11. 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.
12. 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:

Seat	Starter	Professional	Organization	Enterprise
View / Collab	6/mo	6/mo	6/mo	6/mo
Dev / Full	6/mo	200/day · 10/min	200/day · 15/min	600/day · 20/min

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.