figma-pixel-verify

Figma Pixel Verify

実行中の UI を Figma の更新可能なアーティファクト（Inventory + Spec）と照合して測定し、その合否の証拠を Verify セクション（または Spec のソースに対応するファイル）に記録します。不合格の行がある場合は、この実行中に修正して再測定します。実測値はレイアウト後の読み取り結果から取得します。Figma の expected は上書きしないでください。figma-pixel-implement のスキル本文は編集しないでください。

使用するタイミング

• figma-pixel-implement の実行後（または永続的な Inventory + Spec パスを残した、その他の Figma 実装作業後）
• ユーザーがピクセル単位の一致度／デザインへの忠実度／稿面との照合による検収を求めている場合
• 単独での使用：ユーザーから Figma の URL と実行中のプレビュー URL／ルートが提供された場合。測定前に、同じパス規則に従って最小限の Inventory + Spec を保存します

入力

1. 更新可能なアーティファクト — 実装時に使用したファイルパス。同じ列（state、mode、basis）を使用します。このセッション中に実装を行った後、テーブルが見つからないからといって、黙って再構築してハンドオフが完了したと主張してはいけません。FAIL として figma-pixel-implement に戻します。
2. 実行可能な UI — ドキュメントの表示面。優先順位は次のとおりです。更新可能なアーティファクトの Stories サブセクションにあるコンポーネントワークベンチのストーリー（または検出された Storybook 形式のワークベンチ）→ 軽量な分離ハーネス（ホスト／エンジン依存をスタブ化）→ 製品内のプレビュールート → アプリ全体／ブラウザーの起動（最も負荷が高いため、最後の手段）。計算済みスタイル API を利用できない表示面では、layout-probe を使用します。これは、出荷時に使用される親コンテナー（画面が使用するコンテナー）にコントロールをマウントし、レイアウトを実行してフレームを出力するコマンドです。親を指定せずにコントロールをレイアウトするコマンドは、測定にはなりません。
3. UI を開ける実行チャネル（storybook、isolated-harness、preview、full-app）の場合は、実行中の UI のスクリーンショットを撮影します。この実行中にその UI の png、jpg、jpeg、または webp を保存し、パスを記載してください。UI を開けない layout-probe では Screenshot: not-openable を記録し、画像を捏造してはいけません。画像は補助的な証拠です。数値によるチェックの代わりにはなりません。

ワークフロー（順序どおり）

