figma-use-slides

use_figma — スライド向け Figma Plugin API スキル

このスキルには、use_figma MCP ツール向けのスライド固有のコンテキストが含まれています。figma-use スキルでは、MCP を介した Plugin API の実行に関する基本的なコンテキストに加え、ここでは説明していない、より高度なユースケース向けの Figma Plugin API 全般について説明しています。

スライド操作で use_figma を呼び出す際は、カンマ区切りの skillNames パラメーターに必ず figma-use-slides を含めてください。このスキルが MCP リソース経由で読み込まれた場合は、名前の先頭に resource: を付ける必要があります（例：resource:figma-use-slides）。 これはスキルの使用状況を追跡するためのログ用パラメーターであり、実行には影響しません。

スライドデッキの作成方法を選ぶ

環境に generate_deck ツールも用意されている場合は、デッキのリクエストごとにどちらか一方の方法を選んでください。同じデッキに対して両方を呼び出さないでください。

使い分け

use_figma + このスキル（デフォルト）： 新しいデッキの作成、既存デッキの編集、ブランドに合わせたデザイン、参照ファイルのスタイル適用、反復的な調整、スピーカーノート、レイアウト・色・タイポグラフィの完全なクリエイティブコントロールなど、あらゆるスライドタスクに対応します。ほとんどのリクエストでは、こちらを使用してください。

generate_deck： 事前構築された厳選テンプレートを使って、1 回の呼び出しでデッキ全体を生成します。カスタムデザイン、ブランドへの適合、参照ファイルのスタイル適用が不要な、手早くシンプルなデッキに便利です。カスタムテンプレートは使用できず、デザインの方向性を決めるために他の Figma ファイルを参照することもできません。また、会話を通じた反復編集や追加の変更にも対応していません。

迷った場合は、デフォルトとして use_figma + このスキルを選んでください。generate_deck で可能なことをすべてカバーしており、さらに多くのことができます。

どちらかを選び、最後までその方法を使う

デッキの作成方法を選んだら、その方法でリクエスト全体を完了してください。generate_deck でデッキを生成したうえで、さらに use_figma でファイルを作成したり内容を追加したりしないでください。成果物が重複して互いに矛盾し、ユーザーを混乱させることになります。

重要なルール（Slides 固有）

1. 新しく作成した Slides ファイルには、デフォルトでライトテーマが設定されます。 create_new_file で Slides ファイルを作成すると、デフォルトのライトテーマが自動的に初期化されます。このテーマは構造上の土台です。作成するデッキのデザイン方針に合わせて、テーマのカラー変数とテキストスタイルを上書きしてください。デフォルトのライトテーマのトークンに依存したり、影響を受けたりしないでください。
2. すべてのノードを、ネストのすべての階層で、x／y を設定する前に必ず appendChild してください。 新しく作成したノードは、スライドのコンテキスト内の絶対座標 (240, 240)（スライドグリッドの GRID_PADDING）に、暗黙的に自動で親ノードが設定されます。appendChild の前に x／y を書き込むと、その値はこの隠れた原点を基準に保存されます。その後、本来の親ノードに追加すると、ノードは (意図した座標 − 240, 意図した座標 − 240) に配置されます。このバグは断続的に発生します。同じスクリプト内でも問題が起きないフレームがあるため、テストが正常に動作したからといって安全とは限りません。**見分け方：**ノードが設定した位置から (−240, −240) ずれていたら、コードで最終的な appendChild より前に x／y を設定しています。240 を加えて補正しようとしないでください。再試行時にさらに悪い結果になります。設定する順序を修正してください。順序を間違えようがないヘルパーパターンについては、slide-gotchas.md を参照してください。
3. SLIDE_GRID と SLIDE_ROW は不透明なノードです。 これらの .fills、.effects、レイアウトプロパティにはアクセスしないでください。BaseFrameMixin を拡張するのは、SLIDE ノード（type 'SLIDE'）のみです。例外：SLIDE_ROW.name は設定できます。プラグインはこの方法でスライドのセクション名を変更します（例：slideRow.name = "Intro"）。slide-lifecycle.md を参照してください。
4. Slides ファイルでは get_metadata は機能しません。 検証には use_figma の読み取り専用スクリプトを使用してください。作成したノードの位置を closePlugin() の出力に含め、バウンディングボックスが重なっていないことを確認してください。
5. Slides では figma.createPage() を呼び出さないでください。 TypeError: figma.createPage no such property 'createPage' on the figma global object が発生します。createPage() は Design ファイル専用の API です（figma.com/design/...）。Slides の URL は figma.com/slides/... です。代わりにスライドグリッド（SLIDE_GRID／SLIDE_ROW／SLIDE）を使ってデッキの構造を整理してください。slide-lifecycle.md と slide-grid.md を参照してください。
6. 既存のスライドを削除して作り直さないでください。 デッキの改善、再デザイン、スタイル変更を依頼された場合は、既存のスライドをそのまま編集してください。スライドを削除できるのは、ユーザーから「最初からやり直す」または「一から作り直す」と明示的に依頼された場合のみです。

