pixel-audit

ピクセル監査

1 つのページを正とする情報源と照合し、不一致を修正して、各修正を要素レベルで証明してから「検証済み」とします。/design-system はプロジェクト開始時にプレビューを使ってライブラリ全体を一度チェックします。このスキルは機能開発中に 1 つのプロダクトページをチェックします。プロジェクトのライブラリを参照し、ここでコンポーネントを作り直してはいけません。

入力

リクエストから推測し、不足している情報のみ質問します。

• TARGET PROJECT-CODE — Project Matrix の完全なコードです。スタックの慣習と UI ライブラリを指定します。
• SCOPE — 監査対象となる単一のページ／ルートと状態（一覧／詳細、モーダル、フォーム、空／エラー／読み込み中、レスポンシブのブレークポイント、情報源に存在する場合はライト／ダークなどのテーマバリエーション）です。スコープは厳密な境界です。ほかのページ、ルート、ステップは絶対に編集しないでください。
• SOURCE OF TRUTH — Figma MCP コンパニオン経由の Figma ノード、または Figma がない場合は参照画面／参照実装です。成果物には、どちらを使用しているかを記載します。どちらも利用できない場合は停止して確認してください。記憶を頼りに監査してはいけません。
• ログイン／環境 — ページで認証が必要な場合に限り、ローカルの認証情報を指定します。

最初に読み込むもの

• 対象の拘束力を持つコンテキスト：GLOSSARY.md（旧 CONTEXT.md）およびページ／トピック別、または関連する決定から特定した ADR。関連する ADR のみ読みます。
• デザインシステムのドキュメントまたは AGENTS.md で指定されたプロジェクトの UI スキル。登録されていない場合は *-ui-coding スキルを検出して代わりに使用します。**コンポーネントを再利用し、インラインで実装してはいけません。**存在しない場合は、デザインシステムのドキュメントまたはプロジェクトコードからトークン、ライブラリ、プレビューを特定します。

プロセス

1. ページをマッピングする

ルート、ビュー／テンプレート／コンポーネントのファイル、パーシャル、対象範囲内の状態、データ、およびページで使用すべき DS コンポーネントを特定します。コンポーネントのプレビュー（例：/ui/preview/all）があれば開きます。

2. アセットのパイプラインを追跡する

ビルド／アセットのパイプライン、キャッシュ、コンテナ／サービスを特定し、クラス／スタイル／コンポーネントの変更が実際にページへ反映される仕組みを確認します。

3. ピクセルのインベントリを記録する

編集前に正とする情報源を記録します。ノード／領域ごと（フレーム、パネル、カード、行、フィルター、タブ、モーダル、フィールド、ボタン、およびすべての空／エラー／読み込み中／レスポンシブのバリエーション）に、折り返し後の領域も含めて実寸で記録します。フレーム全体のスクリーンショット 1 枚だけに頼ってはいけません。正確な x／y、サイズ、間隔、パディング、ギャップ、フォント、色、境界線、角丸、塗り、アイコンサイズ、配置、不透明度、シャドウ、バリエーションを記録します。期待値は、Figma MCP ノードのメタデータ／変数（正確な値）、または参照画面から測定した値（近似値と明記）です。後者の場合、検証ゲートでは絶対的なピクセル値ではなく、相対的な配置と一貫性を証明します。ソースごとのキャプチャ呼び出しについては、references/evidence-capture.md を参照してください。

4. 期待値と実際の状態を監査する

ノード／状態ごとに不一致を分類します。

• MISSING — 情報源にある項目／状態がアプリに存在しない、または誤っています。
• EXTRA — 情報源にない項目／状態がアプリに存在します。追加 UI は不具合です。判断を求めて報告してください（「修正」のルールを参照）。

不具合リストの成果物

<artifacts-root> を解決します。*.code-workspace ディレクトリがあればそこを使用し、なければコンテキストごとのルート（リポジトリルートの GLOSSARY-MAP.md、旧 CONTEXT-MAP.md）を使用します。それもなければリポジトリルートを使用します。ファイル名には PROJECT-CODE を含め、2 つのプロジェクトで同じ名前のページがあっても衝突しないようにします。

