joo6077/design-audit

注意点（Gotchas）

1. コード品質評価禁止 — アーキテクチャ、パフォーマンス、コードスタイルを評価しないでください。デザイン原則の遵守のみを判定します。

2. トークン不使用でのFAIL乱発禁止 — デザイントークンがないプロジェクトで「トークン不使用」によるFAILを乱発しないでください。トークン体系がない場合は、design-systemスキルの使用を推奨するNOTEとして残してください。

3. アクセシビリティカテゴリ必須 — 視覚的に問題なく見えても必ず検査します：contrast ratio (WCAG 2.2 AA 4.5:1)、タッチターゲット、フォーカスインジケーター、フォームラベル接続、WCAG 2.2 新規 SC (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA)。省略するとREJECT。

   タッチターゲット基準まとめ（2026-04-11更新）：

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px（例外：sufficient spacing / inline text / user-agent / essential）
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = タッチデバイス実用推奨値（プラットフォームガイドライン）

   既存のレポートで「44×44pt」だけを明示すると、読者が「WCAG AA要件」と誤解する可能性があるため、AA/AAA/プラットフォーム推奨を区別して記載してください。出典：W3C WCAG 2.2 SC 2.5.8、W3C What's New in WCAG 2.2。

4. AIアンチパターン検査を含める — Authenticityカテゴリを必ず含めてください。均一なborder-radius、汎用的な青紫パレット、同一構造の繰り返し、目的のない装飾効果はFAIL理由となります。

5. 重要度分類必須 — FAIL項目ごとに重要度を表記します：Critical（アクセシビリティ・倫理）、Major（階層・一貫性）、Minor（微調整）。重要度のないFAILレポートは不完全です。

6. 主観的判定禁止 — 「見た目が良い」「これくらいなら大丈夫」は根拠になりません。すべてのPASS/FAILはaudit-criteria.mdで定義された原則と数値基準に基づく必要があります。

7. 状態/例外画面を含める — 基本画面だけを検査しないでください。空の状態、エラー状態、ローディング状態、データ過多/過少状態がコードに存在する場合は一緒に検査します。

8. コード未確認項目の区別 — ランタイムレンダリング、実際のインタラクションなど、静的解析では判定不可能な項目はPASS/FAILではなく[未検証]と表記し、手動確認方法を案内します。

9. ヒューリスティックとカテゴリの混同禁止 — Nielsenの10ヒューリスティックは評価の観点フレームです。実際の判定は必ずaudit-criteria.mdの10カテゴリ基準（Typography, Color, Spacing, Accessibility, Interaction, Motion, Visual Hierarchy, Layout & Grid, Ethical Design, Authenticity）にマッピングして実施します。

10. Rule-by-Rule監査 — 完了宣言前に10カテゴリ全数対照 — APPROVE/REJECT判定の前に、audit-criteria.mdの10カテゴリ×コアチェックポイントをすべて巡回し、各項目にPASS / FAIL / [未検証]を明示したテーブルがレポートに含まれている必要があります。一部のカテゴリを「該当なし」でひとまとめにせず、理由を記載してください。カテゴリを飛ばした監査は監査ではありません（skill-design-guide §3.6 Rule-by-Rule Audit対応）。

11. Binary Decidability Pre-Check — 監査開始前に二値判定可能性を確認 — 監査範囲を決めた後、各予想FAIL項目が「コード/スタイル/トークンのみでPASS/FAILが二値判定可能か」を最初にチェックします。ランタイムレンダリング・実際のインタラクション・MCP Figma対照が必要な項目は直ちに[未検証]に分類し、PASSで通過させないでください。未検証は2つのカウンターで数えます — invalid_evidence（[未検証:INVALID]・接尾辞なしの[未検証]）は0件は通常判定、1件はPASS許可＋警告明示、2件以上は個別FAILがなくてもREJECTです。4要件をすべて満たした[未検証:ENV]はenv_gapsとして別に数え、REJECT算定には入れず、verified_coverageが0.60未満の場合はBLOCKEDです。このルールはharness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocolの「閾値2は」の条項が正本であり、ここで再定義しません。design-reviewerルール8のコピーと同じ値である必要があります（agent-design-guide §3.5 Binary Decidability対応・skill側反映）。