デザインの考え方

すべてのタスクで、同じ深さのデザイン検討が必要なわけではありません。作業を始める前に、どの段階に当てはまるかを見極めてください。

• コンテンツ／プロパティの編集 — テキストの変更、色の差し替え、数値の更新、配置の修正、要素のサイズ変更などです。デザイン検討は不要です。変更を加え、既存のデザインに合わせてください。
• 構造の追加 — スライドの追加、セクションのレイアウト変更、デッキのカラーパレットの変更、新しい視覚要素の導入などです。「改善」「再デザイン」「スタイル変更」の依頼もこれに含まれます。これらは既存のデッキへの編集であり、新しいデッキの作成ではありません。デザイン検討は必要ですが、継承モードで行います。既存のデッキをデザイン言語として、調査し、配色、書体、空間の使い方、モチーフを合わせてください。デッキの個性を一新するのではなく、既存の個性を発展させてください。
• 新しいデッキの作成 — デッキをゼロから作成するか、空のファイルから作成します。以下に記載する完全なデザイン検討が必要です。

既存のデッキに構造を追加する場合：下記の検査スクリプトを実行し、変更前にスクリーンショットを撮ってください。「どんな色使いにするか」「どんな文字の扱いにするか」の答えはすでにファイルにあります。内容を読み取り、一貫性を保つことが役割です。slide-design.md に記載されているデザイン原則は、選ぶものではなく、合わせるものを示しています。

新しいデッキのデザインプロセス

新しいデッキの Plugin API コードを書く前に、まずどんな「印象」にしたいかを決めてください。Figma ユーザーはビジュアルに対する期待が高いため、汎用テンプレート生成ツールで作ったようなデッキは、望ましくない形で目立ってしまいます。

1. ブリーフを読みます。 デッキは何を、誰に伝えるのでしょうか？ 投資家向けのピッチ、チームの振り返り、製品発表、技術的な詳細解説では、それぞれ異なるビジュアル表現が求められます。デザインはコンテンツと切り離せないものにしてください。
2. デザイン言語を確認します。 何かを考案する前に、ユーザーがすでに提供しているものを確認してください。プロンプト内のブランドガイドライン――カラーパレット、タイポグラフィの仕様、ロゴのルール、トーンを示す言葉――は、すでに決定済みのデザイン方針です。参考用 Figma ファイルへのリンクがある場合は、ざっと見るのではなく、デザイン言語をよく調べてください。ユーザーからの入力が具体的であるほど、自分で考案する範囲は狭めるべきです。ユーザーが参考資料を提供した場合、あなたの役割は「デザイナー」から「解釈者」へと変わります。デザイン言語を読み取り、新しいコンテンツに忠実に適用してください。
3. 残された部分で方針を定めます。 ユーザーがブランドシステム一式を提供している場合、創造性を発揮できるのはレイアウト、テンポ、構成であり、色や書体ではありません。参考としてスライドを1枚だけ提供している場合は、より自由度がありますが、その特徴を反映するようにしてください。何も提供されていない場合は、すべての判断をあなたが担います。配色、書体の扱い、空間の整理方法を選び、すべてのスライドで一貫させてください。明確な視点のあるデッキは（控えめな視点であっても）、あらゆる判断で無難さを優先するデッキより、常に見栄えがします。「方針を定める」範囲は、ユーザーから提供された情報が多いほど狭くなります。
4. 特徴を持たせます。 優れたデッキには、文脈から切り離して見てもそれとわかる要素が少なくとも1つあります。個性的なパレット、意外性のあるレイアウトのリズム、繰り返し使われる形状の表現などです。ブランドガイドラインに沿って制作する場合、その特徴はブランドのデザイン言語から導き出してください。異質な要素を加えるのではなく、すでにあるものを際立たせます。ゼロからデザインする場合は、制作を始める前に、その特徴を決めてください。

