pixel-perfect

ピクセル単位の再現

スクリーンショット、画像、Figma のプレビュー／エクスポート、クリック可能なデモ、または公開中のウェブサイトをもとに、UI を可能な限り正確に再現するためのスキルです。

成果物はコードだけではありません。以下を含みます。

• 計測に基づく実装計画
• 詳細なビジュアル仕様
• その仕様を実装するコード
• レンダリング結果が参照元に近づくまで繰り返す検証ループ

このスキルは、正確な複製を目的としています。インスピレーションを得るためのものでも、再デザイン、整理、標準化、スタイルの解釈を行うためのものでもありません。

このスキルを使用する場面

ユーザーが次のことを望んでいる場合に使用します。

• デザインを正確にコピーする
• スクリーンショットから画面を再現する
• Figma のサイトやデモを正確にクローンする
• 余白、パディング、色、タイポグラフィ、レイアウトを詳細に一致させる
• 見た目を変えずに、デザインを別のフレームワークへ移植する

ユーザーが次のことを望んでいる場合には使用しないでください。

• デザインの再設計
• デザインの批評
• 「このような感じ」の大まかな実装
• 複製ではなく UX の改善

前提条件

• MCP サーバー：
  • Chrome DevTools MCP（推奨）、または Playwright MCP（代替）
• コマンドラインツール：
  • jq
  • awk
  • ImageMagick：magick（v7）、または convert + compare + identify（v6）

このスキルの使用方法

このスキルは、次の厳密な実行ループに沿って使用してください。

1. 参照元を一度計測し、具体的な仕様を作成する
2. その仕様に基づいて実装する
3. 参照元のアーティファクトと照合する
4. 一致していない箇所だけを変更する
5. 再度検証する

必要な問題がすべて解決済み（fixed、accepted_by_user、または renderer_only_drift）となり、検証ゲートに合格するまで、手順 3〜5 を繰り返してください。

基本ルール

1. 参照元を正解とします。
2. 再設計してはいけません。
3. 簡略化してはいけません。
4. デザインを「改善」してはいけません。
5. 明示的に求められていない限り、計測値を丸めた値や見栄えのよい値に置き換えてはいけません。
6. 計測した色、フォントサイズ、間隔、角丸、影をテーマのデフォルト値で置き換えてはいけません。
7. ソースを調査できる場合は、計測してください。
8. 必ずスクリーンショットに基づくビジュアル検証を完了してください。
9. 明らかな差異が残っているのに「十分近い」として終了してはいけません。
10. フレームワークの慣習より忠実さを優先してください。

規範用語

• MUST と MUST NOT は絶対要件です。
• SHOULD は原則として従うべき要件です。レポートで明確な根拠を示す場合に限り、変更できます。

優先順位

トレードオフが必要な場合は、次の順に優先してください。

1. 全体的なレイアウト構造
2. 外側のマージンとセクション間隔
3. 内側のパディングと間隔
4. タイポグラフィ、フォントサイズ、太さ、行の高さ
5. 色、枠線、角丸、影
6. フォントとアイコンのアセットの一致度
7. アイコンのサイズと配置
8. インタラクションの状態と細部

入力の優先順位

受け付ける入力の優先順位は次のとおりです。

1. Figma の検査可能なソース
2. 公開中のウェブサイト
3. クリック可能なデモ
4. 画像エクスポート
5. スクリーンショット

ルール：

• 利用可能なソースのうち、最も優先順位の高いものを主な計測元として使用します
• 必要に応じて、優先順位の低いソースは補足的なビジュアル確認にのみ使用します
• Figma に表現されていない動作や状態の詳細を確認する場合は、実行時のソースを使用します
• ソースが 1 つしか提供されていない場合は、そのソースを使用します

必須の出力

このスキルでは、実行中に次の4項目を作成する必要があります。