12. Evidence Validity Gate — 「証拠がある」と「証拠が証明する」は異なる — Gotcha 11が証拠を得られるかを扱うのに対し、この項目は証拠は得たがそれが何も証明しない場合を扱います。PASSを確定する前に4つの検査を通過させてください。1つでも失敗したらPASSではなく[未検証]です。

    #	検査	失敗例（監査コンテキスト）
    1	非空白	0バイトのスナップショット、エラーのみのログを根拠として引用
    2	活性化	コントラスト検査対象のテキストノードが0個なのに「コントラスト違反なしPASS」
    3	反証可能性	どのコードでも同じ結果を出すgrepをオラクルとして使用
    4	出典	実装者のコメント・コミットメッセージの「アクセシビリティ確認済み」を根拠として採用

    0マッチ判定 — grep 0件は2通りあります。意図された0（対象ファイル数を先に数え、パターンが別の場所でマッチすることを確認した後の0）のみがPASSの根拠になります。空虚な0（パスエラー・空ファイル・絶対にマッチしないパターン）は測定失敗であり[未検証]です。根拠文には対象Nファイル・パターン有効性確認・マッチ0の形式で3つを一緒に記載してください。

    レンダリング成果物特則 — 空画面・空リスト・プレースホルダーのみのキャプチャはPASSの証拠ではなく、検証失敗の信号です。キャプチャを根拠として使う場合は、条件が要求する具体的な要素を指摘してください。指摘できない場合は無効な証拠です。キャプチャごとに../../references/visual-change-protocol.md §3 キャプチャチェックリスト（あふれ・壊れたグリフ・チップ/バッジと行の形状・デバッグ重なり）を確認し、1つでも引っかかったキャプチャはPASSの根拠として使いません。出典：harness/docs/guides/qa-evaluation-guide.md §Evidence Validity Gate。

13. Before/After対照監査 — 意図外領域の変更はFAIL — 変更分（git diff基準）を監査する際は、静的な状態だけを見ずに要求範囲と実際の変更範囲を対照してください。要求が特定の視覚属性1つを指していたのに（ボーダーのみ・色のみ・間隔のみ）、同じ要素のbackground / fill / radius / shadow / spacing / typographyが一緒に変わっていた場合はMajor FAILです。承認済みのデザイン案・既存アプリの色があるのに、プロジェクトトークンや基本パレットに置き換えられていた場合はMajor FAILです（優先順位違反）。監査レポートはEVIDENCEブロック（before / after / proof / 意図外領域）で閉じます。詳細：../../references/visual-change-protocol.md。

14. Decision Propagation Coverage — 確定決定が一部の表面にのみ適用されている場合はMajor FAIL — .design/decisions.yamlが存在する場合は、10カテゴリ監査に先立ってカバレッジを判定します（カテゴリを増やすわけではありません — 前提条件の検査です）。status: approvedであるdecision_idごとにrequired_surfaces[]を巡回し、(a) goldenもuser-visible assertionもなければFAIL (b) goldenのみでvisible/count/height assertionがない場合はFAIL (c) excluded_surfacesに理由なく欠けている表面はカバレッジの空白なのでFAILです。重要度はMajor、アクセシビリティ・倫理の決定であればCriticalです。status: superseded（差し替え済み）の決定は画面の場所を判定せず、superseded_byが同じリスト内の別のapproved決定を指しているかだけを見ます。マニフェスト自体がない場合はFAILではなくNO_MANIFESTとして報告し、監査範囲から除外します — 対象0件と通過は異なります。スキーマ・ルール4条・実行可能なチェッカー：../../references/visual-change-protocol.md §6 Decision Propagation Manifest。

