ux-audit

UX 監査

React／Next.js コード向けの静的な UX 品質レビューです。原則レベルではなく、機能レベル（チェックアウトフロー、オンボーディングフロー、ダッシュボードなど）で動作します。PR を開いているフロントエンド開発者に、次の問いへの答えを提示します。「本番環境でユーザーに悪影響を与えるのはどれで、あると望ましい程度なのはどれか？」

このスキルでできること

• PR 内で変更されたファイルを監査する、差分を考慮したレビュー
• 機能レベルのチェックリスト実行：「これはサインインフロー」「これはチェックアウト」「これはモーダル」と検出し、適切なプレイブックを実行
• リリース準備状況の判定を生成：すべての指摘に release-blocker | fix-this-sprint | backlog を付与
• 最新の React 19 API（useActionState、useFormStatus、useOptimistic、useTransition、<Suspense>、エラーバウンダリ）を活用した具体的な修正案の提示

このスキルでできないこと

適切なツールに任せてください。すでに優れた機能を持つ以下のツールの役割を重複して担わないでください。

対象	代わりに使うツール	理由
Core Web Vitals（LCP、CLS、INP）	Lighthouse + web-vitals + Vercel Agent	静的解析ではなく、実ユーザー環境とラボでの計測
WCAG ルール違反	axe-core / jsx-a11y	信頼できるルール一覧と、構造化された違反情報
記述時の a11y 対策	eslint-plugin-jsx-a11y	実行時より前にリンターで検出
ビジュアルリグレッション	Chromatic / Percy	ピクセル単位の差分
バンドルサイズの予算	size-limit / bundle-analyzer	継続的な予算追跡
一般的なバグレビュー	CodeRabbit / Vercel Agent	差分全体を対象とする LLM によるバグレビュー

指摘が上記のいずれかと重複する場合は、内容を言い直さず、該当ツールへのリンクを提示してください。

全項目の一覧は references/defer-to-other-tools.md を参照してください。

監査ワークフロー

このチェックリストをコピーして、進捗を記録してください。

UX Audit progress:
- [ ] Step 1: Determine scope (PR diff via `git diff --name-only main` OR explicit file/folder)
- [ ] Step 2: Detect features in scope (sign-in / checkout / form / modal / list / dashboard / etc.)
- [ ] Step 3: For each feature, run its playbook from references/feature-playbooks.md
- [ ] Step 4: For each check, load the matching rule (rules-modern/ for state/form/focus bugs; rules/ for Laws of UX)
- [ ] Step 5: Assign each finding a ship tier per references/ship-readiness.md
- [ ] Step 6: Group findings by surface, render with the chosen output adapter
- [ ] Step 7: Verify the audit-self-check before reporting

1. 範囲を決める。 未コミットの変更がある Git リポジトリでは、既定で git diff --name-only main を使います。それ以外の場合は、ユーザーが明示した範囲を監査します。既定でコードベース全体を監査しないでください。ノイズが多すぎます。
2. 機能を検出する。 要素のセマンティクス、ファイル名、ルートパスを照合します。メールアドレスとパスワードを含む <form> はサインイン、多段階インジケーターを含む <form> はオンボーディング、role="dialog" はモーダルと判断します。機能ごとの検出ヒューリスティックについては、references/feature-playbooks.md を参照してください。
3. プレイブックを実行する。 各機能には、順序付けられた 5～7 個のチェックがあります。合格すると思われる場合でも、チェックを省略しないでください。各チェックの合格結果を監査セルフチェックに記録します。
4. ルールを読み込む。 レイヤーは 2 つあります。
   • rules-modern/（レイヤー 2）— 最新のフロントエンド UX における失敗要因（状態の網羅、フォーム内容の保持、フォーカス管理、楽観的更新のロールバック、CLS、マイクロコピー）。指摘の多くはここから見つかります。
   • rules/（レイヤー 3）— UX の法則（ヒックの法則、フィッツの法則、ミラーの法則など）。レイヤー 2 が当てはまらない場合に、認知・知覚に基づく推論に使用します。