1. 短い実行計画
2. 測定に基づく詳細なUI仕様
3. コードによる実装
4. 検証結果と、残っている不一致（ある場合）

仕様を作成せずに、いきなりコーディングを始めてはいけません。

references/report-template.md のレポート見出しスキーマを使用してください。

次の2つの報告モードを使用してください。

• iteration モード：改善ループ中に使用（簡潔な要約のみを表示し、変更点や失敗項目だけを報告）
• final モード：完了時の引き継ぎに使用（情報を省略せず、完全なレポートを提示）

固定のトークン数制限は設けないでください。レポート全体を繰り返すのではなく、成果物の要約を使用して中間出力を簡潔にしてください。

タスクが完了したと判断した場合、エージェントは次のすべてを含む最終的なユーザー確認用の引き継ぎを必ず提示してください。

1. 実装が完了したと判断していることを明示する
2. 次の内容を含む、左右に並べた視覚的比較を示す：
   • 参照デザインの画像1枚
   • 実際にレンダリングされたアプリの画像1枚
3. 不足しているものがないか、ユーザーに直接確認を求める
4. 承認されない場合は、見落とした詳細を列挙するよう明示的に促す

参考資料

詳細な実行手順については、次の資料を参照してください。

• references/report-template.md
• references/responsive-scope-playbook.md
• references/measurement-playbook.md（インデックス）
• references/measurement-chrome-devtools.md
• references/measurement-image.md
• references/measurement-figma.md
• references/specification-playbook.md
• references/validation-playbook.md

ワークフロー

フェーズ1：ソースの種類を特定する

次のいずれに該当するか判断してください。

• ライブで検査可能なソース
• Figmaで検査可能なソース
• 静的なビジュアルソースのみ

ライブで検査可能なソースがある場合は、それを主要な測定ソースとして使用してください。 Figmaで検査可能なソースがある場合は、Figmaの検査データを主要な測定ソースとして使用してください。 画像しかない場合は、スクリーンショットに基づいて測定してください。

ソースの選択では、入力の優先順位に必ず従ってください。 優先順位の低いソースは、優先順位の高いソースが利用できない場合を除き、補足確認にのみ使用してください。

フェーズ2：レスポンシブ検証の対象範囲を選択する

実装を始める前に、必要なビューポートを選択してください。 references/responsive-scope-playbook.md に記載された決定的な対象範囲と分類ルールを使用してください。

最低限、次の要件を満たしてください。

• ユーザーがビューポートやデバイスを明示している場合は、それらのみを使用してください。
• 明示されていない場合は、ソースを分類し、プレイブックのデフォルトのビューポートセットを選択してください。
• ソースの分類、選択したビューポートセット、選択理由を計画に必ず記録してください。
• 選択したセットに含まれるすべての必須ビューポートで、検証に合格する必要があります。
• デフォルトから変更する場合は、その理由をレポートに明記してください。

フェーズ3：調査と測定

モードA：ライブで検査可能なソース

Chrome DevTools MCP などのブラウザーツールを使って、レンダリングされたUIを直接調査してください。 references/measurement-chrome-devtools.md に記載された正確な測定手順に従ってください。

次の項目を測定し、記録してください。

• ビューポートサイズ
• ページ幅と表示されているコンテンツ幅
• セーフエリアまたはブラウザーのインセット（該当する場合）
• 主要な要素のバウンディングボックス
• 親要素およびビューポートを基準とした x 座標と y 座標
• セクションとコントロールの幅および高さ
• 各辺のパディング
• 各辺のマージン
• 兄弟要素間のレイアウト上の間隔
• 計算後のフォントファミリー
• 計算後のフォントサイズ
• 計算後のフォントウェイト
• 計算後の行の高さ
• 必要に応じて文字間隔
• テキストの色
• 背景色
• グラデーション
• 境界線の幅
• 境界線の色
• 角丸
• ボックスシャドウ
• 使用されている場合は不透明度
• アイコンのサイズ
• 配置ルール
• スクロールの挙動
• スティッキーまたは固定配置の有無