15. 証拠チャネルを明示する — artifact_snapshotでアプリ画面を判定しない — 根拠として引用するすべての証拠にチャネル名（artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible）を付けます。PASS文にはviewport・route/state・visible locator・count/height・screenshot/golden idの5要素が必要であり、1つでもなければPASSではなく[未検証]です。チャネル定義：../../references/visual-change-protocol.md §7 Evidence Channels。ユーザーの失敗報告と自己証拠が衝突する場合のプロトコルはharness/docs/guides/skill-design-guide.md §3.8・harness/docs/guides/agent-design-guide.md §10が正本であり、ここで再定義しません — 監査レポートでユーザーの観測を反論しないでください。

プロセス

Step 1: 対象範囲とモードの決定

ユーザーが指定したパスとモードに基づいて監査範囲を決定します：

• ファイルパス → そのファイルのみ
• ディレクトリパス → サブディレクトリのUI関連ファイルすべて
• 未指定 → 最近変更されたUIファイル（git diff基準）

モード：

• quick（デフォルト） — 全10カテゴリを素早く検査。Critical/Major FAILに集中。
• deep — 状態/例外画面、レスポンシブブレークポイント、ダークモード、アクセシビリティ詳細項目まで全数検査。

Step 2: 監査カテゴリの確認

10カテゴリを順に検査します。各カテゴリのコアチェックポイント：

カテゴリ	コアチェックポイント	重要度基準
Typography	タイポスケールの一貫性、行間（文字体系別範囲 — references/audit-criteria.md行間比率行）、本文最小14px（モバイル）/16px（Web）	Major
Color	テキストコントラスト WCAG 2.2 AA 4.5:1、セマンティックトークンの使用、ダークモードコントラスト維持、OKLCH/P3ワイドガマット使用時のsRGBフォールバック確認。APCA Lc参照（情報提供）: 本文Lc 75～90、非本文Lc 60以上、Lc 15未満は非可視。APCAはフォントサイズ+太さ別の差動コントラストを要求するため、細いフォントにはより高いコントラストが必要。判定基準はWCAG 2.2 AAであり、APCAはWCAG 3.0 WD参考用	Critical（コントラスト）/ Major（トークン）
Spacing	スペーシングスケールの一貫性、タッチターゲット WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px（AAA SC 2.5.5 = 44×44）、グループ間/内マージンの階層	Critical（タッチ）/ Major（スケール）
Accessibility	色のみでの状態伝達禁止、フォーカスインジケーター、フォームラベル、代替テキスト、WCAG 2.2 SC 2.4.11 Focus Not Obscured（AA）、SC 2.5.7 Dragging Movements（AA）、SC 3.3.8 Accessible Authentication Min（AA）	Critical
Interaction	アクションフィードバック、ローディングインジケーター、エラー表示、キャンセル/元に戻すパス、ドラッグ専用UX時のシングルポインタ代替（WCAG 2.2 SC 2.5.7）	Major
Motion	アニメーションの目的性、デュレーション200～500ms、prefers-reduced-motion対応	Major
Visual Hierarchy	見出し/本文/キャプションの比率差、コアコンテンツのコントラスト強調、グループマージンによる分離	Major
Layout & Grid	グリッド整列、ガターの一貫性、主要ブレークポイントのレスポンシブ戦略、コンポーネントレベルのレスポンシブはcontainer-type: inline-size + @container推奨（サイズクエリ対応：Chrome 105・Firefox 110・Safari 16）。Container Queriesチェック: ページレベルの分岐はmedia queries、コンポーネントレベルの分岐はcontainer queriesの使用有無を確認。cqw/cqiユニット活用、コンテンツが崩れるポイントベースのブレークポイント設定推奨（デバイスターゲットではない）	Major
Ethical Design	ダークパターン12タイプの不在、同意の明示性、登録・退会パスの対称性	Critical
Authenticity	同一構造の3回以上の繰り返し、汎用パレット、目的のない装飾、汎用コピー、同じ役割の既存画面との慣例不一致	Minor～Major

Step 3: design-reviewerエージェントの呼び出し