1. 事前確認 — reference.mdの手順に従って測定チャネルを決定します。ドキュメント UI では、Stories サブセクションのストーリー → 検出されたコンポーネントワークベンチ → 製品内プレビュー → アプリ全体の起動（最終手段）の順に進みます。計算済みスタイル API がないサーフェス、またはドキュメントのすべての段階が利用できない場合は、layout-probe を使用します。これは、この実行でコマンドを実行し、出荷時の親要素（画面で使われるものと同じコンテナー）内にコントロールをマウントして、レイアウトパスを 1 回実行し、コントロールの幅、高さ、子フレームを出力するものです。親要素なしでコントロールをレイアウトするコマンドは測定ではありません。プロジェクトのツールチェーンで実行できる最小限のプローブが存在しない場合は作成して実行します。ワークベンチが存在しない場合は、採用に関する提案を 1 つだけ助言として記録します。ワークベンチが壊れている場合は、手順を下に進めてその旨を記録します。レポートにチャネル（storybook | isolated-harness | preview | full-app | layout-probe）を明記します。選択したチャネルに到達できることを確認します。Spec source（生きたアーティファクトのパス）を特定します。Inventory と Spec が、測定する行のリストそのものです。この実行ですでに Figma から実装していて、ファイルがない、または重要な行が欠けている場合は、Overall を FAIL とし、表を完成させるために figma-pixel-implement に戻ります。行をでっち上げて、引き継ぎが完了したと主張してはいけません。単独実行（今回実装を行わない）の場合は、implement のパス規約に従って最小限の inventory と spec を保存してから測定します。テーマの対象範囲（mode）とビジュアルの state を記録します。複数のテーマが対象の場合は、測定前に、実行中の UI でテーマを切り替える方法（data-theme、トグル、システム設定）を特定します。ブラウザチャネル（品質ゲート）： macOS で ego-browser スキル（またはそのインストールスクリプト）が利用可能で、CLI がすでに使える場合、または人の対応を待たずにこのターン内にインストールが完了する場合は、他のドキュメントチャネルより先に使用します。この製品の TaskSpace／CLI API をこのスキルにコピーしてはいけません。インストールに GUI での初期設定がまだ必要な場合は、その旨を記録し、このターンで次に利用可能な JS 評価または layout-probe チャネルに進みます。OS が macOS でない場合、スキル／インストール手順が存在しない場合、またはインストールが妨げられている場合は、別のチャネルを使用し、どのチャネルを使用したかを記録します。ego-browser がなくても verify は中止しません。
2. ソースの照合（ゲート） — 測定を始める前に、Figma ソース（取得したノードツリーデータおよび／または参照エクスポート）から、予想項目のリストを機械的に導出します。対象範囲内の各ノードの位置、サイズ、タイポグラフィ一式、コンテナーのプロパティ、兄弟要素間の間隔を、それぞれ予想項目にします。Spec 表と照合し、すべての予想項目が spec の行に含まれているか、理由を添えて out-of-scope として記載されている必要があります。不足項目は新しい spec 行として追加する（この実行で測定する行になります）か、明示的に out-of-scope とします。照合表（予想項目／網羅済み／追加行／対象外）を Verify レポートに記載します。照合が完了するまでは測定を始めてはいけません。対象範囲内のフレームに参照エクスポートがない場合、全体を FAIL とし、figma-pixel-implement に差し戻します。
3. 視覚確認 — モデルが画像を確認できる場合は、UI と Figma のスクリーンショットを取得し、目立つ不一致（誤ったコンポーネント、欠落したブロック、テーマのずれ、断片的な切り抜き／積み重ね表示）を記録します。視覚確認は補助的な証拠です。JS 評価またはレイアウトプローブを実行できる場合、視覚のみの比較では Overall PASS になりません。開けるチャネルでは、保存した実行中 UI のファイルを保持し、そのパスを記載します。UI を開けない layout-probe では not-openable と記録します。
4. ピクセル差分スイープ — 各参照エクスポートを、今回の実装のスクリーンショットと同じボックスに並べて比較し、ツールチェーンで可能ならピクセル単位の差分アーティファクトも作成します。領域ごとに確認します。見つかった差異はすべて、新たに測定する行か、記録済みの残差のいずれかにします。spec 表の外で見つかった差異は、このスイープで正当に検出されたものです。スイープのアーティファクト（並列画像および／または差分画像）を保存し、そのパスをレポートに記載します。開けるチャネルでスイープのアーティファクトがない場合、全体は PASS ではありません。
5. 数値測定 — 重要なビジュアルの各行について、実行中 UI をその行の state と mode に切り替えます（ブラウザチャネルを使った実際のポインターホバー／クリック／テーマコントロールを優先します。宣言型のストーリーエントリー（テスト ID、ノブ、自動アクション）も、その state に到達したものとみなします）。次に計算済みスタイルおよび／またはバウンディングボックスを読み取ります。layout-probe では、実測値はそのコマンドが出力したフレームです。expected に合わせてソースリテラルを書いただけでは、その行を測定したことになりません。セレクターは慎重に対応付け、安定したテスト ID がある場合は優先します。デフォルト状態の読み取りは、ホバー（またはその他の state）の行を満たしません。出荷済みリファレンスとのインタラクション：タスクテキストに figma.com または node-id= が含まれ、さらに 参考、match the existing、または same as も含まれる場合は、指定された既存コントロールの hover、focus、focus-within、open または expanded に関する定義済みルールを読み取ります。静止状態のルールと異なる各プロパティについて、その state の spec 行を追加します。静止フレームの読み取りでは、それらの行は合格になりません。テキスト、可視性、または項目数だけを確認するプローブでは、それらを測定したことになりません。異なるテーマの各 mode の行は、それぞれ別の判定対象です。out-of-scope: behavior の行では数値 PASS の主張をせず、ピクセル PASS ではなく動作として記載します。対象範囲内の複数行テキストノードはすべて、ボックスの測定だけでは不十分です。行数、各行のインク開始位置（レンダリングされた最初の可視文字の左端）、改行位置の内容、ぶら下げインデントまたは行内オフセットを測定し、行として記録します。ボックスのみの読み取りは、複数行ノードの配置を網羅したことになりません。
6. 比較 — reference.mdの許容誤差を適用します。各行に判定を付けます。未測定の重要なビジュアル行（JS 評価が利用可能なのに行をスキップした場合）はブロッキング要因であり、残差を根拠に Overall PASS としてはいけません。
7. 修正ループ — PASS でない行があれば、実行中 UI を修正し、この実行内で再測定してから実測値／判定列を更新します。全体が PASS になるか、測定コマンドが実行できなくなるまで続けます。安全上限は約 8 回です。上限に達した場合は、残差を記載して全体を FAIL とします。測定したボックスが仕様ではなくプラットフォームコントロールの本来のサイズと一致する場合は、次の反復でそのコントロールを custom-layout に切り替え、レイアウトパスで仕様のフレームを割り当てます。Spec の expected は変更しません。figma-pixel-implement スキルファイルにパッチを適用してはいけません。ピクセルの判定を人に求めて一時停止してはいけません。
8. 独立した再確認 — Overall PASS を記載する前に、独立した再確認を行います。新しいコンテキストでのエージェント実行、別のモデル、または作成者の Spec 表を参照せず Figma ソースから予想項目リストを再導出するブラインド再ソース確認のいずれかを実施します。方法、再確認者の識別情報、アーティファクトのパスを、レポートの Independent check: 行に記録します。独立したチャネルを利用できない場合は、試した方法と利用できない理由を記録します。実施していない確認を実施したと主張してはいけません。
9. レポート — 生きたアーティファクトの Verify セクション（または Spec source で指定された別ファイルのレポート）を記述します。テンプレートはreference.mdを参照してください。網羅状況（測定済み／inventory）、チャネルの明記（Channel: storybook | isolated-harness | preview | full-app | layout-probe）、およびプロジェクトで指定されたホストエンジンがワークベンチのブラウザーより古い場合は、任意でその差異に関する注記を含めます。この注記によって幾何学的な PASS を保留にしたり、人の作業が発生したりすることはありません。そのエンジンの構文に依存する行は、そのバージョンの下限に対応したランタイムまたはパーサーで測定します。そうしない場合、その行は未測定のままとなり、全体は PASS になりません。コンポーネントテストの結果は、補助的な証拠として引用できます。複数テーマが対象の場合は、テーマごとに報告します。この Verify セクションが、測定レポートを必要とするホストに提示するレポートそのものです。重要な対象範囲内のビジュアル行がすべて PASS または accepted-residual で、各実測値がこのターンにレイアウトして読み取った値を参照し、かつソース照合表が存在して完全であり、かつピクセル差分スイープのアーティファクトが記載され、かつIndependent check: の行（または試した方法を添えた利用不可の記録）がある場合に限り、Overall は PASS です。重要な行が未測定、MISSING-style、未承認の DRIFT、仕様でトークンが必須なのに HARDCODED、spec 自体が不完全、実測値がソースリテラルからコピーされている場合、または実行中 UI に次のいずれかが表示されている場合、Overall は PASS ではありません。Spec では透明／none なのに塗りつぶしがでっち上げられている、単一の Assets エクスポートに対してグラフィックが断片的に切り抜かれている、インスタンスのジオメトリと一致しない汎用ラッパー、Spec に Figma 変数が記録されているのに独自に作られたテキストカラーの別名、またはリモートのデザイン URLを参照したままの可視グラフィック。プローブコマンドが実行できない場合、全体は FAIL とし、そのコマンド名をレポートに記載します。PASS を報告する前に、このスキルディレクトリにある scripts/check-figma-verify-report.mjs を生きたアーティファクトに対して実行します。終了コード 0 が必須です。Verify セクションには Mounted in、Measurement command、Screenshot、および合格した各行の実測値と色をすべて含む ### Measurement excerpt のコードブロックが必要です。storybook、isolated-harness、preview、full-app では、Screenshot に、この実行で保存した空でない png、jpg、jpeg、または webp ファイルのパスを指定します。UI を開けない layout-probe では、Screenshot を not-openable とします。チェッカーはレポートファイルのディレクトリを基点に相対パスを解決し、ファイルが存在しない、または空の場合は拒否します。スクリーンショットファイルがあっても、数値による合格確認の代わりにはなりません。