参考ファイルを読む

ユーザーから参考用の Figma ファイルへのリンクが提供されたら、デザインを始める前に内容を確認してください。抽出する情報は、ファイルの種類によって異なります。

• スライドファイル：get_metadata はスライドファイルでは機能しません。get_screenshot を使って各スライドをキャプチャし、ビジュアルの参考にしてください。また、参考ファイルの fileKey を指定して use_figma を使い、テーマ変数、カラーパレット、フォントの選択、レイアウトのパターンを抽出する読み取り専用スクリプトを実行してください。
• デザインファイル：get_design_context では、色、タイポグラフィ、レイアウト構造など、包括的なデザインデータを取得できます。get_screenshot ではビジュアルの参考情報を得られます。両方を使ってください。

参考ファイルで確認するポイントは、カラーパレット（どの色相が主役か、アクセントカラーは何か、背景に暗色と明色をどう使っているか）、書体の選択（ファミリー、ウェイト、階層の付け方）、空間の使い方（コンテンツの基準位置、余白の量、要素が端からはみ出しているかどうか）、繰り返し使われるモチーフ（形状、線の表現、装飾要素）です。これらの判断は参考ファイルから引き継ぐもので、それ以外は自由に決められます。

参考にどの程度忠実に従うかは、ユーザーの依頼内容によって異なります。「これと同じような見た目にして」は、新しいコンテンツでデザイン言語を再現するという意味です。「これをインスピレーションにして」は、雰囲気を取り入れつつ、独自の表現にするという意味です。「こちらがブランド資料です」は、ブランドシステムを抽出し、一貫して適用するという意味です。判断に迷った場合は、参考に近づけてください。ユーザーが独自性を求めるのは簡単ですが、ブランドと相反する独自の判断を取り消すよう求めるのは簡単ではありません。

色、書体、レイアウトパターン、構成、避けるべきことについて詳しくは、slide-design.md を読み込んでください。参考ファイルやブランドガイドラインがある場合、slide-design.md の原則は、ユーザーが決めていない部分に適用するデフォルトとして扱い、ユーザーが決めた部分を上書きするものとして扱わないでください。

デッキ作成のワークフロー

5 枚以上の新しいデッキを作成するときは、この 2 段階のワークフローを使ってください。これは、デッキ作成に特化したものであり、figma-use のセクション 6 にある一般的な段階的ワークフローに置き換わるものです。原則は引き続き適用されますが、進め方が変わります。

フェーズ 1 — デザインと計画

上記のデザイン検討プロセス（概要を読む、デザイン言語を確認する、方針を決める、特徴を持たせる）を完了したら、use_figma のコードを書く前に、デッキ全体を対象としたスライド計画を作成してください。

