Aimedialearnner/figma-book-page-capture-skill

Figma Book Page Capture

Core Workflow

Use this skill for page-by-page web documents where each page is a DOM container such as .book-page.

1. Load figma:figma-use and figma:figma-generate-design before Figma writes.
2. Confirm the target URL is the published/live page, not an editor page.
3. Use Playwright or the Node-backed Playwright runtime to open the URL.
4. Count page containers with the requested selector, usually .book-page.
5. Confirm each page size, normally 1190 × 842.
6. Generate one Figma capture ID per page with generate_figma_design({ fileKey }).
7. For each page, run the capture script in Playwright:
   • Open the published URL.
   • Wait for the page selector.
   • Clone only the target page into a clean document.body.
   • Set body size and overflow so navigation, floating buttons, controls, and other pages are excluded.
   • Inject https://mcp.figma.com/mcp/html-to-design/capture.js.
   • Call window.figma.captureForDesign({ captureId, endpoint, selector }).
8. Poll generate_figma_design({ fileKey, captureId }) until completed.
9. Record returned node IDs in page order.
10. After all pages are imported, call use_figma to rename, resize, and arrange all frames.

Do not capture the whole webpage when many .book-page nodes exist. It can timeout or include UI chrome. Always isolate one page DOM per capture.

Required Inputs

• url: published webpage URL
• fileKey: existing Figma design file key
• selector: page container selector, default .book-page
• width: frame width, default 1190
• height: frame height, default 842
• gap: spacing between frames, default 80
• batchSize: reporting cadence, default 10

Script Template

Use scripts/capture-figma-page.mjs as the starting point. Copy or patch it into the workspace when needed, then run it with:

CAPTURE_ID=<id> PAGE_INDEX=<1-based> TARGET_URL=<url> PAGE_SELECTOR=.book-page WIDTH=1190 HEIGHT=842 /path/to/node capture-figma-page.mjs

The script submits one isolated page. Figma completion is confirmed by polling generate_figma_design with the same capture ID.

Figma Cleanup Script Pattern

After capture, use use_figma with the ordered node IDs:

const nodeIds = [/* Page 01..N capture node IDs */];
const W = 1190, H = 842, GAP = 80, COLS = 4;
const nodes = [];
for (let i = 0; i < nodeIds.length; i++) {
  const node = await figma.getNodeByIdAsync(nodeIds[i]);
  if (!node) continue;
  node.name = `Page ${String(i + 1).padStart(2, "0")}`;
  if ("resize" in node) node.resize(W, H);
  node.x = (i % COLS) * (W + GAP);
  node.y = Math.floor(i / COLS) * (H + GAP);
  nodes.push(node.id);
}
return { mutatedNodeIds: nodes, count: nodes.length };

Use skillNames: "figma-use,figma-generate-design".

Reporting

Report progress only at the requested cadence. For a 48-page book and batch size 10, report at:

• 10/48
• 20/48
• 30/48
• 40/48
• final 48/48

Include node IDs per batch when useful. At final, include the Figma file link, imported page count, naming/layout status, and any known conversion caveats.

Caveats

• Code to canvas returns raw editable frames/layers, not design-system components.
• Text usually becomes editable Text layers, but font substitution can occur.
• Images should remain image fills/layers, but remote loading or crop differences can occur.
• Complex gradients, masks, shadows, blend modes, clipping, and SVGs may need manual inspection.
• If a capture ID has completed or been consumed, do not reuse it; generate a new one.
• If browser-side captureForDesign never resolves but Figma polling completes, trust the Figma polling result.