fix-design-system-finding

デザインシステムの指摘を1件修正する

audit-design-system で具体的な問題がすでに特定されている場合に、このスキルを使用します。

このスキルの対象範囲は意図的に限定されています。

• 一度に1件の指摘
• 一度に1つの問題のあるノード、または局所的なクラスター
• 最小限の読み取り範囲
• 最小限の書き込み範囲

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

• 通常の確認ツールを使用するための Figma MCP 読み取りアクセス
• 環境で必要な場合は、use_figma の書き込み呼び出しの前に figma-use スタイルのヘルパー

画面全体を広範囲に再接続する必要がある場合、複数のセクションに連携した変更が必要な場合、またはユーザーがフレーム全体の一括対応を明示的に求めている場合は、代わりに apply-design-system を使用してください。

想定される入力

次のいずれかを推奨します。

• audit-design-system による単一の JSON 指摘
• レビュー JSON 全体と、対応する特定の指摘
• 問題の言い換えと、Figma URL または fileKey および nodeId

指摘が audit-design-system によるものである場合は、次の項目から対象を抽出します。

• code_location.absolute_file_path = /figma/<fileKey>/nodes/<nodeId>

レビュー結果をスコープの契約として扱ってください。1件の指摘への対応から、気づかれないうちに全体の整理へと対象を広げてはいけません。

スコープのルール

次のいずれかに該当するまで、選択した指摘に限定して対応してください。

• fixed：対象の問題を修正した
• blocked：修正にライブラリアセットの不足、アクセスできないコンポーネント、またはより広範なプロダクト上の判断が必要
• needs-follow-up：対象ノードは改善されたが、別の隣接する問題が残っており、個別に確認すべき

ユーザーが複数の指摘を貼り付けた場合は、選択したものに対応するか、最優先の指摘を選び、今回修正する対象として明示してください。

必須ワークフロー

1. 指摘を正規化する

次の項目を抽出して、内容を言い換えてください。

• fileKey
• 問題のある nodeId
• 指摘のタイトル
• レビュアーが指摘した理由

レビュー出力で特定のノードが示されていない場合は中止し、元の指摘 JSON または Figma の直接のノードを求めてください。

2. 置き換え候補が不明確な場合はローカル互換性チェックを実行する

バックアップやキャンバスの編集を行う前に、適切な修正が実際に可能かを判断してください。

次の場合はローカル互換性チェックを実行します。

• 指摘がデザインシステムの置き換えを示唆しているものの、正確なコンポーネントを特定していない
• 該当しそうなライブラリコンポーネントが複数ある
• オーバーライドの挙動やサイズが不明確
• ユーザーが書き込み前に追加調査を明示的に求めている

互換性チェックの結果が次のいずれかになるまで、書き込みを続けないでください。

• safe-to-apply
• blocked
• needs-human-choice

互換性チェックでは、次の点に回答する必要があります。

• 有力候補となる正確なコンポーネントまたはバリアント
• テキスト、アイコン、状態、サイズのオーバーライドがサポートされているか
• 置き換え後もノードのレイアウト契約を維持できるか

結果が blocked の場合は中止し、阻害要因を報告してください。

結果が needs-human-choice の場合は、中止して推測せず、必要最小限の確認質問をしてください。

3. 必要な証拠だけを集める

書き込みの前に、役立つ最小限の読み取りで対象を確認してください。

1. 問題のあるノード、または最も近い親セクションの get_screenshot
2. 構造上のコンテキストを得るための get_metadata
3. 指摘がトークン、未加工の値、色、間隔、またはタイポグラフィに言及している場合は get_variable_defs
4. 指摘が既存のマッピング済みコンポーネントを示唆している場合は get_code_connect_map
5. 置き換え用プリミティブの特定がまだ必要な場合に限り search_design_system

指摘が繰り返しのパターンを明確に示しており、修正の選択にそのパターンの確認が必要な場合を除き、ボード全体を再レビューしないでください。

4. 修正方法を分類する

修正方法を次の中から必ず1つ選択します。