1. スライドごとの計画。 各スライドについて、目的と内容、空間的な表現で記述したレイアウト方針（例：「タイトルを左上に配置し、仕様カードを右側の 3 分の 1 に広げ、装飾用の円を右上端からはみ出させる」）、背景の処理（暗色／明色／グラデーション）を記載してください。計画段階でピクセル座標を計算してはいけません。空間的な表現でレイアウトを記述してください。座標の計算はコード生成時に行います。
2. 共通定数。 使用するフォントファミリーとスタイル、名前付きの役割（primary、accent、bgDark、surface、textPrimary、textMuted など）を持つカラーパレット、繰り返し使うモチーフやシグネチャー要素を宣言してください。
3. レイアウトの多様性の確認。 スライド計画を順番に読み返してください。レイアウトの説明が「2 カラム、2 カラム、グリッド、2 カラム」のように繰り返しに感じられる場合は、作成前に順序を入れ替えてください。多様性を持たせるのに、これが最も手間のかからないタイミングです。アンチパターンについては slide-design.md を参照してください。
4. コードのプレアンブル。 すべてのビルドスクリプトの冒頭に貼り付ける、再利用可能なプレアンブルを記述してください。const C = { ... } のカラーパレットオブジェクト、Promise.all([...]) によるフォント読み込みブロック、および slide-gotchas.md にある addFrame／addText／addRect ヘルパーを含めます。

フェーズ 2 — 構築

計画を大きなバッチに分けて実行します。目標は、スクリプトごとの要素数を減らすことではなく、検討してから構築するサイクルの回数を最小限にすることです。

• 1 回の use_figma 呼び出しにつき 3～5 枚のスライド。（例：一連の商品機能紹介スライドのように）構造が似ているスライドは、同じバッチにまとめられます。各スライドは独立したサブツリーです。スライド間の依存関係はないため、大きなバッチでも問題ありません。
• バッチ間で再計画しないでください。 デザインはフェーズ 1 で決定済みです。バッチが成功して検証に合格したら、すぐに次のバッチに進んでください。バッチが失敗した場合や、アプローチの変更が必要な視覚的な問題が生じた場合に限り、再計画してください。
• すべての構築スクリプトの冒頭にコードの前置きを貼り付けてください（色、フォント、ヘルパー関数）。フェーズ 1 からそのままコピーし、再導出しないでください。
• バッチ検証スクリプト（slide-gotchas.md 参照）を使って、すべてのバッチを検証してください。このスクリプトは、要素の重なり、テキストの切り取り、範囲外のノードを約 3 秒で確認します。チェックに合格した場合は、スクリーンショットを撮らずに次へ進んでください。失敗した場合は、該当するスライドのスクリーンショットを撮り、修正してから続行してください。
• スクリーンショットはチェックポイントでのみ撮影してください。最初のバッチの後（ビジュアルシステム：色、タイポグラフィ、デザイン方針を検証）と、最後のバッチの後（全体的な品質を確認）に撮影します。各チェックポイントでは、別途 get_screenshot を呼び出すのではなく、await slide.screenshot() をインラインで使って代表的なスライドを 1～2 枚撮影してください。
• すべての構築スクリプトから、作成したすべてのノード ID を返してください（いつもどおり）。

セクション

セクションとは、スライドグリッド内の横一列です。各行が 1 つのセクションになります。セクション名は、エディター（行の横）とプレゼンタービュー（登壇者がグループ間を移動する際）に表示されます。セクションはデッキを編集する人のための整理用です。区切りをどこに置くかはユーザーが決めることであり、あなたが決めることではありません。

デッキの整理を依頼された場合

「このデッキを整理して」は、グループ分け、並べ替え、重複の削除、再構成など、意味が曖昧です。AskUserQuestion を使う前に、デッキを確認してください。

既定では、質問せずに提案してください。 多くのデッキには手がかりがあります。タイトルの前後配置、番号付きのユースケース、繰り返される Before / After のペア、「Then X enters the chat」のような転換スライド、Thank you などです。手がかりがある場合は、セクション分けを選び、確認メッセージを 1 つ送って提示してください。提案に含める範囲が限定された選択（Use Cases を 1 行にするか 3 行にするか、転換スライドをどこに置くかなど）は、後から変更できます。どれかを選び、先へ進んでください。

フォールバック：手がかりがない場合は質問してください。 スライドの順序がばらばらで、軸となる流れもない場合は、どの範囲をまとめるか、何という名前にするかを尋ねてください。内容を確認せず、代わりに 3 等分しないでください。

命名と範囲