判定の分類

判定	意味
PASS	正しい state / mode で測定され、期待値の許容範囲内です
DRIFT	測定可能ですが、許容範囲外です
HARDCODED	仕様でトークンが必須だったにもかかわらず、プロジェクトのトークン／変数ではなく、偶然またはリテラル値によって一致しています。トークンのマッピングが契約の一部だった場合に指摘してください
VARIANT	要求されたものではなく、文書化された別のバリアント（例：ホバー／ダーク）と一致しています
MISSING-style	プロパティを測定できません（ノード、スタイル、または利用可能なチャネルがありません）
accepted-residual	明示的に凍結された差異（担当者＋理由）です。Figma の期待値に対する PASS ではありません

ツールの用途（プラットフォーム非依存）

用途	エージェントが使用できるもの
UI を開く／プレビューする	macOS のインストールゲート通過後は品質チャネル。それ以外の場合は、エージェントがすでに利用できる別の JS 評価／プレビューチャネル
ビジュアル状態を切り替える	実際のポインターでホバー／クリックする、またはテーマコントロールを操作してからスタイルを読み取る
レイアウト済みフレームを読み取る	ページ内での JS 評価、DevTools のような API、またはフレームを出力するレイアウトプローブコマンド
スクリーンショット	ブラウザーまたは Figma のスクリーンショットツール（モデルが画像を認識できる場合は、ビジョン機能で確認します）
修正を適用する	ネイティブ編集ツールを使用してから、再測定する

