takazudo/dev-figma-capture

Figma Capture

Capture web pages and convert them to editable Figma design files via Figma MCP.

Prerequisites

• Figma MCP (remote) must be connected: claude mcp add --transport http figma https://mcp.figma.com/mcp
• For Playwright path: playwright npm package available (global or local)

Workflow

Step 1: Parse Arguments

• $ARGUMENTS contains one or more URLs and optional flags
• --existing <fileKey> means add to existing file instead of creating new
• If no URLs provided, ask the user

Step 2: Determine Capture Method

For each URL, decide the capture approach:

Is the page a local dev server (localhost, 127.0.0.1)?
  |
  +-- Yes: Does the page have Figma capture script embedded?
  |   |     (Check by fetching the page source and looking for
  |   |      "mcp.figma.com/mcp/html-to-design/capture.js")
  |   |
  |   +-- Yes → URL Fragment method (lightweight, no Playwright)
  |   +-- No  → Playwright injection method
  |
  +-- No (external site): → Playwright injection method

Step 3: Get Capture ID

Call mcp__figma__generate_figma_design to get a capture ID.

• First URL: use outputMode: "newFile" (unless --existing flag)
• Ask which team/plan to save to if multiple are available
• Subsequent URLs: use outputMode: "existingFile" with the fileKey from first capture

Step 4A: URL Fragment Method (if capture script is on page)

Open the URL with hash parameters:

open "<URL>#figmacapture=<CAPTURE_ID>&figmaendpoint=https%3A%2F%2Fmcp.figma.com%2Fmcp%2Fcapture%2F<CAPTURE_ID>%2Fsubmit&figmadelay=1000"

Wait 5-10 seconds, then poll capture status.

Step 4B: Playwright Injection Method

Run the bundled capture script:

node $HOME/.claude/skills/dev-figma-capture/scripts/figma-capture.mjs \
  --url <URL> \
  --capture-id <CAPTURE_ID>

The script:

1. Opens the page in headless Chromium
2. Strips CSP headers to allow injection
3. Injects Figma's capture.js
4. Triggers captureForDesign() and submits DOM to Figma

Options: --headless false (show browser), --delay <ms>, --selector <css>, --viewport-w <px>, --viewport-h <px>

Playwright dependency: The script requires playwright as a Node.js module. If not available in the current project, install it temporarily or check for a global install. The script imports playwright directly (not via npx).

Step 5: Poll and Confirm

Call mcp__figma__generate_figma_design with the captureId to check status. On success, it returns a claim URL. Open it for the user:

open "<claim-url>"

Multi-Page Capture

For multiple URLs:

1. Capture first URL as newFile → get fileKey
2. For each subsequent URL, call generate_figma_design with outputMode: "existingFile" and the fileKey to get a new capture ID
3. Capture each page with its own capture ID
4. Each page becomes a new page in the same Figma file

Troubleshooting

• Capture hangs: The captureForDesign() promise often doesn't resolve even when capture succeeds. The script handles this with a timeout. Check browser console logs for [Figma Capture] Success! confirmation.
• CSP errors on external sites: Playwright strips CSP headers automatically. If still failing, try --headless false to debug.
• Large pages: Pages over 10MB may fail. Try capturing specific sections with --selector.