• swap-instance：場当たり的に作成されたインスタンスや誤ったインスタンスを、適切なライブラリコンポーネントまたはバリアントに置き換える
• compose-from-primitives：公開されているライブラリのパーツから、ローカルのカスタムラッパーを再構築する
• bind-tokens：生の値を変数またはスタイルに置き換える
• align-variant：既存のインスタンスを適切なバリアントまたはプロパティの状態に変更する
• blocked：現時点では、ライブラリに基づく有効な修正ができない

複数の方法が妥当に思える場合は、元の指摘を満たす最小限の変更を優先します。

5. 影響範囲のみをバックアップする

破壊的な編集を行う前に、問題のあるノード、またはそれを含む最小範囲のローカルセクションのみを複製します。

次のように、内容がわかる名前を付けます。

• Backup - Fix finding 1
• Backup - Custom nav

独立した書き込み呼び出しでバックアップを作成し、作成されたノード ID を返します。

6. 段階的に修正を適用する

画面全体を再構築しないでください。

次の手順を小さく分けて進めます。

1. 現在のノード ID とコンポーネントのリンクを確認する
2. 必要なライブラリコンポーネントまたは変数をインポートするか、見つける
3. 対象範囲のみを置き換える、組み合わせる、またはトークンに置き換える
4. 作成および変更したすべてのノード ID を返す

ノードの位置と有効なオーバーライドを維持できる場合は、swapComponent() を優先します。

次の場合は、元のノードの横に再構築することを優先します。

• 現在のノードが、カスタム構造を含むローカルラッパーである
• レビューの指摘が単一のプリミティブではなく、カスタム構成を対象としている
• 元のノードを置き換える前に、見た目を比較する必要がある

最初の検証で、推奨コンポーネントによってレイアウト、テキストの表示、アイコンの動作、または幅の要件が損なわれることがわかった場合は、作業を止めてください。同じプリミティブを無理に適用し続けず、blocked または needs-follow-up として報告します。

7. 画面全体ではなく、指摘を検証する

書き込み後、次の手順を行います。

1. 変更したノードまたはその直近のセクションのスクリーンショットを撮る
2. レビューで指摘された問題が解消されていることを確認する
3. それが目的だった場合は、結果がライブラリに基づいている、またはトークンにバインドされていることを確認する
4. 余白とテキストのオーバーライドに問題がないことを確認する

修正がナビゲーションのようなグローバルなパターンに影響した場合を除き、検証範囲をローカルセクションより広げないでください。

判断のヒューリスティック

• プリミティブがフレームとして再作成されたという指摘の場合は、swap-instance を優先します。
• 繰り返し使われるローカルラッパーを共通パターンに統合すべきという指摘の場合は、タスクで全ての同一要素への適用が明示されていない限り、代表的なノードを1つ修正します。
• トークン化された要素と並ぶ生の値に関する指摘の場合は、bind-tokens を優先します。
• サイズまたは状態が誤っている、ローカルで編集されたインスタンスに関する指摘の場合は、align-variant を優先します。
• ライブラリに必要なコンポーネントファミリーがない、またはインポートに失敗した場合は、偽の関連付けを作り出さずに blocked とします。
• デザインシステムのコンポーネントが存在していても、ノードのテキスト、アイコン、サイズの要件を維持できない場合は、置き換えを無理に行わず、blocked または needs-human-choice とします。

作業ルール

• 書き込みの範囲は、選択した指摘に厳密に合わせます。
• 置き換えるものの選択が曖昧な場合は、互換性の結果が safe-to-apply になる前に書き込みを行わないでください。
• 1つの指摘を修正しただけで、画面全体が「デザインシステムに準拠している」と主張しないでください。
• 名前よりも、正確なコンポーネントキーと変数 ID を優先します。
• ずれに気付いたという理由だけで、無関係な整理を続けないでください。
• より広範なリファクタリングが明らかに必要な場合は、対象の修正を完了するか、ブロッカーを報告したうえで、次の作業として apply-design-system を推奨します。

成果物の形式

タスクを終了する際は、次の内容を報告します。

• Finding fixed：何を変更し、どのノードを対象にしたか
• Validation：元の問題が解消されたことをどのように確認したか
• Blocked または Follow-up：指摘を完全に解決できなかった場合のみ

報告は対象の1つの指摘に関連する内容にしてください。ユーザーから求められない限り、画面全体の概要は避けてください。