実ビューポートのスクリーンショットとコンテキストなしのサブエージェントレビュー：コードだけではUIを評価できない理由
コードを書いたエージェントは、JSXのコンパイルが通り、Tailwindのクラス名が正しければ、「UIは完璧に実装できました」と自信満々に伝えがちです。しかし実際にブラウザーを開くと、長い見出しが3行に詰まっていたり、暗い背景に読めない暗灰色の文字が置かれていたり、要素がページの左半分に偏っていたりします。Oil UIでは「実際のブラウザーでスクリーンショットを撮る」ことと「コードの背景を知らない独立したサブエージェントにブラインドレビューさせる」ことを必須の受け入れ工程にしています。
重要なポイント
- ソースコードは画面ではありません。実際のブラウザーのビューポート（1440×900、390×844、1920×720など）でレンダリングされたピクセルだけが、デザインを評価する根拠になります。
- コードを書いたエージェントは自分の成果を贔屓して見ます。コンテキストを持たないサブエージェントを起動してスクリーンショットだけを見せれば、率直な指摘を得やすくなります。
- 3つの画面で検証します。原寸のページ全体画像でリズムを見て、200%の部分切り出しで整列と字重を確認し、文字をぼかした色面図でレイアウトの重心の偏りを確かめます。
- スクリーンショットで確認できるのは静的な見た目だけです。最後はブラウザーで実際にクリックと入力をしてタスクを完了し、状態のフィードバックが本当に機能するかを確かめます。
npx skills add oil-oil/oil-ui画像を読み取れるモデルと、ローカルブラウザーを実行できる環境が必要です。
モデルがコードだけを見てもレイアウトの重大な問題を見つけられない理由
コード上では、flex justify-between items-center は問題なく見えます。しかし左に28文字の実際の商品タイトル、右に3つの操作ボタンを置くと、幅390pxのブラウザーではボタンが押し潰されます。同様に、コード内の text-slate-400 on bg-slate-900 は一連の文字にすぎませんが、レンダリングすると人の目では読みにくい低コントラストの文字になります。
ギャラリー作品の際立った細部の多くは、実ビューポートのレビューから生まれています。車載画面「Yantu」（1920×720）は曲がり角が近づくとナビゲーションを自動で拡大し、音楽領域を暗くします。水泳ウォッチ「Splitwater」（198×242、DPR=4）は小さな画面に非常に大きな往復数だけを残します。チェスレッスン「Forkside」では、ナイトのフォークを正しく指すと2本の攻撃線が同時に点灯します。こうした状態を一つずつスクリーンショットで検証しなければ、コードだけではずれを見落としがちです。
| 検査方法 | 具体的な手順 | 主に検出する問題 |
|---|---|---|
| 100%の元のビューポートによるページ全体画像 | 1440×900（デスクトップ）または390×844（モバイル）で、ファーストビューと長いページ全体をキャプチャ | ファーストビューで主操作を見つけられない、各セクションの高さが同じで単調、下部の余白の不連続、スクロールのリズムが平坦 |
| 200%の部分拡大・切り出し画像 | ナビゲーション、テーブル行、フォーム入力領域、価格カードなどの高密度領域を2倍で切り出す | 1pxの罫線が重なって太く見える、数値列のずれ、内側余白のばらつき、小字のコントラスト不足 |
| 文字をぼかした色面構造図 | ページの文字をぼかすか縮小し、色面の分布と重みの対比だけを見る | 上部が重く見えるレイアウト、左右の重心の偏り、強調色の乱立、同じ大きさのブロックばかりになる問題 |
| 実際のクリックによるタスクレビュー | 動作中のページで切り替え、フォーム入力、スライダーのドラッグ、異常状態の発生を実際に行う | ボタンを押しても反応しない、ポップアップが下層の重要情報を隠す、エラー後に復帰できない、状態が同期していない |
コンテキストなしのサブエージェントによるブラインドレビューの仕組み
ページを書き終えたばかりの同じエージェントにスクリーンショットを自己評価させると、たいてい「階層が明確で、配色もモダン」と自分を褒めてしまいます。直前のプロンプトに書かれた理想的な意図を覚えているからです。
Oil UIのブラインドレビューは、この身内びいきを断ち切ります。メインエージェントは、キャプチャしたPNG画像と最小限の背景一文（例：「これはプラットフォームチーム向けの1440×900の運用障害対応画面です」）だけを新しいサブエージェントに渡します。ソースコードも設計意図も伝えません。サブエージェントは、初めてプロダクトを開く厳しいユーザーのように、どこが窮屈で、どこが不自然で、どこが読みにくいかを直接指摘します。
すべての必須状態を実際にキャプチャする
メインエージェントはヘッドレスブラウザーを起動し、対象サイズとDPRで、初期状態、インタラクションの展開状態、異常／完了状態を撮影します。
独立したサブエージェントでコンテキストなしのブラインドレビューを行う
スクリーンショットをサブエージェント（Claude CodeのTask subagentやCodexの独立したレビューセッションなど）に渡し、AIの定型表現に対するチェックリストと可読性チェックリストに沿って採点・指摘させます。
ブラインドレビューの問題リストに沿って修正し、新しい画像で再確認する
メインエージェントは指摘された具体的な位置と問題をもとにスタイルとレイアウトを修正し、再キャプチャで問題が消えたことを確認してからユーザーに納品します。
エージェントにスクリーンショットとブラインドレビューを実行させるプロンプト
ページの初稿ができ、「使えそうだが洗練されていない」と感じたら、次の指示をそのまま送れます。
Oil UIのフローに沿って、現在のページを実際のブラウザーでレビューし、コンテキストなしのサブエージェントによるブラインドレビューを行ってください。
1. ローカルブラウザーで1440×900（デスクトップ）と390×844（モバイル）を表示し、ファーストビュー、長いページ全体、[重要な状態1 / 状態2]の高解像度スクリーンショットを撮ってください。
2. 現在のコードのコンテキストを持たない独立したサブエージェントを起動し、スクリーンショットだけを渡してください。AIテンプレートの痕跡、文字サイズやコントラストの不足、整列や余白の窮屈さ、ファーストビューの重心が明確かを重点的に指摘させます。
3. サブエージェントのフィードバックに沿ってコードを一つずつ修正し、スクリーンショットを撮り直して比較検証してください。サブエージェントと画像読み取りに対応したClaude Code、Codexなどの環境で自動実行できます。
実際に動くギャラリー作品とプロンプト
1440pxまたは390pxのライブデモを開き、モデルとプロンプトが最終的なUIにどう表れたかを確認できます。
Nightwatch
運用監視・インシデント対応
中規模プラットフォームチーム向けの監視・オンコールツール（1440×900）。英語のインターフェースとし、サービストポロジー、レイテンシー、エラーレート、トラフィックのグラフ、最近のデプロイ、ログ、トレースを表示する。インシデント時には、アラート、現在のオンコール担当者、インシデントのタイムラインを示す。 中核はインシデントの進行。障害が起きているサービスと影響を受ける下流サービスがトポロジー上で明確に分かるようにする。時間範囲をドラッグすると、グラフ、デプロイマーカー、ログの時間がそろい、どのデプロイが問題を引き起こしたかを確認できるようにする。 正常な概要、アラートとトポロジー上の影響経路を強調した進行中のインシデント、エラーピーク時にログとトレースを開いて原因デプロイを特定する状態の3状態をデザインする。
作品とプロンプトを見る →
Yantu
車載インフォテインメント
車載インフォテインメント画面のメインインターフェース（1920×720、運転中に一目で読めること）。中国語のインターフェースとし、ナビゲーションマップ、再生中の音楽、空調、よく使う車両操作を表示する。 同じ画面内で優先度が移り変わることがこの作品の中核。通常は地図を主役にし、音楽と空調を小さな領域に配置する。曲がり角が近づくと、案内が自動的に拡大され、音楽が場所を譲る。空調を調整するときは温度スライダーが現れ、他の要素が暗くなる。見なくても正確に押せる大きさのボタンにする。実際の地図サービスではなく、地図を自分で描く。 色：夜間のブルーブラックを背景に、電光ブルーのナビゲーションルートを使い、琥珀色は警告と曲がり角の案内に限定する。ウォームホワイトやベージュは使わない。 巡航中、曲がり角への接近、空調調整の3状態をデザインする。1920×720、DPR=1でスクリーンショットを撮影する。
作品とプロンプトを見る →
Splitwater
水泳ワークアウト用ウォッチアプリ
プールでのワークアウトを記録するウォッチアプリ（各画面を198×242でデザインし、時計のケースやストラップは描かない）。英語のインターフェースとし、往復数、ペース、心拍数、休憩カウントダウン、水泳後のサマリーを表示する。 手首を一目見るだけで分かるように、各画面では一つの大きな数字を主役にする。1往復完了するたびに往復数が短く跳ねて更新される。休憩中はカウントダウンリングが一周し、振動でプールに戻る合図をする。画面が濡れるため、クラウンを回してロック解除し、その状態をインターフェースに表示する。 色：ウォッチ画面はピュアブラック、プールシアンをメインカラー、数字は白とする。暖色は使わない。 水泳中、休憩カウントダウン、ウォーターロック、一時停止と終了、ワークアウトサマリーの5画面をデザインする。1つのインタラクティブ画面を持つ `index.html` と、5画面を横に並べた `screens.html` を納品する。198×242、DPR=4でスクリーンショットを撮影する。
作品とプロンプトを見る →
Forkside
チェスタクティクスレッスン
レーティング800～1600のアマチュアプレーヤー向けのチェスタクティクス学習ウェブサイト（1440×900を基準とし、幅390ピクセルまでレスポンシブ対応）。英語のインターフェースとする。フォーク、ピン、スキュア、ディスカバードアタックなどの戦術を一度に一つずつ、盤面の段階的な解説と数問のパズルで教える。 中核は、解説に合わせて盤上に矢印とハイライトが段階的に現れること。ナイトがフォークのマスへ跳ぶなどの正しい手では、2本の攻撃線が同時に光るようにする。不正解の手では、単に「不正解」と言うのではなく、相手の具体的な応手を示す。駒と盤を洗練させ、デフォルトの駒アイコンではなく、画像生成または3Dレンダリングで素材を作る。 レッスン解説、パズル解答中、解答後に戦術を明示した状態の3状態をデザインする。
作品とプロンプトを見る →Oil UI Pro：最大3ラウンドで9/10を目指す厳密なブラインドレビューとクリック数のタスクレビュー
オープンソース版には1ラウンドの基本的なサブエージェントレビューが含まれます。Oil UI Proでは、最大3ラウンド、9/10を基準とする詳細なブラインドレビューの反復に加え、100% / 200%ズームのチェックリスト、文字を隠した色面構造の検査、クリック数を数える完全なブラウザータスクレビューを行えます。
npx github:oil-oil/oil-cli install oil-ui-proよくある質問
使用環境でローカルブラウザーのスクリーンショットを撮れない場合も、Oil UIを使えますか？
Oil UIの方向の発想、タスク分解、AIの定型表現を避けるルールは、コード生成の段階でも機能します。ただし、実際のブラウザーのスクリーンショットと画像を読む能力がなければ、レンダリング後のピクセルを確認できず、サブエージェントのブラインドレビューも実行できないため、細部の品質は下がります。できるだけローカルのPlaywrightやブラウザーツールを用意してください。
100%のスクリーンショットに加えて、200%の部分拡大が必要なのはなぜですか？
縮小された大きな画像では、1pxのずれ、二重罫線のにじみ、整列していない小さなアイコン、薄すぎる補助文字を見落としやすいためです。中心となるコントロールを200%に拡大して切り出すと、画像を読むモデルも、仕上がりを左右する細部を正確に指摘しやすくなります。
文字をぼかして色面だけで構造を見る利点は何ですか？
具体的な文字を読めなければ、人の目もビジュアルモデルも文の意味に引っ張られません。ページ全体の視覚的な重みが左上に集中していないか、主ボタンが周囲の乱雑な色面に埋もれていないかを一目で確認できます。
ブラインドレビューは何ラウンド行うのが適していますか？
日常的な機能ページなら、1～2ラウンドで明白な問題の多くを修正できます。公開するブランドサイト、中心となるプロダクトワークスペース、ギャラリーレベルの作品なら、Oil UI Proで最大3ラウンドのブラインドレビューと要素削減を行い、9/10を目指すと細部をより作り込めます。