figma-capture

Figma Capture

捕获本地页面渲染后的 DOM，并将结果放入剪贴板，供用户粘贴到 Figma。

通过斜杠命令接收的初始上下文：$ARGUMENTS

如果 $ARGUMENTS 包含 URL 或选择器，请使用它。如果为空，请使用当前打开的浏览器页面和 body。

核心规则

使用官方脚本：

https://mcp.figma.com/mcp/html-to-design/capture.js

默认使用剪贴板模式：

await window.figma.captureForDesign({
  delayMs: 250,
  selector: "body",
})

剪贴板捕获时，不要索要或存储 figma_key。只有在文件模式下提供 endpoint 时，脚本才需要 captureId。selector 已默认为 "body"，但为清晰起见，除非用户提供了其他选择器，否则请显式传入该值。

项目根目录

此技能通常不会写入文件。如果用户要求向项目添加捕获按钮或辅助工具，所有路径均相对于该项目根目录。

• 如果从项目内部调用，请使用当前仓库根目录。
• 如果从同级仓库调用，请在编辑前确认项目根目录。
• 可复用的捕获辅助工具应保留在项目内；不要硬编码用户专属的绝对路径或 Figma 文件键。

提示

遵循项目级约定 CLAUDE.md / AGENTS.md（“技能提示约定”）。仅在需要做出会改变实现方式的明确选择时，才使用工具提供的结构化提问。

决策点	使用结构化提问的原因	建议选项
捕获目标不明确时	会影响剪贴板中包含的内容	当前页面 · 提供的 URL · 提供的选择器
添加持久化的项目 UI	会写入应用代码	一次性控制台捕获 · 仅开发环境按钮

自由输入提示：

• 要打开的 URL。
• 用户希望将捕获范围缩小到 body 以内时使用的 CSS 选择器。
• 当前工作目录不是目标项目时的项目根目录。

无暂停模式：默认使用当前页面、body 和一次性剪贴板捕获。

一次性浏览器捕获

用户希望立即复制当前页面时使用此方式。

1. 在浏览器中打开或切换到目标页面。
2. 如果 window.figma?.captureForDesign 尚不存在，则注入 capture.js。
3. 调用 window.figma.captureForDesign({ selector, delayMs: 250 })。
4. 告知用户粘贴到 Figma。

浏览器控制台代码片段：

await new Promise((resolve, reject) => {
  if (window.figma?.captureForDesign) {
    resolve()
    return
  }

  const script = document.createElement("script")
  script.src = "https://mcp.figma.com/mcp/html-to-design/capture.js"
  script.onload = resolve
  script.onerror = () => reject(new Error("Failed to load Figma capture script"))
  document.head.appendChild(script)
})

await window.figma.captureForDesign({
  delayMs: 250,
  selector: "body",
})

如果剪贴板写入被阻止，请通过按钮点击等直接的用户操作重新执行捕获。某些浏览器要求剪贴板写入紧接着点击事件发生。

仅开发环境的捕获按钮

用户希望应用在本地设计迭代期间提供可重复使用的捕获功能时使用此方式。

实现方式：

1. 仅在本地/开发构建中渲染。
2. 在挂载时预加载 capture.js，避免点击时丢失剪贴板用户激活状态。
3. 点击时调用 window.figma.captureForDesign({ selector: "body", delayMs: 250 })。
4. 将控件放置在产品 UI/FAB 之外；左下角是不错的默认位置。
5. 剪贴板模式下，不要添加环境变量、localStorage、figma_key 或哈希参数。

最简 React 结构：

const FIGMA_CAPTURE_SCRIPT_ID = "figma-capture-script"
const FIGMA_CAPTURE_SCRIPT_SRC =
  "https://mcp.figma.com/mcp/html-to-design/capture.js"

async function loadFigmaCaptureScript() {
  if (window.figma?.captureForDesign) {
    return
  }

  const existingScript = document.getElementById(FIGMA_CAPTURE_SCRIPT_ID)
  if (existingScript) {
    await new Promise((resolve, reject) => {
      existingScript.addEventListener("load", resolve, { once: true })
      existingScript.addEventListener("error", reject, { once: true })
    })
    return
  }

  await new Promise((resolve, reject) => {
    const script = document.createElement("script")
    script.id = FIGMA_CAPTURE_SCRIPT_ID
    script.src = FIGMA_CAPTURE_SCRIPT_SRC
    script.onload = resolve
    script.onerror = () => reject(new Error("Failed to load Figma capture script"))
    document.head.appendChild(script)
  })
}

async function captureForFigma() {
  await loadFigmaCaptureScript()
  await window.figma?.captureForDesign?.({
    delayMs: 250,
    selector: "body",
  })
}

对于 TypeScript，请添加一个小型的本地 Window 声明，而不是进行类型转换：

declare global {
  interface Window {
    figma?: {
      captureForDesign?: (options: {
        delayMs?: number
        selector?: string
        verbose?: boolean
      }) => Promise<{ error?: string; success?: boolean } | void>
    }
  }
}

哈希流程和文件模式

对于常规的本地剪贴板捕获，请避免使用哈希流程：

#figmacapture=...&figmaselector=...

仅当现有集成依赖页面加载后自动捕获时才使用此流程。

只有用户明确要求将捕获结果发送到 Figma 端点时，才使用文件模式。在文件模式下，脚本要求提供 endpoint 和 captureId；这与粘贴到剪贴板的工作流程不同。

验证

• 确认浏览器页面已完成渲染后再捕获。
• 粘贴到 Figma，检查可见的页面内容是否已导入。
• 如果内容缺失，请使用 delayMs: 500 重试，或使用更精确且排除覆盖层的选择器。
• 如果剪贴板权限失败，请将调用放入直接的点击处理程序，或在浏览器自动化上下文中授予剪贴板权限。