名前は短く（1～3 語）、具体的で（Show & tell より Demo）、デッキ内で一貫性のあるものにしてください。セクション数は 2～5 個が一般的です。長いデッキや、同じ構成を繰り返すデッキでは、それ以上でもかまいません。セクション名はスライドのタイトルではありません。内容を説明するのではなく、グループを見つけやすくするためのものです。

セクション名の変更

getSlideGrid() は SlideNode[][] を返します。内側の配列はスライドの単純な JS 配列であり、SLIDE_ROW ノードではありません。これらの配列に .name を設定しても、何も起こりません。セクション名を変更するには、ノードツリーをたどり、実際の SLIDE_ROW に .name を設定してください。

const slideGrid = figma.currentPage.children.find(c => c.type === "SLIDE_GRID");
slideGrid.children[0].name = "Intro";

スピーカーノート

スピーカーノートは、各スライドに付属するプレゼンター専用のメモです。プレゼンタービューに表示され（登壇者にのみ見え、聴衆には表示されません）、ライブプレゼンテーション中の台本、進行メモ、要点の参照として役立ちます。

スピーカーノートを作成するタイミング

• 依頼された場合：ユーザーからスピーカーノート、プレゼンターノート、話すポイント、またはスライド資料用の台本を求められた場合は、内容のあるすべてのスライドにノートを作成します（セクション区切りや装飾のみのスライドは、話す内容がない限り省略します）。
• プレゼンですぐに使えるスライド資料：ライブでのプレゼンにそのまま使えるスライド資料を明示的に求められた場合、スピーカーノートが役立ちます。発表者が、スライドには表示されない進行、つなぎ、背景を把握する助けになる場合は追加します。
• 情報量が少ない、またはビジュアル中心のスライド：チャート、画像、比喩、または印象的な問いを中心に構成されたスライドでは、発表者が何を話すべきかを説明するノートが役立ちます。ビジュアルの文脈が重要な場合は、スクリーンショットや node.screenshot() を使って、画像中心、チャート中心、またはビジュアル情報の少ないスライドを確認します。ただし、デフォルトですべてのスライドをスクリーンショットにしないでください。画像はコンテキストの予算を消費します。
• 頼まれていないノートは追加しない：通常のスライド編集、レイアウト作業、既存のスライド資料の更新では、ユーザーから求められない限りスピーカーノートを入力しないでください。ノートを追加するとプレゼンの流れが変わり、スライド資料の所有者を驚かせる可能性があります。

良いスピーカーノートとは

スピーカーノートは聴衆ではなく、発表者のためのものです。信頼できる同僚が身を寄せて「こう話すといいですよ」と耳打ちしてくれるような内容にします。良いノートの特徴は次のとおりです。

• スライドを補足し、繰り返さない：スライドに「売上が40％増加」とある場合、ノートで「売上が40％増加しました」と繰り返す必要はありません。なぜ増加したのか、聴衆に何を持ち帰ってほしいのか、またはよく出る質問などを書きます。
• 簡潔で、すばやく確認できる：話している途中で発表者がノートに目をやったとき、すぐに自分の位置を見つけられる必要があります。長い段落ではなく、短い箇条書きを使います。各項目には一つの要点だけを含めます。
• つなぎを含める：優れたノートは、スライド間の移り方を発表者に伝えます。「拍手が落ち着いたら……」や「前のポイントを発展させた内容です。40％という数字に触れてください」などです。
• スライドに載せられない背景を補う：データソース（「出典：社内のQ4 FY25指標、未公開」）、注意事項（「CFOが同席している場合は、このスライドを飛ばしてください」）、時間の目安（「ここが折り返し地点です。約10分経過しているはずです」）、想定される質問（「利益率について聞かれるはずです。付録の14枚目を参照してください」）などです。
• プレゼンの雰囲気に合わせる：投資家向けピッチのノートは正確で、リハーサルされたものにします。チームの振り返りのノートはカジュアルで柔軟にします。基調講演のノートには、舞台上の動作指示を含めてもかまいません。文脈に合わせてトーンを調整します。

スピーカーノートで避けること