次のスクリーンショットも撮影してください。

• ビューポート全体
• 各主要セクション
• 視覚的な情報が密集している各領域

DOMを検査できる場合、最初にスクリーンショットから値を目測で推定してはいけません。 先に測定してください。

モード B、スクリーンショットまたは画像のみ

デザインが画像でしか確認できない場合は、構造を推測し、視覚的に計測します。 references/measurement-image.md のスクリーンショットのみの場合の手順を使用してください。

以下を特定します。

• 対象のビューポートサイズ、またはその推定値
• 主なレイアウトコンテナー
• セクション間の相対的な間隔
• カードとコンテナー内のパディング
• テキストの階層
• フォントサイズの相対的な関係の推定
• 角丸の概算
• アイコンサイズの概算
• ピクセルから取得した色のサンプル
• グラデーションが見える場合はその色の変化点
• 配置パターンとグリッドのリズム

実装中にスクリーンショットを繰り返し比較し、不確かな値を調整します。

モード C、Figma ソース

ソースが Figma のプレビュー、またはインスペクトアクセス可能なファイルの場合は、Figma のインスペクトデータから計測します。 references/measurement-figma.md の Figma の手順を使用してください。

まずインスペクト値から計測し、その後、書き出したフレーム画像またはキャプチャしたフレーム画像で視覚的に確認します。

フェーズ 4、実行計画の作成

詳細な仕様を作成する前に、簡潔な実行計画を作成します。

この計画には、以下を必ず含めてください。

• ソースの種類
• 計測方法
• 実装対象
• 検証方法
• 既知のリスクまたは不確実な点

例：

Source: clickable demo
Measurement: Chrome DevTools MCP DOM inspection plus screenshots
Target: React Native screen on iPhone-sized viewport
Validation: simulator screenshots matched against reference
Risk: native font rendering may differ slightly from browser rendering

計画は簡潔に保ちます。これは実行計画であり、仕様書全体ではありません。

フェーズ 5、詳細な実装仕様の作成

コーディングを始める前に、計測に基づく UI 仕様を作成します。

元の参照資料を見なくても他のエンジニアが画面を実装できるほど、具体的な仕様にしてください。 フィールドレベルのスキーマと品質チェックには、references/specification-playbook.md を使用してください。

フェーズ 5 の目的：

• コーディング前に、計測に基づく完全な実装契約を作成する

必須セクション：

1. 画面メタデータ：対象環境と全体のレイアウト動作を定義します。
2. コンポーネント階層：構造ツリーと、実装および検証で使用する名称を定義します。
3. セクションごとの計測値：主要な各セクションのジオメトリ、間隔、配置、表面のスタイルを定義します。
4. タイポグラフィ仕様：主要なテキスト要素の正確なレンダリングルールを定義します。
5. カラーパレット：画面で使用する具体的な色とグラデーションを定義します。
6. 境界線と角丸の仕様：境界線、角丸、区切り線の処理を定義します。
7. アイコン仕様：アイコンのアセット、サイズ、配置、スタイルの詳細を定義します。
8. アセットの同等性とユーザーの判断：フォントやアイコンの利用可否、およびユーザーが承認した代替案を記録します。
9. インタラクションと状態に関する注記：状態に応じて変化する表示やレイアウトの動作を定義します。
10. プラットフォーム変換に関する注記：再設計を行わずにレンダラーへ変換する際の制約を記録します。

各セクションの必須フィールドと出力例については、references/specification-playbook.md を使用してください。 実装を開始する前に、必須の仕様セクションを 10 項目すべて用意してください。

フェーズ 6、受け入れ契約（実装前に必須）

実装を開始する前に、レポートに次の項目を含む受け入れ契約を記載しなければなりません。

