UI プレビューゲートは何をしますか？

画面を変更するすべての変更は、4つのフェーズを経ます。変更が小さく見えてもフェーズを省略しないでください。承認者が承認するのは画像です。

現在の状態を検査する
プレビューを表示し、承認を得る（作業開始前）
実装する
結果が承認されたプレビューと一致することを確認する（作業終了後）

例外：意図した画面を変更しないバグ修正は、フェーズ2をスキップしても構いません。ただし、ユーザーに違いが見える場合は、修正前後の画像を添付して報告してください。以前とは異なる画面、ダイアログ、シート、メッセージを表示することは、既存のコンポーネントを再利用する場合でも、画面変更であり、この例外には該当しません。先にフェーズ2の承認を取得してください。

適用時期

依頼されることなく適用してください。ユーザーがこのスキルを明示的に指定する必要はありません。
最初のターンだけでなく、すべてのターンでチェックしてください。サポート、調査、レビュー、バグ報告として始まった会話でも、途中で「画面をこうしたらどうだろう？」という方向に変わることがあります。そのターンからこのスキルが適用されます。
「どう思う？」「何かアイデアある？」「どのように見える？」という画面に関する質問は、提案とみなされます。
一度開始したら、承認された変更が検証（フェーズ4）されるか、ユーザーが変更を断念するまで、以降のターンでもこのスキルに従い続けてください。
散文やケーステーブルだけで回答された提案は不完全です。同じ返信に変更前後の画像を添付するか、まだ作成できない理由と作成可能な時期を記載してください。
UI変更が承認待ちまたは進行中の間は、進捗報告、オプション一覧、それに関する質問にも、変更前後の画像を再度添付するか、画像パスを記載してください。変更後の画面を散文だけで説明しないでください。

スキルは通常、ターンごとにその説明から選択されるため、会話の途中のターンが見落とされる可能性があります。このファイルの隣にある agent-instructions.md は、エージェントが毎ターン再チェックするための短いルールで、AGENTS.md / CLAUDE.md に追加してください。

1. 現在の状態を検査する

記憶や推測から提案しないでください。

実行中の開発サーバーまたはビルドから実際の画面をキャプチャしてください。デフォルトのビューポートはモバイル 375px 幅です。変更がデスクトップレイアウトにも影響する場合は、デスクトップも追加してください。
それをレンダリングするコード（タブ/ルート構造、コンポーネント、現在のコピー）を読んでください。
証拠を path/to/file:line とキャプチャで記録してください。現在のUIに関するすべての主張は、これらのいずれかを指している必要があります。
既存のコンポーネント、パターン、コピーを優先してください。新しいパターンが必要な場合は、既存のものが適合しない理由を述べてください。

キャプチャには scripts/capture.mjs（スクリプト参照）を使用して、変更前のショット、プレビュー、検証ショットが同じビューポート、スケール、データ状態を共有するようにしてください。

ケース一覧（最初のプレビュー前、依頼なしで実行すること）

承認者は、「タップした後はどうなるの？」や「データがあったらどうなるの？」と尋ねる必要があってはなりません。プレビューを送信する前に、コードと実際のアプリから、変更が影響するすべてのケースをリストアップしてください。

変更される画面の状態: 空 / データあり / 多数のアイテム（切り詰め、「すべて表示」）/ 読み込み中 / エラー / プラン、ロール、権限によってロック / その他の構成（シングルストア vs マルチストア、機能フラグ）。
新規または変更されたコントロールから到達するすべての画面: フォーム、ピッカー、ダイアログ、バリデーションエラー、キャンセル/戻る、確認、成功、失敗。
アクション後: アクション完了後の元の画面の見え方（新しいアイテムの表示、カウンターの変化）、および元に戻す方法や編集方法。
同じデータを表示する他の場所: 一覧、詳細画面、履歴、レポート、エクスポート、その他のプラットフォーム（デスクトップ、Web、LINE、顧客側）。それぞれを「変更あり」「変更なしだが新しいデータを表示」「影響なし」にマークしてください。

最初のプレビューとともに、ケースのテーブルを送信してください：ケース、ユーザーが見るもの、再利用される既存コンポーネント、画像ステータス（添付済み / テストデータが必要 - 準備方法 / 範囲外 - 理由）。プレビューはバッチで届く場合がありますが、最初のメッセージは常に完全な一覧を示し、1つの画像の承認は、まだ表示されていないケースの承認を意味するものではありません。質問を列挙するだけでなく、未決定事項に対して適切なデフォルト値を提案してください。

2. プレビューを表示し、承認を得る

実装コードを書く前に、承認者に1つのサイドバイサイド画像と短いサマリーを表示し、明示的なOKを待ってください。

画像ルール:

