ui-verification

UI 検証

ブラウザーセッションを担当します。このリポジトリ内のほかの UI スキルは、ソースを調べてユーザーにどう見えるかを推測しますが、このスキルはページを読み込み、実際に測定します。

• 対象： アプリの起動、ブラウザーを使った操作、実行時にルールを判定するプローブの実行です。具体的には、計算済みボックス、注入した障害、観測したレイアウトシフト、スクリプトによる Tab 操作、テーマごとの axe スキャンなどです。出力は、ルール ID に対応付けた、再現可能な証拠付きの所見と、修正後に問題が解消したことを確認する再実行です。
• 対象外： ソースを読んで不具合を見つけたり、重大度やリリース可否の判定を下したりすること（どちらも ui-design の Audit モードが担当します）、UI の構築やスタイル変更（ui-design の Build）、恒久的なテストスイートの作成（Playwright テストを作成してください）、アプリ全体で永続的に使う検証 CLI、doctor コマンド、機能マップの構築や保守（app-verification を名前で呼び出してください）、永続的なピクセルベースライン承認ワークフロー（Chromatic、Percy）、および現場でのパフォーマンス計測（RUM または CrUX。Lighthouse はラボ用ツールです）。

この役割分担が重要です。静的監査では、コードがどう動くかを推測して報告します。しかし、擬似要素ですでにヒット領域が 44px に広がっている 40px のコントロールや、何にも接続されていない再試行ボタンは確認できません。このスキルではそれぞれを再現するか、問題ではないことを確認するため、所見を確信度ではなく測定結果とともに提示できます。

目次

• 実行するタイミング
• プローブ一覧
• 進捗チェックリスト
• 1. セッションを確立する
• 2. プローブセットを選択する
• 3. プローブを実行する
• 4. 各所見を判定する
• 5. 解消を確認する再実行
• 6. レポート
• 誠実性に関するルール
• 注意事項
• 関連スキル

実行するタイミング

状況	このスキルで行うこと
ui-design の監査で所見が出され、ユーザーが確認を求めている	references/rule-coverage.md で、該当するルール ID に対応するプローブだけを実行します
監査は実施されておらず、ユーザーがルートまたは実行中のアプリを指定している	機能を検出し、解決したルートに対して一連のテストをすべて実行します
再現済みの所見に対する修正が適用されたばかりである	解消を確認する再実行のみを行います（ステップ 5）
テーマや幅を変えたキャプチャを求められている	probes/theme-locale-matrix.md を確認し、その後、以下の目視レビューを行います
UI の変更または指定されたスクリーンショットの状態のレビューを求められている	状態をそろえた変更前後の確認と、疑わしい重複の調査について、references/visual-review.md を読みます
design-system.md にスケールが記載され、その値を確認する必要がある	実際のページで計算済みスタイルから記載値を読み取ります。ビルド時に上書きされてブラウザーに反映されないテーマ値は対象外です

ここでは重大度やリリース可否の判定は行いません。再現した所見を証拠とともに引き渡し、ui-design の references/ship-readiness.md で重大度を判定してもらいます。同じ所見を 2 つのスキルがそれぞれ判定すると、重大度の基準が食い違う原因になります。

プローブカタログ

各ファイルは1つのプローブについて説明します。測定内容、ドライバーの呼び出し、誤検出を防ぐための確認事項、返されるエビデンスの形式を記載しています。

プローブ	測定内容	主な対象
probes/axe-scan.md	ルートとテーマごとの axe-core 違反。計算済みのコントラストを含みます	コントラスト、アクセシブルネーム、ランドマーク
probes/target-size.md	表示されているすべてのインタラクティブ要素のバウンディングボックスと実効ヒット領域	interaction-target-size
probes/focus-walk.md	Tab キーによるスクリプト化された移動、フォーカスリングのピクセル差分、ダイアログのフォーカストラップと復元	focus-*、interaction-focus-visible、interaction-keyboard-operable
probes/layout-shift.md	データレスポンスを開いたまま取得した、原因が特定された layout-shift エントリー	states-layout-shift、perf-image-dimensions-and-priority
probes/viewport-stress.md	320px 以上の幅、および文字列を3倍にした場合の水平オーバーフローとテキストのクリッピング	layout-long-content-safety、mobile-viewport-scaling
probes/failure-injection.md	データリクエストが 500、[]、不正な形式、または無応答を返した場合の表示内容	states-no-error-state、states-no-empty-state、async-*、microcopy-*
probes/theme-locale-matrix.md	ビューポート、テーマ、疑似ロケール、文字方向を変えて同じルートをキャプチャします	dark-i18n-untested、dark-i18n-rtl-untested
probes/console-network.md	コンソールエラー、ページエラー、リクエストの失敗、ハイドレーション不一致の警告	ハイドレーション不一致、気づかれないランタイムエラー
probes/web-vitals.md	原因要素を特定した LCP、CLS、スクリプト化された操作での INP	パフォーマンスの原因特定。予算の判定は行いません

進捗チェックリスト