<artifacts-root>/specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md

インベントリとスクリーンショットはその隣に置きます。<TARGET-PROJECT-CODE>-<page-slug>-inventory.md および shots/<TARGET-PROJECT-CODE>-<page-slug>/ とします。両方の Markdown 成果物に帰属ゼロのルールを含めます。

不具合ごとに 1 行を記載します。

# Pixel Audit — <page-slug> (<TARGET-PROJECT-CODE>)

Zero attribution: never add or leave co-author, AI, or tool attribution in any output.

Source of truth: <Figma node(s) URL | reference screens/impl — name it>
Scope: <route + states audited>

| # | Node | URL / State | File / Component | Mismatch | Expected | Actual | Kind | Evidence | Status |
| - | ---- | ----------- | ---------------- | -------- | -------- | ------ | ---- | -------- | ------ |
| 1 | Filter bar, Search field | /assets · list | components/search-field | height off | 34px | 40px | MISSING | rect=…, computed=… | open |
| 2 | Row actions, extra "Delete" | /assets · list | pages/assets/index | not in source | — | delete icon present | EXTRA | ref=…, screenshot | open |

証拠は、検証ゲートに従って要素レベルで示します。ステータスは open → awaiting verification → verified と進み、ゲートに失敗した場合は reopened になります。再実行時に旧形式の fixed 行があれば、awaiting verification として扱います。これらにも完全なゲートが必要です。

修正

• 1回につきノード／ページ／状態は1つです。 無関係な修正をまとめて行わないでください。
• 動作、データ、インターフェースの作業が必要な MISSING の不具合は、スタイル修正ではなくスライスです。 該当行を記録し、/to-tickets に回して、ここでは実装しないでください（境界は /polish-batch が定めます）。
• プロジェクトの UI ライブラリのコンポーネントを再利用してください。 正当な理由と文書化がない限り、独自の UI を作成しないでください（登録済みのプロジェクト UI スキルにある再利用と新規作成のルールに従ってください）。
• 共有コンポーネントを変更する必要がある場合は、ライブラリ、プレビュー、登録済みのプロジェクト UI スキルを拡張するために /design-system を提案してください。ページ固有の変更として修正したり、自動で次の作業に進んだりしてはいけません。 まずユーザーに確認してください。他のページでも使われており、このページのフレームが例外である可能性があります。別途許可されるまでは、該当行を Needs user の下で open のままにして続行してください。共有コンポーネントを無断で書き換えてはいけません。
• SCOPE の範囲を厳守してください。 他のページやフローにある見た目上の小さな問題は、ここでは修正せず、/polish-batch で記録してください。
• EXTRA は報告し、判断はしないでください。 アプリにはあるもののソースにはないアイコン／ボタン／フィールド／アクションは、黙って残したり、削除したり、スタイルを変更したりせず、ユーザーが判断できるよう提示してください。

検証ゲート

「検証済み／完了／修正済み」と主張するには、修正ごとに根拠が必要です。