5. リリース区分を決める。 すべての指摘に、次の 3 つの区分のいずれかを付与します（references/ship-readiness.md を参照）。
   • release-blocker — マージ前に修正（データ損失、認証の破損、重要経路におけるエラー状態の欠落、ダークパターン、元に戻らないフォーカストラップ）
   • fix-this-sprint — マージはするが、課題を記録（タッチ操作で 44 px 未満のターゲット、スケルトンの欠落、曖昧なエラー、空の状態における CTA の欠落）
   • backlog — 追跡しつつリリース（ダークモード未テスト、RTL 未検証、マイクロコピーの細かな問題）
6. グループ化して出力する。 表示領域（コンポーネントファイルまたはページ）ごとにグループ化します。references/output-adapters.md にある 3 つのアダプターのいずれかで出力します。
7. セルフチェックする。 監査が実際に実行されたことを確認します（実行したルール数 > 予定していたルール数、すべての指摘にファイルと行を記載、すべての指摘に修正コード例を記載）。

3 つの監査レイヤー

Layer 1 — Feature playbooks  (the entry point)
  references/feature-playbooks.md
  12 features × 5-7 ordered checks → pulls rules from Layers 2 and 3

Layer 2 — Modern frontend failure modes  (the high-leverage layer)
  rules-modern/<category>-<slug>.md
  33 rules covering state coverage, form preservation, focus mgmt,
  async/optimistic, CLS pairings, microcopy, dark mode, i18n, mobile.
  Detection recipes use React 19 APIs.

Layer 3 — Laws of UX  (the cognitive/perceptual reserve)
  rules/<prefix>-<slug>.md
  30 rules for Hick's, Fitts's, Miller's, etc. Invoked when feature
  playbooks need cognitive load / decision / perception reasoning.
  Usually 1-2 of these per audit; not all 30.

差分を考慮したモード

既定の対象範囲は PR の差分です。次のコマンドで検出します。

git diff --name-only main -- '*.tsx' '*.jsx' '*.ts' '*.js' '*.css' '*.module.css'

対象ファイルのみを監査します。出力にはベースブランチを示します。Auditing: 8 files changed vs main

単一コンポーネントをすばやくローカルで確認するには、次を実行します。git diff --name-only HEAD -- src/Component.tsx

全体を確認するには、明示的に --full src/ を指定します（まれなケースです。コードベースにこのスキルを導入するときに限ります）。

出荷準備状況の判定

すべての監査では、個々の指摘の詳細より先に、最上位の判定を出力します。

═══════════════════════════════════════════════════════════
SHIP VERDICT: ❌ NOT READY (1 release-blocker)

Surface count:           3 (CheckoutForm, PaymentStep, ConfirmStep)
Findings:                7
  Release blockers:      1   ⛔  Form data loss on validation (PaymentStep.tsx:42)
  Fix this sprint:       3   ⚠️
  Backlog:               3   📋

Defer-to (not audited here):
  Performance (CWV):     Run Lighthouse
  Bundle size:           Run size-limit
  WCAG violations:       Run axe-core
═══════════════════════════════════════════════════════════

判定レベル：

• ✅ READY — リリースブロッカーが0件、今スプリントで修正すべき項目が3件以下
• ⚠️ READY WITH FOLLOW-UP — リリースブロッカーが0件、今スプリントで修正すべき項目が4件以上
• ❌ NOT READY — リリースブロッカーが1件以上
• 🚫 INCOMPLETE — 監査のセルフチェックに失敗（再実行してください）

出力アダプター

形式は3種類あり、すべて同じ JSON から生成されます。状況に応じて選択してください。

アダプター	使用場面	形式
ターミナルテーブル	ローカル開発、すばやく確認するとき	サーフェスごとにグループ化した、コンパクトな5列のテーブル
PR コメント	GitHub / Vercel でのレビュー	インライン差分用の suggestion ブロックを含む Markdown
CI JSON	パイプライン、ダッシュボード	references/output-schema.md に準拠した厳密な JSON

テンプレートとフィールドの対応付けについては、references/output-adapters.md を参照してください。

スキッププロトコル

指摘には、インラインコメントで意図的に抑制できるものがあります。

{/* ux-audit-ignore:focus-not-restored — intentional: parent owns focus */}
<Dialog open={open} onClose={onClose}>