• 必ず一致させる項目の一覧：譲れないデザイン上の決定事項に注釈を付けたもの
• 無視する項目の一覧：許容される不一致を明示したもの
• 許容されるプラットフォーム間の差異：レンダラーの違いに限った差異の許容範囲

ルール：

• この契約を記録する前に実装を開始してはなりません。
• ユーザーが注釈付きの比較スクリーンショットを提供した場合、その注釈を必ず 必ず一致させる項目の一覧 に反映します。
• 画面がデータ駆動型の場合、文言やコンテンツの不一致がレイアウト、間隔、はみ出し、または折り返しに影響しない限り、それらの不一致は除外することが望ましいです。
• 除外事項はすべて 無視する項目の一覧 に明示的に記載します。

フェーズ 7、仕様に基づいて実装する

仕様を信頼できる唯一の情報源として、コードを記述します。

ルール：

• 一度に 1 つのセクションを実装します
• 明示された値を使用します
• 外観が変わる場合は、フレームワークのデフォルト設定を避けます
• 任意の測定値をスペーシングスケールに正規化しません
• 実際の色を近似するテーマカラーに置き換えません
• フォントサイズを「より標準的な」値に変更しません
• ボタンをよりバランスよく、またはモダンにしません
• 詳細を削除したり追加したりしません
• 正確なアセットが見つからない場合に、代替フォントやアイコンパックを自動選択しません
• 代替アセットを実装するのは、仕様にユーザーの明示的な承認が記録された後に限ります
• 参照元で認識できるほど異なるアイコンファミリーが使用されている場合は、そのアイコンファミリーを採用するか、本格的な実装に着手する前にユーザーの明示的な承認を得なければなりません

23px や 18px のような不規則な値が指定されている場合も、そのまま使用します。

フェーズ 8、実行してキャプチャする

正しいターゲット環境で実装を実行します。

実行計画で定義された環境設定を使用します。検証中にターゲット環境を切り替えないでください。

実行チェックリスト：

• 計画からターゲットの種類（web、react-native、またはその他の宣言されたターゲット）を確認します
• スクリーンショットのキャプチャに適した安定した実行モードでターゲットを起動します
• ターゲットのフォントとアイコンアセットが、承認済みのアセットの同等性に関する決定と一致していることを確認します
• 可能であれば、キャプチャ前にアニメーションやトランジションを無効にし、フレームのばらつきを抑えます
• 計画で宣言された各必須ビューポートを正確に設定します
• 各ビューポートで必須のスクリーンショットをすべてキャプチャします

選択したビューポートセット内の各必須ビューポートについて、次のスクリーンショットをキャプチャします。

• 画面全体
• 各主要セクション
• 参照元と見た目が異なる領域

各パスでは、計画で宣言された正確なビューポートサイズを使用します。 ビューポートサイズは計画と正確に一致しなければなりません。 各ビューポートで必須のスクリーンショットをキャプチャしなければなりません。

アーティファクトの出力要件：

• 各ビューポートについて、キャプチャアーティファクトと検証入力ファイルをディスクに保存します
• 各ビューポートについて、./scripts/validate-visual.sh を実行し、JSON 出力（例：validation/<viewport>.json）を保存します
• バリデーターの JSON アーティファクトを、数値の信頼できる唯一の情報源として扱います

フェーズ 9、ビジュアル検証

必須の各ビューポートで、実装のスクリーンショットを参照画像と比較します。

特に以下を確認します。

• 上部の余白
• ページの左右のパディング
• カードの幅
• セクション間の余白
• カード内部のパディング
• テキストサイズの差異
• テキストの太さの差異
• 行の高さの差異
• 色の誤り
• 角の丸みが強すぎる、または不十分
• シャドウの不一致
• ボタンの高さの不一致
• アイコンの配置の不一致
• 行の密度の不一致
• 配置のずれ