• 環境を明記してください。 ホスト／URL とブラウザー／セッション、またはローカルアプリのビルドとシミュレーター／デバイスを記載してください。
• ビルドパイプラインを通してください。 変更のたびに再ビルド／更新し、変更したクラス／スタイル／コンポーネントがソースファイルだけでなく、ページまたはアプリが実際に読み込んだアセットに存在することを確認してください。
• 要素単位の根拠で各修正を証明してください。 セレクター／ref、getBoundingClientRect()、関連する計算済みスタイル、DOM、および配置が重要な場合は切り抜きスクリーンショットを提示してください。ネイティブアプリでは、同等のインスペクターによるジオメトリー、解決済みスタイル、レンダリングツリー、およびローカルシミュレーターのスクリーンショットが必要です。ページ全体のスクリーンショットは概要にしか使えません。必要な自動化が利用できない場合は、保留中の手動確認を列挙し、推測で行を verified にしないでください。
• 次は失敗とみなします。 非表示、サイズがゼロ、折りたたまれている、切り取られている、位置がずれている、サイズが誤っている、またはクラスが適用されていない要素、およびステップ3のキャプチャと比べて新たに発生したコンソールエラー。
• 検証済みとする前に反証を試みてください。 修正が誤っている可能性（ブレークポイントが違う、アセットが古い、クラスが適用されていない、要素が画面外にあるなど）を積極的に探し、排除してください。
• 次のすべてを満たさない限り、「検証済み／完了／修正済み」と言ってはいけません。 環境を明記 · ビルドパイプラインを通過 · 読み込まれたアセットに変更が含まれる · 要素の根拠を取得 · ソースを実寸で取得 · 期待値と実際の値を比較 · 対象範囲内のすべての状態を確認。未着手の行は open のままにし、ゲートを満たせない変更済みの行は reopened にしてください。
• 最終確認： 最終報告の前に、最終ビルド上で verified の各行について要素の根拠を再取得してください。状態が変わっていた行は reopened にしてください。

ルール

• 帰属表示は一切禁止です。コミット、PR、イシューコメント、リリースノート、生成ドキュメント、設定、コードコメントに、共同作成者、AI、ツールの帰属表示を追加したり残したりしないでください。
• 提案にとどめ、自動で次の作業に進まないでください。 監査後に /code-review を提案し、変更した行がすべて検証済みの場合に限り /commit-push-close または /commit-push-pr を提案してください。変更した行に reopened がある場合は、まず解決を提案してください。その後は停止します。
• 決定は成果物です。インベントリと不具合一覧はチャットではなく、ディスク上に保存してください。
• どこでも Project Matrix に記載された PROJECT-CODE の正式名称を使ってください。あるプロジェクトの規約、トークン、コンポーネントを別のプロジェクトに混在させないでください。
• ローカル環境のみ。 ローカルの認証情報、ローカルブラウザーを使い、クラウドエージェントは使わないでください。
• サブエージェント：独立した作業にはローカルのレーンを自動で割り当ててください。クラウドエージェントは使わないでください。割り当て時にレーン数を伝え、各レーンの完了時に報告してください。レーンで実行するのはステップ1（ページのマッピング）のみです。修正、統合、ゲートの確認はメインエージェントが担当します。
• 各フェーズの移行時に Stage / Found / Next / Needs user を出力してください。各フィールドは1行ずつ記載します。フェーズは mapped → inventory captured → audited → fixing → verified です。

出力

対象範囲内の修正後：

Stage: pixel-audit — audited <page-slug> (<TARGET-PROJECT-CODE>) vs <source of truth>; wrote specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md.
Found: <N> defects (<M> MISSING, <E> EXTRA); <V> verified, <R> reopened; <U> EXTRA items awaiting your decision.
Next: <resolve reopened changed rows; otherwise /code-review, then /commit-push-* for verified changes>. Untouched open rows and EXTRA decisions stay for the next pass.
Needs user: <EXTRA items to decide (keep/remove/restyle), or blocked states, or "none">.

Suggested next skills (optional):
- /code-review: eyeball the in-scope diff before shipping.
- /commit-push-pr (or /commit-push-close): only when every changed row included in the shipment is verified.

提案の先には進まないでください。

完了条件

• <artifacts-root>/specs/pixel-audit/<TARGET-PROJECT-CODE>-<page-slug>-defects.md に不具合一覧があり、情報源と対象範囲が明記され、不具合ごとに1行で記載されている
• <TARGET-PROJECT-CODE>-<page-slug>-inventory.md と shots/<TARGET-PROJECT-CODE>-<page-slug>/ が隣接して存在する
• 各行のステータスが verified、open、reopened のいずれかであり、検証待ちのものがない。また、verified の各行の証拠セルには要素レベルの証明が記載されている
• 返信は Suggested next skills (optional) のフッターで終わり、その後に何も続かない