品質チャネルのインストールが成功したら、測定にはそのチャネルを使用してください。インストールが不可能な場合は、別の JS 評価経路を使用できます。このスキルにサードパーティーのブラウザー API をコピーしないでください。

ドキュメントチャネルがない場合は、レイアウトプローブを実行して、出力されたフレームを読み取ってください。そのコマンドを実行できない場合は、数値の行を MISSING-style とし、不足しているコマンドを明記してください。また、ピクセル単位の PASS を主張しないでください。

関連性

スキル	境界
figma-pixel-implement	コードと永続的な Inventory/Spec を作成します。最終判定は担当しません
Agent-native Figma→code guidance / MCP fetch	測定の代わりにはなりません
Host PDCA workflows	インストール時に強く依存します。Figma UI が対象範囲に含まれる場合は呼び出してください。Verify セクション（または Spec のソースとなる同階層ファイル）がない場合、その検証段階は失敗します。spec-gap の FAIL は implement に戻ります
ego-browser（外部、macOS）	品質測定チャネルです。スキル／インストール経路が存在する場合はインストールしてください。frontmatter の依存関係ではありません。インストールできない場合は、機能を縮退させてください

落とし穴

• 測定可能だったにもかかわらず、スクリーンショットだけを根拠に PASS と判定する。
• 再測定せずに、調整を延々と繰り返す。
• 高 DPR で生じる ±1 CSS px のジオメトリ上の誤差を、DPR に触れずに失敗として扱う。
• マスクや currentColor の問題を黙って見過ごす。実装者がアセットのルールに違反していた場合は、色の DRIFT の根本原因として指摘する。
• デフォルトテーマだけを測定した後、モードごとの行を PASS と判定する。対象となる各テーマは、それぞれのテーマで測定する。
• デフォルト状態のスタイルを根拠に、ホバー状態の行を PASS と判定する。
• 重要な行が「未測定」のまま残差にしか記録されていないのに、全体を PASS と判定する。
• 固定された 18px と 16px の差を accepted-residual ではなく PASS として扱う。
• 継続的に更新される成果物の保存先があるのに、レポートをチャットにしか残さない。
• Spec の expected を実測値で上書きする。
• この実行で実装が完了した後、不足している spec を黙って再構築し、引き継ぎが完了したと主張する。
• 独自に作成した単色の塗りつぶし、葉のパスを重ねたアイコン、汎用の 16/24 シェル、独自のテキスト色エイリアス、またはリモートのデザイン URL に対して PASS と判定する。
• macOS で利用可能な品質チャネルの CLI を使わず、より精度の低いドキュメントチャネルだけで測定する。
• 別のチャネルやレイアウトプローブをこの実行中に動かせるのに、GUI のオンボーディングを待つ。
• expected と一致するソース内のリテラル値を、実測値として扱う。
• サードパーティー製ブラウザーの TaskSpace/CLI API をこのスキルにコピーする。
• ego-browser をインストールできないホストで、ego-browser が利用できないことを理由に検証を中止する。
• JS-eval が利用可能なのに、視覚情報やスクリーンショットだけを根拠に全体を PASS と判定する。
• 使用した測定チャネルを明示せずに判定を報告する。
• ワークベンチやエンジンフロアに関する注記を、幾何学的な PASS を保留したり、その行の完了を人に依頼したりする理由として扱う。
• 配信対象の親要素を一度もマウントしないレイアウトコマンドを測定として扱う。
• 開けるチャネルで、空でないスクリーンショットファイルを保存していないのに PASS を報告する。
• UI を開けないレイアウトプローブ用の画像を独自に作成する。
• ソースとの照合を省略する。すると測定対象の集合が、作成者が記憶して書き出した内容だけになってしまう。
• 開けるチャネルで差分スイープの成果物がないのに PASS を報告する。
• 同じコンテキストでの自己レビューを、独立した再確認として扱う。
• 複数行テキストノードのボックスだけを測定して、その配置の検証が済んだとする。