Agentツールを使用してdesign-reviewerサブエージェントを生成します：

Agentツール呼び出し:
- subagent_type: design-reviewer
- prompt: "次のファイルをデザイン原則に基づいて[quick|deep]モードで評価せよ: [対象ファイルリスト]"

エージェントが読み取り専用で分析後、カテゴリ別PASS/FAIL/未検証結果を返します。

Step 4: レポートのフォーマット

エージェントの結果をtemplates/audit-report.mdフォーマットにまとめます。

各FAIL項目には必ず含めるもの：

• ファイル:行の位置
• 重要度（Critical / Major / Minor）
• 違反した原則（出典を含む）
• 具体的な改善方向（スタックに依存しないレベル）

未検証が1件以上の場合は、レポートに有効性集計を併記します（Gotcha 12）：

## Evidence Validity
- 検査対象証拠: {{n}}件
- 無効判定: {{k}}件 [項目ID — 失敗した検査番号 — 理由]
- 未検証累計: `invalid_evidence` {{a}}件 / `env_gaps` {{b}}件 / `verified_coverage` {{c}}

Step 5: 最終判定

• FAIL 0 + invalid_evidence 0 + verified_coverage 0.60以上 + L3 10/10 → APPROVE（env_gapsの数を記録）
• Decision Propagation Coverage FAIL 1個以上 → REJECT（10カテゴリ判定とは別の前提条件 — Gotcha 14。マニフェスト不在はFAILではなくNO_MANIFEST報告）
• 決定伝搬検査終了コード2（SCHEMA_ERROR）は入力形状が間違っていて判定できなかったものでありREJECTです — FAIL行なくviolations=0と出力されても通過と読みません。終了コード3（NO_SURFACE・NO_DECISION）はNO_MANIFESTと同様に対象0件として報告します
• Critical FAIL 1個以上 → REJECT（即時）
• Major/Minor FAILのみ → REJECT + 優先順位別の改善リスト
• FAIL 0だが**invalid_evidence 2件以上** → REJECT（Gotcha 11閾値）
• FAIL 0、invalid_evidence 2件未満、verified_coverage = (判定したチェック項目数 − env_gaps) / 判定したチェック項目数 < 0.60 → BLOCKED（insufficient_verified_coverage — 再検証コマンドを実行後、再監査）
• FAIL 0でもL3カバレッジ < 10/10（10カテゴリ中飛ばしたカテゴリがある） → REJECT + 残りのカテゴリを明示（飛ばしたカテゴリはFAILである — レビュアルール11）
• FAIL 0、invalid_evidence 1件、verified_coverage 0.60以上、L3 10/10 → APPROVE + 未検証項目と手動確認方法を明示

REJECTレポートの構造：

1. Critical FAILリスト（即時修正必要）
2. Major FAILリスト（次のスプリントまでに修正）
3. Minor FAILリスト（改善推奨）
4. [未検証]項目（手動確認必要 — [未検証:ENV] / [未検証:INVALID]を区別）

変更分監査（git diff基準）の場合は、レポートをEVIDENCEブロックで閉じます（Gotcha 13）：

## EVIDENCE
- before: [変更前状態の根拠 — ファイル:行またはキャプチャ]
- after:  [変更後状態の根拠]
- proof:  [判定を裏付けるコマンドと出力]
- 意図外領域: [変化なし確認の根拠 / またはFAIL処理した項目]

参考文献

• references/audit-criteria.md — カテゴリ別監査基準詳細
• templates/audit-report.md — レポート出力フォーマット
• ../../references/visual-change-protocol.md — 視覚変更優先順位・部分変更分離・証拠ブロック・§6 Decision Propagation Manifest・§7 Evidence Channels（SSOT）
• harness/docs/guides/skill-design-guide.md §3.8・harness/docs/guides/agent-design-guide.md §10 — ユーザー失敗報告優先順位プロトコルの正本
• harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol・§Evidence Validity Gate — 未検証閾値・有効性4検査の正本