スラッグはルールのスラッグと一致している必要があります。抑制した項目は監査サマリーに記載されるため、レビュアーはその意図を確認できます。

参照ファイル

ファイル	読むタイミング
references/feature-playbooks.md	ステップ2～3 — 機能を検出し、対応するプレイブックを選択するとき
references/modern-failure-modes.md	カテゴリー別にまとめられた、全33件の最新ルールの一覧
references/states-coverage.md	コンポーネントの種類ごとに、読み込み中／空／エラー／無効状態への対応を検証するとき
references/ship-readiness.md	ステップ5 — 各指摘に出荷レベルを割り当てるとき（例を参照）
references/output-adapters.md	ステップ6 — ターミナル／PR コメント／JSON 向けに指摘を整形するとき
references/defer-to-other-tools.md	他のツールに委任する懸念事項（CWV、WCAG、バンドルなど）を見分けるとき
references/output-schema.md	指摘と判定の厳密な JSON スキーマ
references/observational-rubrics.md	レイヤー3の評価基準ルール（基準付きの1～5段階評価）
rules-modern/<category>-<slug>.md	ステップ4 — レイヤー2の最新フロントエンドチェックを実行するとき
rules-modern/_sections.md	最新ルールレイヤーのカテゴリー一覧
rules/<prefix>-<slug>.md	ステップ4 — Laws of UX のレイヤー3チェックを実行するとき
rules/_sections.md	Laws of UX ルールレイヤーのカテゴリー一覧

注意点

• デフォルトでは、コードベース全体を監査しないでください。 デフォルトは差分対応モードです。全体を対象とするスキャンは明示的に指定します。
• 他のツールと役割を重複させないでください。 指摘が「LCP > 4s」なら、それは Lighthouse の担当です。リンクを示し、言い換えて繰り返さないでください。「alt テキストがない」なら、それは axe の担当です。リンクを示し、言い換えて繰り返さないでください。
• 機能検出のステップを飛ばさないでください。 すべてのファイルにすべてのルールを適用するとノイズが生じます。機能ごとに適切なプレイブックを実行すれば、有用な結果が得られます。
• すべての指摘に release-blocker を割り当てないでください。 このレベルは、実際に出荷を妨げるもの（データ損失、重要なユーザーフローの破損、ダークパターン）に限定してください。むやみに割り当てると、有用な情報が埋もれます。
• 該当する場合は、最新の React API を使わない修正案を提示しないでください。 「ローディング状態を追加する」では不十分です。「<Suspense fallback={<Skeleton />}> で囲み、トリガーには useTransition を使う」のように、実行可能な案を提示してください。
• 先に JSON を処理せず、Markdown を出力しないでください。 ユーザーが Markdown を希望する場合でも、まず JSON ドキュメントを作成し、実行間で指摘を監査できるようにしてください。
• Laws of UX の指摘を過剰に追加しないでください。 レイヤー3は予備です。指摘にレイヤー2の説明（「エラー状態がない」）とレイヤー3の説明（「Postel's Law 違反」の両方が当てはまる場合は、レイヤー2を使ってください。より具体的で、実行に移しやすいためです。
• ソースをそのまま引用しないでください。 すべてのルールは言い換えてください。lawsofux.com は CC BY-NC-SA ライセンスのため、そのまま引用するとスキルに影響が及びます。
• 検出結果を捏造しないでください。 ファイルを grep で検索できない、または JSX を確認できない場合は、理由を添えて指摘を unknown としてください。根拠のない指摘をしてはいけません。

監査のセルフチェック

以下のいずれかに該当する場合、監査に INCOMPLETE のフラグを付けます。

• 実行されたルールの数が、プレイブックで予定された数より少ない
• unknown（証拠不十分）を返したルールが 30% を超える
• fail/warn の指摘に file:line の記載が一つもない
• reproduceSteps または fix のスニペットが提供されていない
• ルールごとの見かけ上の所要時間の中央値が不自然なほど短い（指摘の間に Read または Grep ツールの呼び出しがない）
• すべての指摘が同じティアになっている（疑わしい点：判断を伴わない一律の割り当て）