UX品質チェックは何をしますか？

変更が触れるUI画面をreferences/rules.mdのルールに対してチェックします。各ルールには、理由、コードでのチェック、ブラウザでのチェック、修正方法が記載されています。そのファイルの先頭の表には、各ルールがどの種類の変更に適用されるかが示されています。

1. 変更を見つける

リクエストで指定された差分を取得します。PR、ブランチ、コミット、または未コミットの変更のいずれかです。名前がない場合は、未コミットの変更を使用します。未コミットの変更がない場合は、デフォルトブランチとのマージベースに対するブランチの差分（git diff $(git merge-base HEAD origin/HEAD)...HEAD）を使用します。ブランチがデフォルトブランチの場合は、最後のコミットを使用します。レポートでどの差分をチェックしたかを明記します。
変更されたUIファイル（コンポーネント、テンプレート、スタイル、およびそれらがレンダリングする文字列やプロパティ）をリストアップします。共有コンポーネントやトークンへの変更もUI変更です。
差分内のどのファイルもUIをレンダリングしない場合（サーバーコード、テスト、設定、ドキュメントのみ）、その旨を1～2文で述べて停止します。検出結果は報告しません。

2. リポジトリ独自のUIルールを読み、画面をマッピングする

リポジトリのルールはカタログのデフォルトよりも優先されます。

リポジトリのエージェントドキュメント（AGENTS.md、CLAUDE.md、デザインシステムのREADME）から「UIルール」または同様のセクションを読みます。ルールで指定されているコントロール、トークン、コンポーネント（ダイアログヘルパー、非同期ボタン、タイプトークン、AIマークなど）をそれぞれメモします。修正ではそのコンポーネントを指定します。
リポジトリ独自のUXチェック（make ux-checkやux:checkターゲット、レイアウトやアクセシビリティのスクリプト、lintルール、またはUIルールのソースをスキャンするテスト）を探します。変更をカバーするものをすべて実行し、その出力を証拠として使用します。

次に、各変更ファイルをユーザーが見る画面（ルート、ビュー、コントロール）にマッピングします。共有コンポーネントは、それを使用する各画面にマッピングされます。画面はユーザーがそれを見つける方法で名前を付けます（「レビューページ、コメント追加フォーム」）。各画面について、以下を記録します。

種類: 差分が追加または編集するreferences/rules.mdの凡例に従って、画面にタグを付けます。write、data、form、list、control、overlay、layout、route、copy、chart、style。新しいホバースタイルはcontrolとlist。保存ボタンはwriteです。
状態: 空、ローディング中、保留中、エラー、ホバー、フォーカス、選択済み、無効。ほとんどの欠陥は、作者が開いていない状態にあります。

3. チェックを実行する

各画面について、「適用対象」が画面の種類と共通する各ルールを実行します。チェックする前にルールのセクションを読みます。スキップしたルールとその理由を記録します。

最初にコードを読みます。 各ルールの「コードでのチェック」には何を探すべきかが書かれています。これでほとんどの欠陥を捕捉でき、ブラウザは不要です。不足している状態を報告する前に、コードが呼び出すコンポーネント（ラッパー、非同期ボタン、フォームフック、pendingを渡す親など）を読みます。多くの場合、それらが状態を処理しています。

次に、可能であればブラウザで測定します。 静的HTMLページはfile:// URLでディスクから開きます。アプリの場合は、実行中の開発サーバーを探すか、リポジトリのドキュメントに記載されたコマンドで起動します。ホストが提供するブラウザツール（組み込みブラウザペイン、Playwrightスクリプト、ヘッドレスChrome）を使用します。ページがサインインを要求する場合は、そのブラウザでユーザーにサインインを依頼します。自分で資格情報を入力しないでください。

scripts/measure.jsをページに読み込みます。このスクリプトは、各ルールの「ブラウザでのチェック」で指定されるヘルパーを定義し、references/rules.mdにはそれぞれが何を返すかがリストされています。ページを読み込むたびに再度貼り付けます。アプリが提供する各テーマと配色、および少なくともスマートフォン幅とデスクトップ幅でチェックします。