客観的な差分チェックも実行し、数値結果を記録してください。 references/validation-playbook.md の検証フローとレポート形式を使用してください。 LLM に提示する更新では、まず ./scripts/summarize-validation.sh を使って検証成果物を簡潔なサマリーに投影してください。

検証プロファイル：

• lenient（明確な理由がある場合に限り使用可能）
• portable（異なるレンダラー間での作業におけるデフォルト）
• strict（同じレンダラーでの作業におけるデフォルト）
• ultra（オプトインのみ。デフォルトでは使用しない）

プロファイルの選択ルール：

• ソースとターゲットが実質的に同じレンダラーとフォントスタックを使用する場合、デフォルトで strict を使用します
• ブラウザーから React Native など、ソースとターゲットでレンダリング方法が異なる場合、デフォルトで portable を使用します
• ultra は、ユーザーが明示的に指定し、条件が統制されている場合（同じレンダラーのバージョン、同じ OS、同じ DPR、同じフォント、同じキャプチャーパイプライン）に限り使用します
• より高い忠実度での一致を妨げる制約がある場合に限り lenient を使用します。具体的な阻害要因と、より厳しいプロファイルが達成不可能な理由を記録してください

portable の解釈：

• portable では、レンダラーレベルの差異のみを許容しなければなりません
• portable では、注釈付きのデザイン上の決定事項を「Must-match list」で緩和してはなりません

注記付きの問題の解決：

• 注記付きのすべての問題は、fixed、accepted_by_user、renderer_only_drift のいずれか1つのステータスで解決しなければなりません
• 検証レポートには、注記付きの問題ごとに yes/no のチェック項目を含めなければなりません
• 検証レポートには、component、property、desired value、actual value、drift、result、reason の列を含むコンポーネントプロパティ表を含めなければなりません
• 表の各行の結果は、good、bad、bad_with_reason のいずれかでなければなりません
• renderer_only_drift には簡潔な理由を含めなければなりません
• 必須のステータスで解決されていない注記付きの問題がある場合、レポートで validated と記載してはなりません
• 最新のビジュアル変更後に更新されていない場合、レポートで validated と記載してはなりません

実行のたびに、メトリクスを報告する前に、選択したプロファイルとその選択理由を報告してください。 実行のたびに、必須のすべてのビューポートについて、ビューポートごとのメトリクスを報告してください。

LLM への入力投影ルール：

• 反復ループでは、モデルに投影サマリー（失敗したチェック、主な差異、差分、次のアクション）のみを提示してください
• 特定の不一致を解決するために対象を絞った一部のデータが必要な場合を除き、検証 JSON 全体を再入力しないでください
• 追加の詳細が必要な場合は、対象を絞った一部のデータ（単一のビューポート、単一の問題 ID、または特定のチェックタイプ）のみを読み込んでください

フェーズ 10：調整

目に見える差異がなくなるようにコードを調整します。

差異から仕様の不足や誤りが判明した場合は、仕様を更新してください。

以下を繰り返します。

• 実装する
• 実行する
• キャプチャする
• 比較する
• 調整する

明らかな差異がなくなるか、プラットフォーム上の制約によって完全な再現が不可能になるまで続けます。

最後の実質的な UI 編集の後に、少なくとも 1 回の完全な capture -> compare -> fix -> re-capture ループを必ず実行してください。 調整ループは少なくとも 1 回実行し、10 回を超えて実行してはいけません。

10 回のループ後も未解決の差異が残る場合、レポートには以下を含む詳細な未解決事項のセクションを記載する必要があります。

• 未解決の問題それぞれ
• 現在の望ましい状態と実際の状態
• 試したこと
• 問題の解決が難しい理由
• レンダラーのみ、アセットの制約、データの制約、実装上の制約のいずれが原因と思われるか
• 問題ごとの推奨される次のアクション

作業が阻まれた場合は、その制約と残っている差異を記録してください。

反復レポートのルール：