Verification progress:
- [ ] Step 1: Establish the session (references/session-setup.md): driver, build mode, base URL, auth, resolved routes
- [ ] Step 2: Select the probe set from handed-over rule ids (references/rule-coverage.md) or from the routes
- [ ] Step 3: Run each probe; record evidence artifacts before interpreting any of them
- [ ] Step 4: Decide each finding reproduced / not-reproduced / unknown; repeat timing-sensitive or inconsistent results when needed
- [ ] Step 5: For each fix applied, re-run the identical probe and record clearedBy
- [ ] Step 6: Emit the verification block per finding (references/evidence-output.md), then render
- [ ] Step 7: List probes skipped and why. A probe that could not run is never a pass

1. セッションを確立する

references/session-setup.mdを読んでください。ここでは4つの項目を確認します。どれか1つでも誤ると、それ以降のすべてのプローブが無効になります。

• ドライバー。 リポジトリで実行できる場合は Playwright、できない場合は Chrome DevTools のブラウザーツールを使います。4つのプローブではリクエストのインターセプトとネットワーク制御が必要なため、これらに対応していないドライバーでは実行できません。
• ビルドモード。 パフォーマンスとレイアウトシフトのプローブは本番ビルドに対して実行します。開発モードの数値はバンドラーを測定したものです。障害注入とフォーカスのプローブは開発モードでも問題なく実行できます。
• 認証とシードデータ。 ログインが必要なルートでシード済みセッションがない場合、結果は合格ではなく unknown になります。
• ルート。 差分を URL に対応付けます。到達可能なルートがないコンポーネントは、リポジトリに Storybook があればそこを使い、なければ unknown になります。

アプリが起動しない場合は、ここで中止してください。セッションなしで検証を実行しても検出結果はなく、その結果は報告対象であり、問題がないことを示すものではありません。

2. プローブセットを選択する

ルール ID の一覧を渡された場合（通常は ui-design の監査によるもの）：references/rule-coverage.md を開き、各 ID に対応するプローブを選んで、それらだけを実行します。プローブがない ID はソースのみの検出結果として扱い、変更せずにそのまま引き継し、その旨を明記します。

ルートだけを渡された場合： ui-design の機能別プレイブックと同じ方法で機能（フォーム、リスト、モーダル、ダッシュボード、チェックアウト）を検出し、その画面に適した一連のテストを実行します。probes/axe-scan.md、probes/console-network.md、probes/viewport-stress.md は、低コストであり、誰も予想していなかった問題を見つける3つのプローブなので、すべてのルートで必ず実行します。

実行前にマトリックスの規模を見積もってください。ルート、ビューポート、テーマを掛け合わせると、すぐに大規模になります。実行に20分かかるようでは、次回は省略されてしまいます。ビューポートを2つ（360と1280）、テーマを2つにすれば、必要な範囲を網羅できます。幅を追加するのは、プローブですでに問題が見つかった場合に限ります。

3. プローブを実行する

各プローブファイルに独自の手順が記載されています。すべてに共通するルールは3つです。

• 解釈する前に証拠を保存します。 スクリーンショット、JSON形式の測定結果、コンソールログを、まずディスクに書き込みます。証拠が一度も保存されていない指摘は、レポートを読む人が検証できず、静的監査で残された状態に戻ってしまいます。
• 1つのプローブにつき、1つのルート、1つのビューポート、1つのテーマにします。 2つの条件を1回の実行にまとめてはいけません。結果に意外な点があったとき、どの要因が影響したのかを把握する必要があります。
• 不確かな測定は繰り返します。 タイミングに左右される結果や一貫しない結果は、条件を管理して再試行します。トリガーを記録した決定論的な失敗を、重複して実行する必要はありません。結果が変動する場合は、その条件が理解されるまで結論は不明のままです。

UI変更や名前付き状態のキャプチャでは、references/visual-review.md に従って、報告する前に自分で画像を確認します。視覚的な観察結果は、プローブの測定結果とは分けて記録してください。

4. 各指摘を判定する

結果は3種類あります。そのうち中間の結果こそが、このスキルの価値を発揮するものです。

結果	意味	引き継いだ指摘への影響
reproduced	プローブで欠陥が測定されました	fail のままですが、今後はソースを読んだ結果ではなく、測定結果に基づく observed が付きます
not-reproduced	テストした条件では欠陥が確認されませんでした	プローブが問題とされたトリガーを試した場合に限り、指摘を取り下げます。それ以外の場合は、残るカバレッジの不足を付記して候補を維持します
unknown	プローブを実行できなかったか、判定できませんでした	指摘はプローブの理由とともに unknown として残ります。合格に変わることはありません

not-reproduced は、無駄な実行ではなく、実際に成果となる結果です。大規模なルールコーパスが file:line で確実であるかのように示す誤検出を取り除き、ui-design がすでに要求している却下セクションにも反映できます。

プローブで静的ルールが予測していない問題が見つかった場合は、そのプローブが主に対象としているルール ID に対する新しい指摘として出力します。該当するルールがない場合（ui-design に対応する項目のない axe 違反やコンソールエラーなど）は、axe:<violation-id> または runtime:<signature> として出力し、それがコーパスではなくブラウザーから見つかったことを明記します。

