apply-design-system

デザインをデザインシステムに接続する

既存の Figma デザインで、切り離されたレイヤー、ローカルラッパー、単発のコンポーネントではなく、公開済みのデザインシステムを再利用する場合にこのスキルを使用します。

このスキルでは、次の 2 つの開始方法をサポートしています。

• review-then-apply：ユーザーは全体的な見直しを希望していますが、問題のあるセクションはまだ特定されていません
• apply-known-scope：ユーザーは、デザインシステムに適合させるセクションまたはクラスターをすでに把握しています

まず、次の機能を読み込んでください。

• get_metadata、get_screenshot、search_design_system などのツールを使うための Figma MCP 読み取りアクセス
• 環境で必要な場合は、use_figma を呼び出す前に figma-use スタイルのヘルパー
• 画面全体またはページ全体を再接続する場合は、利用可能であれば画面構築用の補助ワークフロー

単一の audit-design-system 指摘に対する通常の後続作業として、このスキルを使わないでください。対象を絞った問題には、書き込み範囲を限定できる fix-design-system-finding を使用してください。

基本ルール

デザインシステムのボタンやアイコンがいくつか含まれているだけで、セクションが「接続済み」だと判断しないでください。

このスキルは、複数セクションの整合を取るためのものです。確認済みの特定ノードを 1 つ修正すればタスクを満たせる場合は、より対象を絞った指摘修正用スキルを選んでください。

各セクションを、次のいずれか 1 つに分類してください。

• already-connected：セクション自体がライブラリのインスタンスであるか、すでに標準的なものとしてユーザーが明示的に承認した構成です
• exact-swap：公開済みのライブラリコンポーネントまたはバリアントで、セクションをそのまま置き換えられます
• compose-from-primitives：該当するライブラリコンポーネントが 1 つもありませんが、公開済みのライブラリプリミティブからセクションを再構築できます
• blocked：ライブラリに必要なコンポーネントが公開されていない、インポートに失敗する、またはセクションが意図的に独自設計されています

必須ワークフロー

1. まず対象範囲を決める

置き換え候補を集める前に、画面の初期監査が必要かどうかを判断します。

対象範囲がまだ特定されていない場合：

1. audit-design-system を実行するか、同等の内部監査を実施します。
2. レビュー結果を、すべての細かな指摘を個別の書き換えタスクとして扱うのではなく、セクション単位の作業パッケージにまとめます。
3. レビュー結果が対象を絞った指摘 1 件のみの場合は、ここで作業を続けず、fix-design-system-finding に切り替えます。

対象範囲がすでに特定されている場合は、そのまま進めます。

レビューがすでに存在するという理由だけで、コンポーネントの調査を省略しないでください。レビューで特定できるのはデザインのずれです。このスキルでは、実際に置き換えるプリミティブとバリアントも選ぶ必要があります。

2. 現状を記録する

書き込みを行う前に：

1. get_metadata で対象フレームのメタデータを取得します。
2. get_screenshot でスクリーンショットを取得します。
3. get_design_context が必要で、Figma から Code Connect に関する質問があった場合は、続行する前にツールの指示どおりにユーザーへ質問してください。

このスキルでは、構造の調査には get_metadata と use_figma の併用を優先してください。不足しているコンテキストを補う場合を除き、get_design_context は任意です。

3. 対象画面をバックアップする

破壊的な編集を行う前に、フレームまたはページを複製し、バックアップを右側に配置します。

わかりやすい名前を付けてください。例：

• Backup - Start
• Backup - Mobile dashboard

これを専用の use_figma 呼び出しで行い、作成されたノード ID を返してください。

4. 既存画面を調査する

ライブラリを検索する前に、対象フレームを確認します。

use_figma を使い、次の情報を収集してください。

• トップレベルのセクションインスタンス
• 各セクションの mainComponent
• そのコンポーネントがローカル、リモート、または欠落のいずれか
• 各ローカルラッパー内ですでに使用されているネストされた公開コンポーネント
• 存在する場合は、公開されたテキストプロパティとバリアントプロパティ