左側に変更前、右側に変更後を1つの画像にまとめてください。
変更された領域をすべてボックスで囲んでください：変更前は赤、変更後は緑。
ボックスをペアにしてください：すべての変更に対して、両側の該当する位置にボックスを配置します。追加の場合は、変更前の挿入ポイントに細いマーカーをギャップに配置します（"pad": 0、小さな h）。削除の場合は、変更後のギャップにマーカーを配置します。欠落した要素の代わりとして、無関係な隣接要素（例：下の行）をボックスで囲まないでください。
ボックス座標は、capture.mjs --selector の出力（または、入力後に開くダイアログなど、状態にインタラクションが必要な場合は、e2eテストでPlaywrightを使用して測定した要素の矩形）から取得し、目視では取得しないでください。送信前に合成画像を確認し、各ボックスがターゲットに正しく配置されていることを確認してください。
両側で同じビューポート、スクロール位置、サンプルデータを使用してください。
画面が状態（データ有無、エラー、空、ロール別、構成別）によって分岐する場合は、変更が影響するすべての状態に対して1組の変更前後画像を表示してください。表示しなかった状態は承認されません。状態ごとに1つの画像を作成し、1つの画像に複数のペアを絶対に配置しないでください。
ステージング（コードを一時的に変更して開く）によってのみ到達可能な実際の画面は、仕様に "staged" を含め、画像にその旨が表示されるようにしてください。
送信前チェック: compose.mjsはこれらのルールに違反する仕様を拒否し、チェックリストを出力します。画像を開き、各項目に回答し、その回答をメッセージに含めてください（テンプレート参照）。項目が不合格の場合は、修正して再合成してください。テキストで不合格項目を説明しないでください。
以下の画像ポリシーに従ってください。

画像ポリシー

ユーザーまたはプロジェクトは、モックアップを許可するかどうかを決定します。リクエストまたはプロジェクトの指示（AGENTS.md、CLAUDE.md、コントリビューション用ドキュメント）から選択肢を探してください。何も記載がない場合は、real-only を使用してください。キャプチャが難しいからといって、自分で mockup-allowed に切り替えないでください。代わりに確認してください。

real-only（デフォルト）: 両側とも実際の実行中のアプリの全画面キャプチャです。プロトタイプブランチまたはフィーチャーフラグの背後で変更後側を構築し、キャプチャしてください。切り取ったり貼り付けたりした断片、コードや手作業（生成画像を含む）で描き直したモックアップ、行を半分に切ったキャプチャ、実際のアプリが表示するものと異なるダミーデータを使用しないでください。
mockup-allowed: 変更後側は、ユーザーまたはプロジェクトが明示的に許可した場合にのみモックアップを使用できます。変更前側は依然として実際のキャプチャです。すべてのモックアップパネルに合成仕様で "mockup": true をマークし、画像にその旨が表示され、承認リクエストに記載されるようにしてください。モックアップはフェーズ4の証拠としてカウントされません。検証では常に実装された画面の実際のキャプチャを使用します。

より厳格なプロジェクトルールは、より緩やかなユーザー設定よりも優先されます。両者が競合する場合は、その旨を指摘し、プロジェクトルールに従ってください。

サマリー（references/templates.md 参照）:

どこで: どの画面/タブの、画面上のどこに変更が現れるか
何が可能になるか: ユーザータイプ別（例：管理者、顧客）
何が変わらないか: 影響を受けるプラットフォーム/サーフェス

承認は、表示された内容に正確に適用されます。それ以外の部分は、新しいプレビューが必要です。

3. 実装する

承認されたプレビューに従って構築してください。実装中に目に見える逸脱（レイアウト、コピー、動作、新しいプラットフォームへの影響）が生じた場合は、その差分をリリースせずに、更新されたプレビューを持ってフェーズ2に戻ってください。

これには、コードレビューへの対応として行われた小さなコピー編集や修正も含まれます。修正が承認された画像を超えてユーザーの見るものを変更する場合は、停止して最初に新しいプレビューの承認を取得してください。後からテキストで報告してもカウントされません。

4. 承認されたプレビューに対して検証する

コード差分だけで完了を報告しないでください。

プレビューと同じキャプチャ設定と状態を使用して、実装された画面を再キャプチャしてください。
検証画像を合成してください：承認されたプレビュー | 実際の結果。約束された各変更をボックスで囲んでください。承認されたプレビューからのすべての差異を、たとえ小さなずれでも琥珀色でボックスで囲んでください。テキストだけで説明された差異は検証されません。
項目ごとにチェックしてください：
- 約束されたすべての変更が存在し、プレビューと一致していること
- 「変更しない」とリストされたすべてのものが変更されていないこと
- ボックスで囲まれた領域以外で、要素が移動、折り返し、溢れていないこと
- 変更されたインタラクションが、レンダリングされるだけでなく、実際に動作すること e2eテストの合格は動作を確認するだけです。変更がないように見える各状態の画像チェックを代替するものではありません。
判断してください：
- 一致：検証画像とチェックリスト結果を報告してください。
- 承認された意図の範囲内の軽微な不一致：修正し、再キャプチャし、再チェックしてください。
- 承認された内容を変更する不一致：報告し、再度承認を取得してください。

検証できなかったもの（プラットフォーム、デバイス、実際のデータ）は、完了とせずに別途リストアップしてください。

スクリプト

両方のスクリプトは Node 18+ と Playwright が必要です（npm i -D playwright && npx playwright install chromium）。PLAYWRIGHT_MODULE をモジュールパスに設定すると、既存のインストールを再利用できます。

画面をキャプチャし、要素のボックス座標を取得する：

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

セレクタの矩形をCSSピクセルで出力し、boxes として貼り付け可能です。

JSON仕様からパネルを合成する：

node scripts/compose.mjs spec.json

仕様形式、トーン、検証レイアウトは、references/compose-spec.md にあります。

UI プレビューゲート