audit-design-system

デザインシステムを監査する

Figma ノードを確認し、デザインがデザインシステムに適切に統合されていない証拠がないかを調べます。

このスキルは読み取り専用です。その後、ユーザーが書き込み操作を求めた場合、ホスト環境でヘルパーが必要なら、後続のスキルは figma-use スタイルのヘルパーを通じて use_figma を使用してください。

出力形式の選択

• ユーザーからの明示的なリクエストを優先します：
  • ユーザーが --json または JSON を求めた場合は、JSON をそのまま出力します（Markdown のコードフェンスや説明文は付けません）。
  • ユーザーが --markdown、Markdown、または特定の人間が読みやすい形式を求めた場合は、人間が読みやすい Markdown レポートを出力します。
• Codex Desktop アプリ：デフォルトで JSON をそのまま出力します。
• Codex CLI およびその他のチャット形式の環境：デフォルトで人間が読みやすい Markdown レポートを出力します。
• 機械処理されるレビュー画面：デフォルトで JSON をそのまま出力します。
• 環境が不明確な場合：デフォルトで Markdown を出力します。

ワークフロー

1. Figma の入力を解析します。 Figma の完全な URL、または fileKey と nodeId を受け付けます。 必要に応じて、ノード ID を 72-293 から 72:293 に正規化します。

2. Figma MCP の読み取りツールを使用して、必要最小限の証拠を取得します。 レビュー対象の正確なノードに対して get_design_context を呼び出します。 視覚的な確認のために get_screenshot を呼び出します。 実際にどの変数がバインドされているかを確認するため、get_variable_defs を呼び出します。 該当する場合は、get_code_connect_map を呼び出します。 レビュー対象のノードが大きい、繰り返しが多い、またはボード形式で、詳細を確認する前にネストされたインスタンスの対応関係を把握する必要がある場合は、get_metadata を呼び出します。 システム化されていない可能性が高いプリミティブを特定し、監査対象のデザインシステムから具体的な置き換え候補を提示できる現実的な見込みがある場合は、search_design_system を呼び出します。

3. 見た目の好みではなく、システム化の不備を確認します。 デザインシステムを継承するべき箇所がローカルで構築されていないかを探します。 すべての指摘は、インスタンス、重複したフレーム、生の値、バリアントのずれ、トークンのバインド漏れなど、Figma 上で確認できる構造に基づけてください。 根拠の弱い指摘をするより、指摘を省くことを優先します。

4. 根拠が十分に強い場合は、置き換え候補を提案します。 カスタムプリミティブの可能性が高いものを特定した後、search_design_system を使用して、監査対象のデザインシステム内で最も近いコンポーネントファミリーを探します。 スクリーンショットの類似性だけでなく、構造と命名から見て一致する可能性が高い場合に限り、候補を含めます。 検索結果がノイズの多いもの、または曖昧な場合は、推測で候補を挙げずに省略します。

5. 環境に応じた形式で指摘を提示します。 Codex Desktop と機械処理されるレビュー画面には JSON を、Claude Code CLI やその他のチャット形式の環境には Markdown を使用します（上記の「出力形式の選択」を参照してください）。

6. ユーザーが修正を求めた場合は、適切な後続スキルに引き継ぎます。 問題のある特定のノードを修正する場合は、fix-design-system-finding を優先します。 画面全体を対象にした広範な確認をユーザーが求めている場合、複数のセクションで連携した修正が必要な場合、または書き込み前の範囲定義にレビューを使用する場合は、apply-design-system を優先します。

指摘対象

• コンポーネントインスタンスではなく、その場しのぎのフレームとして再作成された共有 UI プリミティブ。 よくある対象：ボタン、アイコンボタン、カード、アラート、ピル、チップ、アバター、統計タイル、タブバー、ナビゲーションバー、FAB、リスト行。

• 明らかに 1 つの再利用可能なプリミティブにまとめるべき、繰り返し登場する兄弟構造。 例：内容が異なるだけの、ほぼ同一の統計タイルが 3 つある。