5. 再実行による解消確認

差分を読むだけでは、修正を検証したことになりません。同一のプローブを再実行します。同じルート、同じビューポート、同じテーマ、同じシード、同じ注入障害を使ってください。指摘に clearedBy として記録し、修正前のアーティファクトは保持します。修正後のもので上書きしてはいけません。

特記すべき結果は3つです。

• プローブが合格するようになった場合：指摘は applied となり、解消済みです。
• プローブが引き続き失敗する場合：修正は機能していません。適用済み・未検証として報告し、その旨を明記します。修正だけを報告して再実行について黙っていてはいけません。
• プローブは合格したものの、同じルートの別のプローブが失敗するようになった場合：修正によってリグレッションが発生しています。これは新しい指摘であり、元の指摘への注記ではありません。

6. レポート

references/evidence-output.md で形式が定められています。各指摘に追加する verification ブロック、トップレベルの session ブロック、アーティファクトのパスです。ここで定義されるのは、ui-design の references/output-adapters.md スキーマに対する差分のみです。同スキーマが、指摘オブジェクト、3つの件数、判定の唯一の定義元です。

このスキルを単独で実行する場合は、SHIP VERDICT を省略した同じターミナルアダプターを出力します。判定は段階的な監査に属するものであり、プローブ結果だけから判定を出力すると、誰も行っていない段階の割り当てを捏造することになります。

誠実さに関するルール

• プローブをスキップしたことは、合格したことを意味しません。 実行されなかったプローブは、その理由（ルートがない、認証が必要、ドライバーがインターセプトに対応していない、アプリをビルドできない）とともにすべて報告してください。これらをひそかに省いたレポートは、実際にはないカバレッジがあるように見えます。
• スクリーンショットは証拠であって、判定ではありません。 判定は測定値に基づいて行います。エージェントは引き渡す前にキャプチャを確認します。目視による観察は測定結果を補完しますが、スクリーンショットをフローが正しいことの証明にしてはいけません。
• 範囲を広げて再設計しないでください。 このスキルは測定した内容を報告します。新しいタイプスケールが必要な指摘事項があれば、監査と同様に、次に実行するモードを明示してください。
• 対象はアプリであり、ハーネスではありません。 プローブ自体が原因の失敗（解決されなかったセレクターや、誤ったリクエストを飲み込んだルートインターセプトなど）は、ハーネスの不具合です。プローブを修正して再実行してください。アプリの欠陥として報告してはいけません。
• 数値には単位と条件を付けてください。 44x44px at 360px width with touch emulation on は測定値です。too small は、このスキルが置き換えようとしている推論です。

注意点

複数のプローブにまたがる注意点です。各プローブファイルには、それぞれの誤検出に関する説明があります。

• page.emulateMedia({ colorScheme: 'dark' }) は、class="dark" または data-theme 属性でテーマを切り替えるアプリ（ほとんどの Tailwind アプリが該当します）には何の効果もありません。プローブはダークモードに切り替わっていないのに、問題なく通過したと報告します。アプリ独自の切り替え機能を操作し、キャプチャする前に属性が設定されたことをアサートしてください。
• next dev に対してパフォーマンスやレイアウトシフトのプローブを実行すると、オンデマンドコンパイルを測定してしまいます。ルートへの初回ナビゲーションでバンドラーの処理に数秒かかることがあり、その時間が LCP に加算され、実際の影響を大きく上回ります。
• アニメーションが終わらないと、スクリーンショットプローブはタイムアウトまで待ち続けます。キャプチャ時には prefers-reduced-motion: reduce を設定し、モーションに関するチェックはこれをオフにして別途実行してください。視覚効果を抑える設定でも、壊れる可能性があるコードパスだからです。

関連スキル

• ui-design：ソースを読み、このスキルが再現する指摘事項を作成し、重要度の分類、リリース可否の判定、指摘事項のスキーマを管理します。
• typography-audit：描画後の測定値や行送りの値が必要なタイポグラフィ関連の指摘事項は、測定のためにこのスキルに引き継げます。
• ax-audit：エージェント機能を備えたインターフェイスを対象とします。実行時の確認には、同じセッションとプローブを使用します。
• ui-animation：モーションの表現を扱います。このスキルではタイミングをキャプチャできますが、カーブの評価はそのスキルの担当です。
• app-verification：アプリごとに永続的に使用できるハーネス（verify CLI、doctor コマンド、機能マップ、worktree の分離）で、リポジトリに保持され、すべてのエージェントが再利用します。このスキルのプローブは、そのハーネスの verify が対応する UI 経路を確認する際に呼び出せる種類のチェックです。固定された UI ルールに対して一度だけブラウザプローブを実行する場合はこのスキルを使ってください。セッションを重ねてもリポジトリが継続的に検証を実行し、その結果を証明できるようにする場合は、app-verification（名前を指定して呼び出してください）を使ってください。

メンテナンス専用：evals/evals.json には、このスキルを変更する人向けの動作シナリオとルーティングプロンプトが格納されています。検証の実行中に読み込まれることはありません。