名前よりも正確なキーを優先してください。名前はあくまで手がかりです。

読み取り専用のインベントリに使えるパターン：

(async () => {
  try {
    await figma.setCurrentPageAsync(figma.root.children.find(p => p.id === "PAGE_ID"));
    const frame = await figma.getNodeByIdAsync("FRAME_ID");
    const sections = frame.findAll(n => n.type === "INSTANCE").map(inst => {
      const mc = inst.mainComponent;
      const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
      return {
        instanceId: inst.id,
        instanceName: inst.name,
        componentName: mc?.name ?? null,
        componentKey: mc?.key ?? null,
        componentSetName: cs?.name ?? null,
        componentSetKey: cs?.key ?? null,
      };
    });
    figma.closePlugin(JSON.stringify({ createdNodeIds: [], mutatedNodeIds: [], sections }));
  } catch (e) {
    figma.closePluginWithFailure(e.message);
  }
})()

5. デザインシステムからコンポーネントマップを作成する

次の順で、信頼性の高い情報源を優先してください。

1. 同じライブラリまたは作業ファイルにある、すでにシステムを使用している画面
2. use_figma で直接確認した既知のライブラリページ
3. 最後の手段としてのみ search_design_system

search_design_system を使用する場合は、次の点に注意してください。

• 無関係なチームライブラリやコミュニティライブラリが結果に含まれることがあります
• 広範なクエリは候補を探すのに便利ですが、実際のファイルまたはページを確認するまでは、結果を信用しないでください
• 適切なライブラリが判明したら、検索を繰り返すよりも、そのファイルを直接確認してください

候補ごとに、次の情報を記録してください。

• コンポーネントまたはコンポーネントセットのキー
• 正確なバリアント名
• セクションが一対一の置き換えか、複数要素の組み合わせか
• オーバーライドに必要なテキストプロパティキーまたはネストされたインスタンスプロパティ

ライブラリのメインバリアントやデフォルトバリアントを、安易に選ばないでください。

バリアントを選ぶ前に、元のノードを確認し、次の点を把握してください。

• 名前、文言、使用状況から読み取れる意味的な手がかり
• 塗り、線、エフェクト、角丸、タイポグラフィの処理などの視覚的な手がかり
• 画面にすでに現れている、プライマリとセカンダリのボタン処理など、バリアントに似た特徴

次に、これらの手がかりと、利用可能なコンポーネントセットのバリアントを比較し、最も近いものを選びます。ファミリーは適切でもバリアントの一致が曖昧な場合は、デフォルトバリアントを黙って使用せず、その旨を明示してください。

6. セクションの方針を決める

次のヒューリスティックを使用してください。

• ライブラリコンポーネントがセクションの役割と構造に十分近く、swapComponent() または直接の置き換えで意図を保てる場合は、exact-swap を使用します。
• セクションが実際にはアバター、バッジ、ボタン、メトリクス、ナビ項目などのライブラリ要素を囲むコンテナーである場合は、compose-from-primitives を使用します。
• デザインシステムに複合コンポーネントがない、ライブラリが公開されていない、インポートに失敗する、またはセクションを独自のものとして維持すべき場合は、blocked を使用します。

よくあるパターン：

• ヘッダーのサマリーブロックは、多くの場合、単一のコンポーネントではなく compose-from-primitives です。
• アラートやメトリクスには、多くの場合、有力な exact-swap 候補があります。
• 予約や患者のカードは、システムがそうしたドメインカードを明示的に提供していない限り、多くの場合、複数要素の組み合わせが必要です。
• 下部ナビゲーションバーは、多くの場合、ナビ項目のプリミティブから作られたカスタムコンテナーです。

7. 一度に1つのセクションを更新する

1つのスクリプトで画面全体を書き換えないでください。

セクションごとに、次の手順を実行します。