• 台本の全文：文字ばかりのノートは一字一句そのまま読むことを促し、プレゼンの質を大きく損ないます。ユーザーから明示的に台本を求められた場合は作成しますが、デフォルトでは箇条書きにします。
• 聴衆向けの書式設定：ノートは聴衆には見えません。発表者以外が読みやすくなるように最適化しないでください。
• スライドとの重複：連絡先情報を添えた「ありがとうございます」のように、スライドだけで内容が明確な場合はノートは不要です。スライドのノートを空のままにしても問題ありません。

書式

slide.speakerNotes には Markdown 文字列を指定できます。基本の構成には箇条書きを使います。発表者が見落としてはいけない重要な語句の強調には、太字が便利です。サポート対象（リスト、太字、斜体、取り消し線）および非サポート（見出し、コードブロック、インラインコード、リンク）の Markdown の一覧については、slide-properties.md を参照してください。

スライドファイルの確認

スライドファイル専用の読み取りツールはまだありません。確認には、読み取り専用スクリプトで use_figma を使用し、視覚的なコンテキストの把握には get_screenshot ／ await node.screenshot() を使用してください。

• 作成する前に確認してください。 何かを作成する前に、読み取り専用の use_figma を実行して、既存の内容（スライド、テキスト、コンポーネント、命名規則など）を確認してください。ここでは figma-use のセクション 6「まず確認する」のパターンが適用されます。
• get_metadata はスライドファイルでは動作しません — 対応しているのは figma（デザイン）エディタータイプのみです。
• console.log() の出力は返されません — 戻ってくるのは return の値だけです。必要なデータは必ず return してください。
• 視覚的なコンテキストの把握には get_screenshot を使用してください — スクリーンショットを取得するには、有効な nodeId を渡します。また、use_figma スクリプト内で await node.screenshot() を直接使用することもできます。

確認用クイックスクリプト

デッキ内のすべてのスライドを一覧表示する：

const grid = figma.getSlideGrid();
return grid.map((row, rowIdx) =>
  row.map((slide, colIdx) => ({
    id: slide.id,
    name: slide.name,
    row: rowIdx,
    col: colIdx,
    isSkipped: slide.isSkippedSlide,
    speakerNotes: slide.speakerNotes,
  }))
);

特定のスライドのテキストコンテンツを取得する：

const slide = figma.getNodeById("TARGET_SLIDE_ID");
// findAllWithCriteria uses an indexed type lookup — much faster than
// findAll(n => n.type === 'TEXT') on slides with many shapes/images.
const textNodes = slide.findAllWithCriteria({ types: ["TEXT"] });
const fontsToLoad = new Set();
for (const t of textNodes) {
  if (t.fontName !== figma.mixed) {
    fontsToLoad.add(JSON.stringify(t.fontName));
  } else {
    const segments = t.getStyledTextSegments(["fontName"]);
    for (const seg of segments) fontsToLoad.add(JSON.stringify(seg.fontName));
  }
}
for (const f of fontsToLoad) {
  await figma.loadFontAsync(JSON.parse(f));
}
return textNodes.map(t => ({
  id: t.id,
  name: t.name,
  characters: t.characters,
  x: t.x,
  y: t.y,
  width: t.width,
  height: t.height,
}));

参考ドキュメント

タスクに必要な参考資料のみを読み込んでください。

• slide-gotchas — スライド固有の注意点（座標オフセット、不透明なノードタイプ、検証の回避策）
• slide-lifecycle — スライドとスライド行の作成、複製、削除、並べ替え
• slide-grid — スライドグリッドレイアウト（getSlideGrid、setSlideGrid）の操作
• slide-content — スライド内のコンテンツ（テキスト、図形、自動レイアウト）の作成 — SlideNode は BaseFrameMixin を拡張します
• slide-properties — スライド固有のプロパティ（speakerNotes、isSkippedSlide、focusedSlide、focusedNode、slideThemeId、InteractiveSlideElementNode）
• slide-design — 視覚的に魅力があり、多様性のあるデッキを作成するためのデザイン原則（色彩戦略、タイポグラフィ、レイアウトの多様性、空間構成、アンチパターン）