🧩 デザインシステムからFigma画面を組み立てる - figma-generate-design

figma-generate-designは、コードや画面の説明をもとに、Figma上へページ、モーダル、ダイアログ、ドロワー、サイドバー、パネルなどを組み立てる公式エージェントスキルです。

重要なのは、四角形やテキストをハードコードして見た目だけを再現するスキルではないことです。Code Connect、既存画面、ライブラリ検索からコンポーネント、Variables、テキストスタイル、エフェクトスタイルを発見し、公開済みデザインシステムのインスタンスとして画面を作ります。

この記事では、現行の公式スキルを基準に、対象範囲、探索の優先順位、6段階の構築手順、Webアプリを取り込む並列ワークフロー、運用上の注意点を解説します。

Figma関連の3スキルは役割が異なります。再利用資産そのものを構築する流れはfigma-generate-library、Figmaからアプリケーションコードへ変換する逆方向はfigma-design-to-codeで扱っています。

これらのワークフローで扱うCanvas、Node、Component、Instance、Variables、Styles、Code Connectの概念関係は、Figmaの構造とデータモデルで説明しています。

この記事の全体像。以下、順に解説します。

figma-generate-designの役割

成果物は、複数セクションで構成されたFigma上のViewです。新規作成だけでなく、既存画面の一部更新にも使います。

figma-generate-designを使うときは、figma-useも必ず読み込みます。figma-useはPlugin APIの実行規約、figma-generate-libraryは再利用資産を構築するワークフローを担当します。

キャンバス操作はuse_figmaで行い、通常はskillNames: "figma-use,figma-generate-design"を指定します。両方をMCPリソースとして読み込んだ場合はskillNames: "resource:figma-use,resource:figma-generate-design"とします。この値は利用状況を追跡するログ用で、実行結果は変えません。

First Draftとは別の仕組み

Figma AIのFirst Draftは、自然言語から編集可能な初期デザインを生成するFigma製品内の機能です。一方、本稿のfigma-generate-designは、MCPクライアント上のAIエージェントへ作業手順を与えるスキルです。

両者を同一視すると、公式スキルが要求するコンポーネント探索、Variablesのバインド、セクション単位の検証を見落とします。

全体構造

画面生成は、ソースとFigmaのデザインシステムをAIエージェントが対応付ける処理です。

最低限、接続済みのFigma MCP Server、既存のfileKey、ソースコードまたは画面説明に加え、対象ファイルに公開済みデザインシステムがあるか、利用可能なチームライブラリへアクセスできることが必要です。対象ファイルがなければ、先に/figma-create-new-fileまたはcreate_new_fileで作成し、そのfileKeyを再利用します。

6段階の構築ワークフロー

1. 成果物を分解する

Figmaを操作する前に、コードと要件を読みます。

• Header、Hero、Content、Footerなどの主要セクション
• Button、Input、Card、Navigationなどの必要部品
• 実際に使われているフォントファミリー
• 画像、背景画像、アバター、外部アイコンの有無
• 新規作成か、既存画面の更新か

フォントを確認せずInterへ置き換えると、処理が成功しても見た目は一致しません。CSS変数、コンポーネント、フォント設定から製品の書体を先に特定します。

2. コンポーネント、Variables、Stylesを収集する

キャンバスを書き換える前に、各セクションで使う資産を表へまとめます。公式スキルには、探索順序を飛ばさないためのHard Gateがあります。

コンポーネントは次の順番で探します。

1. 必要な部品に対応するCode Connectファイル
2. 対象ファイルにある既存画面のInstance
3. 未解決の部品だけをsearch_design_systemで検索

Code Connectファイルでは、Figma URLからFile KeyとNode IDを取得します。URLのnode-id=609-35535は、Plugin APIでは609:35535へ変換します。ライブラリファイル上でKeyとNode Typeを解決し、COMPONENT_SETならimportComponentSetByKeyAsync()、単一のCOMPONENTならimportComponentByKeyAsync()で取り込みます。Keyだけを見て一律にComponent SetとしてimportするとPromiseがrejectされます。

search_design_systemを使う前にget_librariesで利用可能なライブラリを確認し、必要に応じてincludeLibraryKeysで検索範囲を絞ります。組織ライブラリはページングされます。libraries_available_to_add_next_offsetが非nullなら、その値を次回のget_librariesのoffsetへ渡します。

Variablesでは、ローカルと公開ライブラリの違いに注意が必要です。

ローカルVariablesが空でも、デザインシステムにVariablesがないとは限りません。色、余白、角丸をハードコードする前に、公開ライブラリ側も検索します。TypographyやShadowはincludeStylesで探し、Text StyleとEffect Styleとして適用します。

3. Wrapper Frameを最初に作る

セクションをページ直下に作り、後から別の呼び出しで親へ移動すると、appendChild()が意図どおりに動かず孤立したFrameを残すことがあります。先にView全体のWrapperを1回のuse_figmaで作り、IDを返します。

const wrapper = figma.createAutoLayout("VERTICAL");
wrapper.name = "Settings";
wrapper.resize(1440, 100);
wrapper.layoutSizingHorizontal = "FIXED";
return { success: true, wrapperId: wrapper.id };

