デザインシステムから画面/ビューを構築・更新する
このスキルは、公開されたデザインシステム(コンポーネント、変数、スタイル)を再利用して、Figma内で画面、ビュー、複数セクションからなるUIコンテナを作成または更新するために使用します。プリミティブな図形をハードコードされた値で描くのではなく、デザインシステムのトークンを活用します。これには、フルページ、モーダル、ダイアログ、ドロワー、サイドバー、パネルなど、複数のセクションで構成されるあらゆるビューが含まれます。重要なポイントは、FigmaファイルにはコードベースのUIコンポーネントやトークンに対応する、コンポーネント、色/スペーシング変数、テキスト/エフェクトスタイルを含む公開済みデザインシステムが存在する可能性が高いということです。それらを発見し、ハードコードされた色でボックスを描く代わりに使用してください。
必須: use_figmaを呼び出す前に、必ずfigma-useも読み込んでください。そのスキルには、作成するすべてのスクリプトに適用される重要なルール(色の範囲、フォントの読み込みなど)が含まれています。
このスキルの一部としてuse_figmaを呼び出す際は、常に skillNames: "figma-generate-design" を渡してください。 これはログ記録用のパラメータであり、実行には影響しません。
スキルの境界
- このスキルは、成果物が複合的なFigmaビュー(新規または更新)、フルページ画面、モーダル、ダイアログ、ドロワー、サイドバー、パネル、またはデザインシステムコンポーネントインスタンスから構築された複数セクションのコンテナである場合に使用します。
- ユーザーが新しい再利用可能なコンポーネントやバリアントを作成したい場合は、figma-useを直接使用してください。
- ユーザーがCode Connectマッピングを作成したい場合は、figma-code-connectに切り替えてください。
前提条件
- Figma MCPサーバーが接続されていること
- 対象のFigmaファイルに公開されたデザインシステム(またはチームライブラリへのアクセス)があること
- ユーザーから以下のいずれかが提供されること:
- 作業対象のFigmaファイルのURL / ファイルキー
- または、どのファイルを対象とするかのコンテキスト(エージェントがページを発見できます)
- 構築/更新する画面/ビューのソースコードまたは説明
並行ワークフロー(Webアプリ限定)
ブラウザでレンダリング可能なWebアプリから画面を構築する場合、以下の両方のアプローチを並行して実行することで最良の結果が得られます:
- 並行して実行:
- このスキルのワークフロー(use_figma + デザインシステムコンポーネント)を使用して画面の構築を開始する
generate_figma_designを実行し、実行中のWebアプリのピクセルパーフェクトなスクリーンショットをキャプチャする
- 両方が完了したら: use_figmaの出力を
generate_figma_designキャプチャからのピクセルパーフェクトなレイアウトに合わせて更新します。キャプチャは目標とする正確なスペーシング、サイズ、ビジュアル処理を提供し、use_figmaの出力はデザインシステムにリンクされた適切なコンポーネントインスタンスを持ちます。キャプチャに画像が含まれている場合は、キャプチャの画像塗りのimageHash値をコピーしてuse_figmaの出力に転送します(詳細はステップ5を参照)。 - 見た目が良好であることを確認したら:
generate_figma_designの出力を削除します。これは視覚的な参照としてのみ使用されました。
これにより、両方の長所が組み合わされます: generate_figma_designはピクセルパーフェクトなレイアウト精度を提供し、use_figmaはリンクされ更新可能な適切なデザインシステムコンポーネントインスタンスを提供します。
ソースに画像が含まれている場合、この並行ワークフローは必須です。 use_figmaプラグインAPIは外部画像URLを取得できません。ファイル内に既に存在するノードからimageHash値をコピーすることによってのみ画像塗りを設定できます。generate_figma_designは表示されているすべての画像をFigmaにラスタライズし、必要なハッシュを提供します。画像が存在する場合にキャプチャをスキップすると、画像フレームは空白のままになります。
iOS、Androidなどの非Webアプリ、または既存の画面を更新する場合は、以下の標準ワークフローを使用してください。
必須ワークフロー
以下の手順を順番に実行してください。手順をスキップしないでください。
厳格なゲート、禁止されたショートカット:
- 禁止: 2a-iが完了し、2a-iiが試行されるか「該当なし」(例:「空のファイル、既存の画面なし」)と記録されるまで、
search_design_systemでコンポーネントキーを検索すること。- 禁止: 以下のチェックリストのステップ2のすべての行が入力されるまで、キャンバスを変更する
use_figma呼び出し(ステップ3以降)を行うこと。
ステップ1: 成果物を理解する
Figmaに触れる前に、構築するものを理解します:
- コードから構築する場合は、関連するソースファイルを読み、構造、セクション、使用されているコンポーネントを理解します。
- ビューの主要なセクションを特定します(例:ページの場合: ヘッダー、ヒーロー、コンテンツパネル、フッター;モーダルの場合: タイトルバー、フォームセクション、アクションバー;サイドバーの場合: ナビゲーション、コンテンツエリア、フッターアクション)。
- 各セクションについて、関連するUIコンポーネント(ボタン、入力、カード、ナビゲーションピル、アコーディオンなど)をリストアップします。
- ビューに画像が含まれているかどうかを確認します(例:
<img>、<Image>、背景画像、商品写真、アバター、URLから読み込まれるアイコン)。含まれており、これがWebアプリである場合、並行generate_figma_designキャプチャワークフローを実行する必要があります。ステップ2と同時にすぐに開始し、コンポーネントを発見している間キャプチャが実行されるようにします。上記「generate_figma_designとの並行ワークフロー」を参照してください。
ステップ2: コンポーネントキー、変数、スタイルを収集する
デザインシステムから3つの要素が必要です: コンポーネント(ボタン、カードなど)、変数(色、スペーシング、半径)、スタイル(テキストスタイル、シャドウなどのエフェクトスタイル)。デザインシステムトークンが存在する場合、ハードコードされた16進数の色やピクセル値を使用しないでください。
2a: コンポーネントを発見する
2a-i. 必須: 必要なコンポーネントのCode Connectを確認する。 ステップ1で作成したコンポーネントリストから、各コンポーネントにコードベース内にCode Connectファイルがあるかどうかを確認します。Code Connectファイルはコンポーネントソースの隣にあり、プラットフォームごとに命名されています:
- TypeScript/JS:
*.figma.ts、*.figma.js - React(パーサーベース):
*.figma.tsx - Kotlin/Compose:
@FigmaConnectを含む.ktファイル - Swift:
FigmaConnectを含む.swiftファイル
必要な各コンポーネント(例:Button、Card、Input)について、そのCode Connectファイルを検索し、コンポーネント名でglobまたはgrepします(例:**/Button.figma.tsx、**/Card.figma.ts)。実際に必要なコンポーネントに一致するファイルのみを読み取ります。
一致した各Code Connectファイルから、FigmaコンポーネントURLを抽出します。URLからfileKeyとnodeIdを解析します(ハイフンをコロンに変換: 123-456 → 123:456)。次に、use_figmaを介してコンポーネントキーを解決します:
例: Code Connectファイルに // url=https://figma.com/design/ABC123/File?node-id=609-35535 が含まれている場合。fileKey = ABC123、nodeId = 609:35535 を解析します。ライブラリファイル(fileKey ABC123、ターゲットファイルではない)に対してuse_figmaを実行してキーを解決します:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
複数のルックアップを1回の呼び出しでバッチ処理します。返されたキーをステップ4でimportComponentSetByKeyAsync()とともに使用します。
解決されたコンポーネントをマークします。すべてのコンポーネントが解決された場合は、2a-iiと2a-iiiをスキップします。必要なコンポーネントのいずれにもCode Connectファイルがない場合は、2a-iiに進みます。
2a-ii. 未解決のコンポーネントが残っている場合は必須: 既存の画面を検査する。 ターゲットファイルに、同じデザインシステムを使用した画面が既に含まれているかどうかを確認します。既存のフレームのインスタンスをウォークする単一のuse_figma呼び出しにより、正確で信頼性の高いコンポーネントマップが得られます:
// 読み取り専用の探索。速度のためにインスタンス内部の不可視コンテンツをスキップ(非表示のバリアントなど)。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
結果を未解決のコンポーネントと照合します。新しく解決されたものをマークします。すべてのコンポーネントが解決された場合は、2a-iiiをスキップします。
2a-iii. 最終手段: search_design_system。 2a-iと2a-iiの両方が完了した後もコンポーネントが未解決の場合のみ。
検索する前に、get_librariesを呼び出して、ファイルで利用可能なライブラリを発見します。これにより、ファイルに既に追加されているライブラリと、追加可能なライブラリ(コミュニティUIキットと組織ライブラリ)の2つのリストが返されます。各エントリにはlibraryKeyが含まれており、search_design_systemのincludeLibraryKeysパラメータに渡すことで、検索範囲を特定のライブラリに限定できます。
// ステップ1: 利用可能なライブラリを発見
// ステップ1: 利用可能なライブラリを発見
get_libraries({ fileKey })
// Returns: {
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// ステップ2: libraryKeyを使用して特定のライブラリ内を検索
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
libraries_available_to_add内の組織ライブラリはページネーションされています(1ページ20件)。libraries_available_to_add_next_offsetがnull以外の場合、さらに組織ライブラリが利用可能であるため、offsetをその値に設定してget_librariesを再度呼び出し、次のページを取得します。コミュニティUIキットは最初のページにのみ表示されます。ユーザーが特定のライブラリを指定したが現在のページに表示されていない場合は、諦める前にさらにページを進めてください。
これは、ファイルに多くのライブラリがあり、すべてのライブラリからマッチを取得するのではなく、特定のライブラリ(例:「iOS 26」や「Material 3」)内のみを検索したい場合に特に便利です。
幅広く検索: 複数の用語や同義語を試します(例:「button」、「input」、「nav」、「card」、「accordion」、「header」、「footer」、「tag」、「avatar」、「toggle」、「icon」など)。includeComponents: trueを使用してコンポーネントに焦点を当てます。
コンポーネントプロパティをマップに含めます。テキストオーバーライドのために各コンポーネントが公開するTEXTプロパティを把握する必要があります。一時的なインスタンスを作成し、そのcomponentProperties(およびネストされたインスタンスのもの)を読み取り、その後一時インスタンスを削除します。
プロパティ情報を含むコンポーネントマップの例:
Component Map:
- Button → key: "abc123", type: COMPONENT_SET
Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
Properties: { "Device": VARIANT, "Variant": VARIANT }
Nested "Text Heading" has: { "Text#2104:5": TEXT }
Nested "Button" has: { "Label#2:0": TEXT }
2b: 変数を発見する(色、スペーシング、半径)
最初に既存の画面を検査します(コンポーネントと同じ)。または、search_design_systemをincludeVariables: trueとともに使用します。
警告: 2つの異なる変数発見方法を混同しないでください。
use_figmaとfigma.variables.getLocalVariableCollectionsAsync(): 現在のファイルで定義されたローカル変数のみを返します。これが空を返した場合、それは変数が存在しないことを意味するわけではありません。リモート/公開されたライブラリ変数は、このAPIからは見えません。search_design_systemとincludeVariables: true: リンクされたすべてのライブラリ(リモートや公開されたものを含む)を検索します。これはデザインシステム変数を発見するための正しいツールです。
getLocalVariableCollectionsAsync()が空を返したという理由だけで「変数は存在しない」と結論付けないでください。 独自の変数を作成することを決定する前に、必ずsearch_design_systemをincludeVariables: trueとともに実行してライブラリ変数を確認してください。
クエリ戦略: search_design_systemは変数名(例:「Gray/gray-9」、「core/gray/100」、「space/400」)と照合します。カテゴリではありません。複合クエリを1つ実行するよりも、複数の短くシンプルなクエリを並行して実行します:
- プリミティブカラー: 「gray」、「red」、「blue」、「green」、「white」、「brand」
- セマンティックカラー: 「background」、「foreground」、「border」、「surface」、「text」
- スペーシング/サイズ: 「space」、「radius」、「gap」、「padding」
最初の検索が空を返した場合は、より短い断片や異なる命名規則を試してください。ライブラリは大きく異なります(「grey」と「gray」、「spacing」と「space」、「color/bg」と「background」)。
最も信頼性の高い結果を得るには、既存の画面のバインドされた変数を検査します:
// 読み取り専用の探索。速度のためにインスタンス内部の不可視コンテンツをスキップ。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// boundVariablesは任意のシーンノードに存在する可能性があります。
// すべてのシーンタイプを列挙してfindAllWithCriteriaに渡すのは、
// findAll(() => true)とほぼ同じであり、スクリプト出力がはるかにノイズが多くなります。
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
ライブラリ変数(remote = true)の場合は、figma.variables.importVariableByKeyAsync(key)でキーを使用してインポートします。ローカル変数の場合は、figma.variables.getVariableByIdAsync(id)を直接使用します。
バインディングパターンについては、variable-patterns.mdを参照してください。
2c: スタイルを発見する(テキストスタイル、エフェクトスタイル)
search_design_systemをincludeStyles: trueとともに使用し、「heading」、「body」、「shadow」、「elevation」などの用語でスタイルを検索します。または、既存の画面が何を使用しているかを検査します:
// 読み取り専用の探索。速度のためにインスタンス内部の不可視コンテンツをスキップ。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
// textStyleIdはTEXTおよびTEXT_PATHに存在し、
// effectStyleIdはほとんどのシーンシェイプ/コンテナタイプに存在します。
// 網羅的な型リストを避けるために`in`ガードを使用して両方を処理します。
if ('textStyleId' in node && node.textStyleId) {
// ... テキストスタイルの処理 ...
const style = figma.getStyleByIdAsync(node.textStyleId);
// ...
}
if ('effectStyleId' in node && node.effectStyleId) {
// ... エフェクトスタイルの処理 ...
const style = figma.getStyleByIdAsync(node.effectStyleId);
// ...
}
}
// ...
既存の画面が見つからない場合は、search_design_systemを使用してスタイル名を検索します。見つかったら、importStyleByKeyAsync(key)でキーを使用してインポートします。style-patterns.mdを参照してください。
ステップ3: キャンバスを準備する
すべてのデザインシステムデータ(コンポーネントキー、変数、スタイル)を収集したら、以下を行います:
- ターゲットファイルを開く: 既存の画面を更新する場合は、そのページとフレームに移動します。新規作成する場合は、適切な名前で新しいページとフレームを作成します。
- 既存のコンテンツをクリアする: 完全な再構築の場合、
use_figma内でフレームの子を削除します。準備ができていないものは削除しないでください。
ステップ4: セクションごとにビューを構築する
ビューを1つの巨大なスクリプトで作成するのではなく、セクションごとに構築します。これにより:
- 各セクションの後で結果を反復的に確認・調整できる
- ネストされたインスタンスプロパティが混雑したスクリプトで埋もれない
- レイアウトエラーを早期に発見できる
セクションごとの構築パターン:
// セクションごとに個別のuse_figmaスクリプトを作成する
// スクリプト1: ヘッダー
importComponentSetByKeyAsync({ componentKey: "abc123" }).then(() => {
const header = figma.createInstanceFromComponentSetAsync("abc123", { "Variant": "Desktop" });
// プロパティを設定、テキストを上書き
});
// スクリプト2: ヒーローセクション
// ...
// スクリプト3: コンテンツパネル
// ...
インスタンスを入れ子にする: セクションフレームをfigma.createFrame()で作成し、配置後にインスタンスをその子として追加します。appendChild()を使用してツリーを構築します。
テキストオーバーライド: テキストプロパティを設定する前に、インスタンスが特定の構造(table、flexboxの子など)を持っていることを確認します。テキストノードが予期しないパスにある場合があります。findAllWithCriteriaを使用してインスタンスの子を探索し、テキストを安全に設定します:
instance.findAllWithCriteria({ types: ["TEXT"] }).forEach(t => {
if (t.name === "Button Label" && t.characters === "Label") {
t.characters = "送信";
}
});
findAllWithCriteriaは読み取り専用であり、Figmaのインスタンス内部ノードツリーを探索するための信頼できる方法です。
変数の適用: 変数バインディングとスタイルについては、variable-patterns.mdおよびstyle-patterns.mdでのパターンに従ってください。
ステップ5: 画像の処理(Webアプリ、並行ワークフローを使用)
画像がある場合は、generate_figma_designキャプチャが完了した後に、出力から各画像のimageHash値を抽出します。Figmaファイル内のノードでこれらの値を使用して画像塗りを設定できます:
// generate_figma_designの出力からimageHashを取得
const nodeWithImage = captureFrame.findOne(n => n.name === "Product Image");
const hash = nodeWithImage.fills[0].imageHash; // 例: "Hc3k..."
// 同じimageHashをビルドしたビュー内の画像フレームに適用
const myImage = myFrame.findOne(n => n.name === "Product Image");
myImage.fills = [{ type: "IMAGE", imageHash: hash, scaleMode: "FILL" }];
画像ハッシュの転送を怠ると、画像フレームは空白のままになります。
ステップ6: 確認して修正する
セクションごとのビルド後:
- ビュー全体を視覚的に確認するために
use_figma呼び出し(またはgenerate_figma_designキャプチャとの比較)を実行します - レイアウトの不一致(スペーシング、サイズ、配置)に対処します
- テキストオーバーライドが正しく適用されていることを確認します
- すべてのインスタンスが正しくインポートされたコンポーネントセットにリンクされていることを確認します
- 次の反復で改善する領域に注意します
ベストプラクティス
- バッチルックアップ: 複数の
importComponentSetByKeyAsync呼び出しを可能な限り1つのuse_figmaスクリプトにグループ化します。 - インスタンスのテスト: プロパティを設定する前に、インスタンスで
findAllWithCriteriaを使用してテキストノードの構造を検証します。 - 読み取り専用探索:
figma.skipInvisibleInstanceChildren = trueを設定したfindAllWithCriteriaは、キャンバスを変更せずにインスタンス内部を探索するための高速な方法です。 - 常にCode Connectを最初に確認する: 利用可能な場合は、
search_design_systemを使用するよりも、Code Connectはより正確で高速なコンポーネント解決を提供します。 - セクションごとに構築する: ビルドプロセスを管理可能な単位に分割し、各セクションの後に検証します。
- 変数とスタイルを再利用する: 生の16進数やピクセル値の代わりに、発見した変数とスタイルを適用します。これにより、デザインシステムへのリンクが維持されます。
トラブルシューティング
- コンポーネントキーが見つからない: 手順2aを完了していることを確認してください。Code Connect、既存の画面の検査、
search_design_systemのすべてを試してください。 - 変数が適用されない: 変数が未定義でないこと、正しいキーを使用していることを確認してください。リモート変数のインポートが必要な場合があります。
- テキストスタイルが機能しない: 多くのテキストスタイルはプラットフォームごとに異なります。リモートスタイルの場合は
importStyleByKeyAsyncを使用し、ローカルのものについては手順2cからスタイルIDを使用します。 - 画像が読み込まれない: ソースに画像が含まれている場合、並行
generate_figma_designワークフローを実行しましたか?画像ハッシュを正しく転送しましたか? - レイアウトの不一致: 自動レイアウトのパディング、アイテム間のギャップ、フレームのサイズを確認します。
generate_figma_designキャプチャをピクセル完璧なガイドとして使用します。 - パフォーマンスの問題: 大規模なビルドの場合、ファイルが重くなりすぎないように、不要になった中間ノードやスクリプト出力をクリーンアップします。