1. 現在のノード ID を読み取ります。
2. ライブラリコンポーネントをインポートするか、特定します。
3. 置き換えまたは再構築する前に、元のセクションに最も近いバリアントを特定します。
4. 親がオートレイアウトを使用しているか確認します。
5. そのセクションのみを作成または置き換えます。
6. 変更したすべてのノード ID を返します。
7. get_screenshot で検証します。

既存のノードが互換性のあるファミリーのインスタンスで、オーバーライドを維持したい場合は、swapComponent() を優先してください。

次の場合は、元のノードの隣で再構築してください。

• 古いセクションが、異なるコンテンツを含むローカルラッパーである
• 元のセクションを置き換える前に、結果を視覚的に比較する必要がある
• 複数のプリミティブから組み立てる

親がオートレイアウトでない場合は、置き換えをレイアウト上のリスクを伴う操作として扱ってください。

オートレイアウトでない親では、次の点に従ってください。

• x と y を明示的に維持します
• 置き換え後も同じ領域を占める必要がある場合は、幅と高さを明示的に維持します
• 新しいインスタンスが古いノードの位置やサイズを引き継ぐと思い込まないでください
• 絶対位置指定またはグループ化された親では、置き換えや再構築後にずれが生じる可能性があることをユーザーに警告します
• ユーザーが構造の整理を望んでいる場合にのみ、親をオートレイアウトに変換することを提案します。デフォルトの手段としては提案しないでください

8. インポートの失敗を明示的に処理する

importComponentSetByKeyAsync() または importComponentByKeyAsync() が失敗するかタイムアウトした場合：

1. 停止します。
2. 無関係な編集を続け、セクションが接続されているかのように扱ってはいけません。
3. 対象ファイルの別の場所に、完全一致するコンポーネントキーがすでに存在するか確認します。
4. ライブラリファイルにアクセスできる場合は、そこで正確なコンポーネントキーを確認します。
5. コンポーネントセットのキーではなく、正確なコンポーネントキーをインポートしてみます。
6. インポートに失敗し続ける場合は、セクションを blocked としてマークし、障害の内容を明確に報告します。

以下は実際のブロッカーとして扱います：

• 公開済みのキーがライブラリに存在するが、インポートがタイムアウトする
• search_design_system でファミリーが見つかるが、対象ファイルにインポートできない
• インポートできるのはネストされたプリミティブのみで、意図した複合コンポーネントはインポートできない

9. 実際に変更された内容を検証する

各セクションの作業後：

• 全体フレームだけでなく、変更したセクションのスクリーンショットを撮影します
• プレースホルダーテキストがなくなっていることを確認します
• インスタンスがライブラリコンポーネントに実際にリンクされていることを確認します
• 間隔に不具合が生じていないことを確認します

最後に、画面全体のスクリーンショットも検証します。

作業ルール

• 段階的に作業し、バックアップを保持します。
• ノイズの多い検索結果より、ライブラリを直接確認する方法を優先します。
• 名前より、正確なコンポーネントキーを優先します。
• 正しいコンポーネントファミリーかどうかだけでなく、元の見た目に合ったバリアントを選びます。
• 自動レイアウトを使用しない親の中身を置き換える場合は、位置とサイズを明示的に維持します。
• レポートでは、ノード名、キー、コンポーネントファミリー、最終ノードがローカルかライブラリに紐付いているかを示す、具体的な証拠を提示します。
• 共有された子要素がいくつかあるだけのローカルな外枠を残している場合、完全に再接続したと主張してはいけません。
• セクションを独自実装のままにする必要がある場合は、その旨と理由を説明します。

成果物の形式

作業を完了する際は、以下を報告します：

• Swapped：ライブラリインスタンスに直接置き換えたセクション
• Composed：ライブラリのプリミティブから再構築したセクション
• Already connected：すでに有効な接続があったセクション
• Blocked：接続できなかったセクションと、その具体的な理由

すべてがブロックされた場合は、その旨を明確に伝え、曖昧な概要ではなく正確な失敗モードを記載します。