変更された各行、カード、コントロールをインタラクション状態でも測定します。 ホバー、フォーカス、選択状態では、塗りつぶし、境界線、影、コントロールが追加されることがよくあります。すると、2つのボックス要素が接触したり、アイテムが拡大して隣接要素を移動させたり、ホバー時のみのアクションがカウントをラインから押し出したりします。画面上の各リスト、カードグループ、コントロールグループについて:

アイテムが静止状態のときにsnapshot(sel, "rest")とgaps(sel)を実行します。
ブラウザツールで1つのアイテムをホバーし、snapshot(sel, "hover")とgaps(sel)を再度実行します。キーボードフォーカス（Tabキーを押す）と、ホバーされたアイテムの隣にある選択済みアイテムについても同様に行います。
moved("rest", "hover")を実行します。2つのボックス要素間のギャップが0pxの場合、または他のアイテムがホバーされたときにアイテムが移動した場合は、欠陥です。

メニュー、ポップオーバー、パネルを開く各アクションの周辺でも同様に行います。メインブロックのスナップショットを撮り、開き、再度スナップショットを撮り、比較します。コードでは、ボックスを追加したりサイズを変更したりするプロパティ（background、border、box-shadow、padding、margin、width、display）について、各:hover、:focus-visible、選択済みクラスのルールを読みます。

ブラウザがない場合、または開くページがない場合は、コードの検出結果を報告し、実行されなかったブラウザチェックをリストします。

4. 各欠陥を確認する

欠陥を報告する前に、もう一度確認します。

コードの欠陥: ユーザーがその状態に到達できることを確認します。ブランチが実行され、プロパティが渡され、ラッパーや親がそれを処理していないことを確認します。
ブラウザの欠陥: リロード後、欠陥が指定する状態で再度測定します。再現しない値は破棄します。
変更内か変更前か: 差分が追加または変更した行の欠陥は変更に属します。同様に、差分が対応する状態を追加せずに状態を追加した場合（新しい:hoverルールに対応する:focus-visibleルールがない、新しい書き込みに対応する保留状態がないなど）、たとえ欠落した行が別の場所にあっても、変更に属します。差分が触れていない行の欠陥は、変更前に存在していたものです。変更の検出結果とは別に「既存の欠陥」として報告し、変更された画面上にある場合のみ報告します。

チェックに不合格の欠陥は破棄します。チェックできなかった欠陥は「未確認」として理由とともに報告します。

5. 検出結果を報告する

チェックした差分と画面を指定する1行から始めます。次に、欠陥ごとに1つの検出結果を、最も重大なものから順に示します。重大度:

高: ユーザーがデータや入力を失う、重複書き込みを送信する、コントロールに到達できない、またはテキストを読めない。
中: コントロールが誤解を招く（間違ったアイコン、色のみの状態、AIマークの欠落）、またはレイアウトが明らかに壊れている。
低: リポジトリのシステムとの不整合（生のタイプ値、混合選択コントロール、フィラー）。

各検出結果には4つの部分があります:

部分	内容
画面	ビューとコントロール、ファイルと行（`ReviewForm.tsx:42`）
ルール	カタログのルールID、または違反したリポジトリルール
証拠	読み取ったまたは測定したもの：コード行、測定値、状態、テーマ、幅
修正	1～2文の変更。リポジトリのコンポーネントやトークンを指定する場合はそれを使用

例:

画面: スタックサイドバー、作成者フィルターリスト（AuthorList.tsx:58） ルール: no-cramped-controls 証拠: gaps(".author-row")（1440px、行2をホバー時）：行1（選択済み）と行2の間でy: 0。静止時もギャップは0ですが、選択された行のみがボックスを描画します。 修正: リストにgap: 2pxを追加するか、ホバー時の塗りつぶしを2px内側に配置します。

次に、以下のセクションを追加します:

既存の欠陥: 変更によって導入されなかった、ステップ4の欠陥。それぞれ1行で。
未チェック: スキップしたルールとその理由、および実行されなかったブラウザチェック。

ユーザーが修正を求めた場合は、修正を行い、同じ画面で同じチェックを再度実行します。

UX品質チェック