figma-capture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Figma Capture

Figma 捕获

Capture the rendered DOM of a local page and put the result on the clipboard so the user can paste it into Figma.

Initial context received via slash: $ARGUMENTS

$ARGUMENTS

includes a URL or selector, use it. If it is empty, use the currently open browser page and

body

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

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

如果

$ARGUMENTS

包含URL或选择器，则使用该内容。如果为空，则使用当前打开的浏览器页面和

body

元素。

Core rule

核心规则

Use the official script:

text

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

Use clipboard mode by default:

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

Do not ask for or store a

figma_key

for clipboard capture. The script requires

captureId

only when

endpoint

is provided for file mode.

selector

already defaults to

"body"

, but pass it explicitly for readability unless the user provided another selector.

使用官方脚本：

text

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

默认使用剪贴板模式：

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

剪贴板捕获无需请求或存储

figma_key

。只有在为文件模式提供

endpoint

时，脚本才需要

captureId

。

selector

默认值为

"body"

，除非用户提供了其他选择器，否则为了可读性需显式传入该参数。

Project root

项目根目录

This skill usually does not write files. If the user asks to add a capture button or helper to a project, all paths are relative to that project root.

If invoked from inside the project, use the current repo root.
If invoked from a sibling repo, confirm the project root before editing.
Keep reusable capture helpers project-local; do not hardcode user-specific absolute paths or Figma file keys.

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

如果从项目内部调用，使用当前仓库根目录。
如果从同级仓库调用，在编辑前确认项目根目录。
可复用的捕获辅助工具需保持项目本地化；不要硬编码用户特定的绝对路径或Figma文件密钥。

Prompting

提示规则

Follow the project-wide convention in

CLAUDE.md

AGENTS.md

("Skill Prompting Conventions"). Use the harness's structured-question tool only for discrete choices that change the implementation.

Decision point	Why structured	Suggested options
Capture target when ambiguous	Affects what enters the clipboard	current page · provided URL · provided selector
Add persistent project UI	Writes app code	one-off console capture · dev-only button

Free-form prompts:

URL to open.
CSS selector when the user wants a narrower capture than
```
body
```
.
Project root when the active working directory is not the target project.

No-pause mode: default to current page,

body

, and one-off clipboard capture.

遵循

CLAUDE.md

AGENTS.md

中的项目范围约定（"Skill Prompting Conventions"）。仅当存在会改变实现方式的离散选择时，才使用工具的结构化问题功能。

决策点	为何采用结构化方式	建议选项
捕获目标不明确时	影响存入剪贴板的内容	当前页面 · 提供的URL · 提供的选择器
添加持久化项目UI	需要写入应用代码	一次性控制台捕获 · 仅开发者可用的按钮

自由格式提示：

要打开的URL。
当用户希望捕获范围比
```
body
```
更窄时，提供CSS选择器。
当当前工作目录不是目标项目时，提供项目根目录。

无暂停模式：默认使用当前页面、

body

元素和一次性剪贴板捕获。

One-off browser capture

一次性浏览器捕获

Use this when the user wants the current page copied now.

Open or focus the target page in the browser.

Inject

capture.js

window.figma?.captureForDesign

is not already present.

Call

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

Tell the user to paste in Figma.

Browser-console snippet:

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",
})

If the clipboard write is blocked, rerun the capture from a direct user gesture such as a button click. Some browsers require clipboard writes to happen close to the click event.

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

在浏览器中打开或聚焦目标页面。

如果

window.figma?.captureForDesign

尚未存在，则注入

capture.js

。

调用

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

。

告知用户在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",
})

如果剪贴板写入被阻止，请通过直接用户操作（如按钮点击）重新运行捕获。部分浏览器要求剪贴板写入操作必须在点击事件附近执行。

Dev-only capture button

仅开发者可用的捕获按钮

Use this when the user wants the app to expose repeatable capture during local design iteration.

Implementation pattern:

Render only in local/dev builds.
Preload
```
capture.js
```
on mount to avoid losing clipboard user activation during the click.

On click, call

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

Place the control away from product UI/FABs; bottom-left is a good default.
Do not add env vars,
```
localStorage
```
,
```
figma_key
```
, or hash params for clipboard mode.

Minimal React shape:

tsx

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",
  })
}

For TypeScript, add a small local

Window

declaration rather than casting:

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

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

实现模式：

仅在本地/开发构建中渲染。
在组件挂载时预加载
```
capture.js
```
，避免在点击期间丢失剪贴板用户激活状态。

点击时调用

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

。

将控件放置在远离产品UI/FAB的位置；默认放在左下角是不错的选择。
剪贴板模式下无需添加环境变量、
```
localStorage
```
、
```
figma_key
```
或哈希参数。

极简React结构：

tsx

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>
    }
  }
}

Hash flow and file mode

Hash流程与文件模式

Avoid the hash flow for normal local clipboard capture:

text

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

Use it only when an existing integration depends on automatic capture after page load.

Use file mode only when the user explicitly wants the capture sent to a Figma endpoint. In file mode,

endpoint

and

captureId

are required by the script; that is a different workflow from clipboard paste.

常规本地剪贴板捕获应避免使用Hash流程：

text

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

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

仅当用户明确希望将捕获内容发送到Figma端点时，才使用文件模式。在文件模式下，脚本需要

endpoint

和

captureId

；这与剪贴板粘贴是不同的工作流程。

Verification

验证步骤

Confirm the browser page has finished rendering before capture.
Paste into Figma and inspect whether the visible page content arrived.
If content is missing, retry with
```
delayMs: 500
```
or a narrower selector that excludes overlays.
If clipboard permissions fail, move the call into a direct click handler or grant clipboard permissions in the browser automation context.

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