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 を要求したり保存したりしないでください。スクリプトで captureId が必要になるのは、ファイルモードで endpoint を指定した場合のみです。selector のデフォルトはすでに "body" ですが、ユーザーが別のセレクターを指定していない限り、わかりやすさのため明示的に渡してください。

プロジェクトルート

このスキルは通常、ファイルを書き込みません。ユーザーがプロジェクトへのキャプチャボタンやヘルパーの追加を求めた場合、すべてのパスはそのプロジェクトルートからの相対パスです。

• プロジェクト内から呼び出された場合は、現在のリポジトリルートを使用します。
• 隣接するリポジトリから呼び出された場合は、編集前にプロジェクトルートを確認します。
• 再利用可能なキャプチャヘルパーはプロジェクト内に置き、ユーザー固有の絶対パスや Figma ファイルキーをハードコードしないでください。

プロンプト

プロジェクト全体の規約である CLAUDE.md / AGENTS.md（「Skill Prompting Conventions」）に従います。実装に影響する選択肢が明確に分かれている場合に限り、ハーネスの構造化質問ツールを使用します。

判断事項	構造化する理由	推奨する選択肢
あいまいな場合のキャプチャ対象	クリップボードに入る内容が変わるため	現在のページ · 指定された 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 にして再試行するか、オーバーレイを除外する、より対象を絞ったセレクターを使用します。
• クリップボードの権限で問題が発生した場合は、直接のクリックハンドラー内で呼び出すか、ブラウザー自動化コンテキストでクリップボードの権限を付与します。