ページなら1440px、モーダルなら640pxなど、幅はソースの実寸に合わせます。既存コンテンツと重ならない位置へ配置し、以降の呼び出しでは返却したIDを使います。

4. セクションごとに組み立てる

Header、Form、Action Barなどを1セクションずつ、別々のuse_figma呼び出しでWrapper内へ作ります。一度に画面全体を生成しません。

手作りするのはWrapper、セクションコンテナ、行や列などのレイアウトです。Button、Card、InputなどはデザインシステムからInstanceとして取り込みます。色、余白、角丸はVariablesをバインドし、文字とShadowにはStyleを適用します。

Instanceの表示文字列は、探索時に確認したTEXTプロパティをsetProperties()で上書きします。子Text Nodeのcharactersを直接変更するより、Componentとの接続を維持しやすい方法です。

繰り返し要素がデザインシステムに存在しない場合も、同じFrameを複製しません。ローカルComponentを1つ作り、そのInstanceを配置します。Component化は後工程ではなく、初回構築の完了条件です。

アイコンは、既存のIcon ComponentがあればInstanceを使います。なければコードベースのSVGをcreateNodeFromSvg()で取り込みます。線や四角形を回転して手描きすると形が崩れるため避けます。SVGにはviewBoxと明示的なwidth、heightを含め、currentColorは取り込み後にVariableへバインドします。

5. セクションと画面全体を検証する

各セクションの作成直後にget_screenshotで確認します。最後にWrapper全体も確認します。

• 文字の上下が切れていないか
• 要素が重なっていないか
• PlaceholderのTitleやButtonが残っていないか
• Component Variantが正しいか
• 製品のフォントファミリーを使っているか
• 画像が空白になっていないか

全体を縮小したスクリーンショットだけでは、文字切れや誤ったVariantを見落とします。個別セクションのNode IDでも撮影し、問題のある箇所だけをuse_figmaで修正します。

6. 既存Viewは差分だけ更新する

更新タスクでは、get_metadataで既存構造を確認し、変更が必要なセクションだけを特定します。Componentの差し替え、TEXTやVariantプロパティの更新、廃止セクションの削除、新規セクションの追加を小さな呼び出しで実行します。

エラーが起きた場合は、同じスクリプトを即座に再試行しません。メッセージと現在のメタデータ、スクリーンショットを確認し、失敗したセクションのスクリプトを修正します。use_figmaの失敗したスクリプトはatomicに扱われるため、成功済みの前セクションは維持されます。

Webアプリでは2つの生成経路を併用する

ブラウザで表示できるWebアプリでは、同じfileKeyへ2つの生成を並行して行います。

generate_figma_designは実行中の画面を高い視覚精度で取り込みます。一方、use_figma側はデザインシステムへ接続されたComponent Instanceを作ります。前者を見本に後者を調整し、確認後は参照用Captureを削除します。

Webアプリに画像が含まれる場合、この並列経路は必須です。一般のFigma Plugin APIにはcreateImageAsync()がありますが、現行のuse_figma実行環境では外部画像URLを取得できません。CaptureされたNodeの画像FillからimageHashを取り出し、最終Viewの対応するFrameへ設定します。

targetFrame.fills = [{
  type: "IMAGE",
  imageHash: "hash_from_capture",
  scaleMode: "FILL"
}];

画像転送後はCaptureを残しません。最終成果物は、見た目だけを写したNodeではなく、更新可能なデザインシステムのInstanceで構成します。

依頼に含める情報

少なくとも、次の情報を渡します。

• 対象FigmaファイルのURLまたはFile Key
• 画面のソースコード、またはセクションが分かる説明
• 利用するデザインシステムやチームライブラリ
• 新規作成か既存Viewの更新か
• 対象デバイスと画面幅
• 画像を含むWebアプリの場合は実行可能なURL

figma-useとfigma-generate-designを使い、
このリポジトリの設定画面をFigmaへ構築してください。

対象ファイル: <Figma URL または fileKey>
ソース: src/pages/settings/
幅: 1440px
既存のButton、Input、Card、Variables、Stylesを優先して再利用してください。
各セクションのスクリーンショットを確認してから次へ進んでください。

3つのFigmaスキルを使い分ける

まずLibraryで部品とトークンを整え、その資産を使ってDesignで画面を組み立てます。Figmaで確定した画面を実装へ反映するときはDesign-to-Codeを使います。3つを分離すると、再利用資産、画面構成、実装コードの責務が混ざりません。

まとめ

figma-generate-designは、コードや説明からFigmaへ画面を作る作業を、既存デザインシステムの再利用と段階的な検証を備えたワークフローへ変えるスキルです。

重要なのは、Code Connect、既存画面、ライブラリ検索の順で資産を探すこと、Wrapperを先に作ること、各セクションを直接その中へ追加すること、VariablesとStylesをハードコードより優先することです。画像を含むWebアプリではgenerate_figma_designのCaptureも併用し、最終成果物を更新可能なComponent Instanceへ仕上げます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• Figma MCP Server Guide
• figma-generate-design SKILL.md
• figma-use SKILL.md
• figma-generate-library SKILL.md
• figma-design-to-code SKILL.md
• Use First Draft with Figma AI