• ほかのデザインシステム要素では変数を使っているのに、視覚的な値がハードコードされている。 よくある対象：塗りつぶし、線、テキストの色、角丸、間隔、タイポグラフィ、影。 生の 16 進カラー値や、トークン化された要素の隣に独自のジオメトリがあるなど、具体的な証拠がある場合にのみ指摘してください。

• カスタムフレームで構築されたグローバルナビゲーションや、その他の影響範囲が大きいパターン。 多くの画面にわたって不整合が広がるため、これらは積極的に指摘してください。

• 名目上はコンポーネントであるものの、バリアントに不整合がある。 例：ローカルの編集ボタンのサイズ、線の太さ、角丸が、想定されるアイコンボタンのプリミティブと一致していない。

指摘対象外

• 純粋に審美的な好み。
• コピーライティングや製品上の判断。
• 画面固有の要素として合理的に維持できるレイアウトの選択。
• 基盤となるプリミティブがすでにコンポーネント化され、トークン化されている場合の、一度限りの構成。
• 文書化されていないデザインライブラリに関する推測が必要な主張。

根拠の基準

各指摘では、次の 2 つの質問の両方に答える必要があります。

1. これが適切にシステム化されていないことを示す、具体的な Figma の根拠は何ですか？
2. それが伝播、一貫性、テーマ設定、またはメンテナンスに影響するのはなぜですか？

有効な根拠の例：

• インスタンスにすべきノードが通常のフレームになっている
• 複数の兄弟要素で同じ構造が重複している
• 変数や標準的なプリミティブを適用すべき箇所に、生の色やジオメトリの値が使われている
• グローバルなパターンがカスタム実装されている

根拠として弱いものの例：

• 「これはカスタムに見える」
• 「通常ならこれをコンポーネントにする」
• 構造的な裏付けのない、スクリーンショットの見た目だけに基づく発言

置き換えの提案に関するルール

共有プリミティブの欠落に関する指摘では、可能であれば置き換え候補を 1 つ添えてください。

欠けているもののカテゴリがわかってから、search_design_system を使用してください。例：

• カスタムのアバタークラスター
• 独自の統計タイル
• ローカルのアラートカード
• 手作業で構築されたナビゲーション項目

次の条件を満たす場合にのみ、置き換え候補を提案してください。

• ノードの役割が明確である
• 検索結果が関連するライブラリまたは監査対象のファイルコンテキストに属している
• 候補が指摘内容と構造的に適合している

適切な提案の表現：

• このカスタムアバターフレームは、ライブラリ X の Avatar に置き換えられる可能性があります。
• これらの繰り返し使われている統計タイルは、ライブラリ X の Metric item に対応しているようです。

過度な断定は避けてください。

• 根拠が明確でない限り、提案したコンポーネントが確実に正しいと主張しないでください
• すべての指摘に置き換え候補を無理に含めないでください
• 検索で最初に表示されたというだけで、無関係なライブラリのコンポーネントを推奨しないでください

出力形式

JSON 出力

選択された出力形式が JSON の場合は、Markdown のコードフェンスや追加の文章を付けず、次の JSON 形式をそのまま返してください。

{
  "findings": [
    {
      "title": "<= 80 chars, imperative>",
      "body": "<valid Markdown explaining why this is a problem>",
      "confidence_score": 0.0,
      "priority": 0,
      "code_location": {
        "absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
        "line_range": {
          "start": 1,
          "end": 1
        }
      }
    }
  ],
  "overall_correctness": "patch is correct" | "patch is incorrect",
  "overall_explanation": "<1-3 sentence summary>",
  "overall_confidence_score": 0.0
}

スキーマに関する注意事項：

• デザインシステムとの統合に関する問題が 1 つ以上見つかった場合は、overall_correctness: "patch is incorrect" を使用してください。
• 指摘がない場合に限り、overall_correctness: "patch is correct" を使用してください。
• 各指摘では、最も具体的な問題ノードを指定し、code_location.absolute_file_path を /figma/<fileKey>/nodes/<nodeId> に設定してください。
• line_range.start と line_range.end は常に 1 に設定してください。