• 各調整ループでは、projection の出力から iteration レポートブロックを生成する必要があります
• iteration レポートには、変更されたステータスと不合格の行のみを含めることが推奨されます
• handoff の final レポートモードでのみ、レポートの全セクションと網羅的な表が必要です

完了の定義

以下のすべてを満たした場合にのみ、このスキルは完了です。

1. 簡潔な実行計画が存在すること。
2. 測定値に基づく詳細な UI 仕様が存在すること。
3. UI がコードで実装されていること。
4. レンダリング結果を参照画像と視覚的に比較していること。
5. プロファイル選択ルールに従って検証プロファイルを選び、その結果をレポートに記録していること。
6. 客観的な検証指標を記録し、選択したプロファイルで必要な閾値をすべて満たしていること。
7. lenient を使用する場合、障害となった要因とその理由を明示的に記録していること。
8. フォントとアイコンのアセットの一致状況を記録し、フォールバックの使用には明示的なユーザー承認を記録していること。
9. 受け入れ条件に Must-match list、Ignore list、Portable-allowed drift が含まれていること。
10. ユーザーが比較用としてマークしたスクリーンショットを提供している場合、それらを主要な検証資料として使用していること。
11. マークされた問題をすべて、理由を付けて fixed、accepted_by_user、または renderer_only_drift として解決していること。
12. 最新の視覚的な変更の後に検証レポートを更新していること。
13. 最後の実質的な UI 編集後に、少なくとも 1 回の完全な capture -> compare -> fix -> re-capture ループを実行していること。
14. 検証レポートに、検証した各プロパティの望ましい値、実際の値、差異、結果を含むコンポーネントプロパティ表があること。
15. 選択したビューポートセットに必要なすべてのビューポートで検証に合格していること。
16. 余白、タイポグラフィ、色、境界線の角丸、配置、セクションのサイズに明らかな差異が残っていないこと。
17. 最終回答に「完了したと考えています」という明示的な記述があること。
18. 最終回答に、ユーザーが確認できる参照画像と実際のアプリの画像を並べて含めること。
19. 最終回答で、完了しているか確認し、未完了の場合は見落とした点を指定するようユーザーに求めること。

「おおむね似ている」では完了ではありません。 「十分よい」では完了ではありません。 「フレームワークの慣習に沿っているが、少し異なる」では完了ではありません。

避けるべき失敗

以下のことをしてはいけません。

• デザインをざっと見ただけで、記憶を頼りに実装する
• 仕様を省略する
• なんとなく適切だと考えて、あらゆる箇所に汎用的な余白として 16 を使う
• 近いという理由でデフォルトのフォントサイズを使う
• 測定した色をテーマカラーに置き換える
• ユーザーの承認なしに、フォントやアイコンのフォールバックを自動的に選ぶ
• 最新の視覚的な変更より前の古いレポートを使って、検証済みと主張する
• 比較用としてマークされたスクリーンショットの問題を、fixed、accepted_by_user、または renderer_only_drift として解決せずに無視する
• 主観的な UX 改善を加える
• 最初の実装だけで終える
• スクリーンショットを比較せずに成功を宣言する
• 明示的にユーザーへ確認を求め、見落とした点について尋ねることなく終了する

呼び出し例

Use pixel-perfect to copy this screen exactly
Use pixel-perfect to recreate this Figma preview in React Native
Use pixel-perfect to clone this clickable demo without redesigning it
Use pixel-perfect to port this web design into native while preserving the look

期待される動作の概要

このスキルは、「このデザインをコピーして」といった曖昧なプロンプトを、厳密なプロセスに変換します。

• ソースを調べる
• ソースを計測する
• 計画を立てる
• 詳細な仕様書を作成する
• 仕様書に基づいて実装する
• 対象を実行する
• スクリーンショットを撮影する
• リファレンスと比較する
• 一致するまで調整する

このスキルは、エージェントに創造性を求めるものではありません。正確さを求めるものです。