人が読みやすい Markdown レポート

選択した出力形式が markdown の場合、次の内容を含む、書式設定された Markdown レポートを提示します。

1. ヘッダーセクション：

   • レビュー対象のファイル名とノード
   • 総合判定：✅ 合格 / ⚠️ 要対応 / ❌ 重大な問題あり
   • 信頼度（パーセンテージ）

2. 概要： 全体の状態を説明する2～3文

3. 指摘事項の表： 優先度を示した簡潔な一覧

   • 🔴 重大（優先度3）：ライブラリレベルまたはナビゲーションレベルの深刻な問題
   • 🟠 高（優先度2）：重要な再利用可能プリミティブまたはトークン化に関する問題
   • 🟡 中（優先度1）：中程度のシステムとのずれ
   • ⚪ 低（優先度0）：軽微な点、または影響の小さい一貫性の問題

4. 詳細セクション： 各指摘事項を詳しく説明します。次の内容を含めます。

   • 問題点（Figma の構造から確認できる具体的な根拠）
   • 重要な理由（保守性、一貫性、テーマ設定への影響）
   • search_design_system で裏付けられる場合は、置き換え候補
   • 参照用の影響を受けるノード ID

5. 推奨事項： 優先順位を付けた対応項目

出力ルール

• 指摘事項は、重要度の高い問題に絞ってください。通常は0～6件です。
• タイトルは命令形にし、80文字未満にしてください。
• ユーザーが Figma で該当箇所を特定できるよう、各指摘事項には必ず特定のノード ID を記載してください。
• JSON 出力では、ファイルシステムのパスを作り出さないでください。必ず /figma/<fileKey>/nodes/<nodeId> を使用してください。
• 信頼できる置き換え候補がある場合は、指摘事項の本文に含めてください。

レビューの判断基準

priority は次のように指定してください。

• 0：軽微な点、または影響の小さい一貫性の問題
• 1：中程度のシステムとのずれ
• 2：重要な再利用可能プリミティブまたはトークン化に関する問題
• 3：広範囲に波及する可能性がある、ライブラリレベルまたはナビゲーションレベルの深刻な問題

confidence_score は次のように指定してください。

• 0.9-1.0：構造から直接確認できる根拠
• 0.7-0.89：繰り返しや周辺のトークン使用状況から導かれる強い推論
• 0.5-0.69：妥当ではあるものの根拠が不十分な推論。この場合は指摘事項への記載を避けてください。

ボードと画面の対象範囲

単一画面の場合：

• ルートノードを確認します
• 繰り返し使用されている子ノード、または影響範囲の大きい子ノードを詳しく確認します
• 問題のある最も具体的なノードを指摘事項に記載します

ボードまたは大きなページの場合：

• 候補となる画面や繰り返し使われるモジュールを特定するため、まず get_metadata を使用します
• すべてを監査しようとせず、関連性の高いノードのみを確認します
• 指摘事項の対象範囲を絞り、根拠に基づいて記載します

例となるトリガーフレーズ

• 「この Figma 画面でデザインシステムとの統合状況を確認して」
• 「このボードを監査して、コンポーネントの使用漏れを確認して」
• 「このデザインでトークンが正しく使われているか確認して」
• 「/audit-design-system https://figma.com/design/...」
• JSON 出力の場合：「/audit-design-system --json https://figma.com/design/...」

引き継ぎのガイダンス

レビュー後は、次の振り分けルールを使用してください。

• 具体的な指摘事項が1件で、変更範囲が限定的な場合は、fix-design-system-finding を使用します
• 複数の指摘事項をまとめて画面またはセクション全体の調整が必要な場合は、apply-design-system を使用します

レビュー結果をすべて、単一の指摘事項を修正するスキルに無理に当てはめないでください。より広範な適用作業に向けて、対象範囲を把握するためにレビューを活用したほうがよい場合もあります。