a11y-debugging

コア概念

アクセシビリティツリー vs DOM: 要素を視覚的に非表示にする場合（例：CSS opacity: 0）とスクリーンリーダーの動作は異なり、display: none や aria-hidden="true" とも異なります。take_snapshot ツールはページのアクセシビリティツリーを返します。これは支援技術が「見る」ものを表すため、セマンティック構造の最も信頼できる情報源となります。

web.dev ドキュメントの参照: 特定のアクセシビリティガイドラインを調べる必要がある場合（例：https://web.dev/articles/accessible-tap-targets）、URL の末尾に .md.txt を追加することで（例：https://web.dev/articles/accessible-tap-targets.md.txt）、クリーンで生のマークダウン版を取得できます。これはより読みやすくなります！

ワークフローパターン

1. 自動監査（Lighthouse）

Lighthouse アクセシビリティ監査を実行して、包括的なベースラインを取得することから始めます。このツールは高レベルのスコアを提供し、失敗した特定の要素とその修正方法をリストアップします。

1. 監査を実行します：
   • mode を "navigation" に設定してページをリフレッシュし、読み込み時の問題をキャプチャします。
   • outputDirPath（例：/tmp/lh-report）を設定して、完全な JSON レポートを保存します。
2. 概要を分析します：
   • scores（0～1 スケール）を確認します。スコアが 1 未満の場合は違反があります。
   • audits.failed の数を確認します。
3. レポートを確認します（重要）：
   • 解析: ファイル全体を 1 行ずつ読まないでください。jq などの CLI ツールまたは Node.js のワンライナーを使用して失敗をフィルタリングします：

     # 失敗した監査とその詳細を抽出
     node -e "const r=require('./report.json'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))"
     

   • これにより、完全なレポートをコンテキストに読み込まずに、失敗した要素の selector と snippet を効率的に抽出できます。

2. ブラウザの問題と監査

Chrome は一般的なアクセシビリティの問題を自動的にチェックします。list_console_messages を使用してこれらのネイティブ監査を確認します：

• types: ["issue"]
• includePreservedMessages: true（ページ読み込み時に発生した問題をキャッチするため）

これにより、手動調査なしに、ラベルの欠落、無効な ARIA 属性、その他の重大なエラーがしばしば明らかになります。

3. セマンティクスと構造

アクセシビリティツリーは見出しの階層とセマンティックランドマークを露出させます。

1. ページに移動します。
2. take_snapshot を使用してアクセシビリティツリーをキャプチャします。
3. 見出しレベルを確認: 見出しレベル（h1、h2、h3 など）が論理的で、レベルをスキップしていないことを確認します。スナップショットに見出しロールが含まれます。
4. コンテンツの並べ替え: DOM の順序（アクセシビリティツリーを駆動する）が視覚的な読む順序と一致することを確認します。take_screenshot を使用して視覚的なレイアウトを検査し、スナップショット構造と比較して、CSS フロートや絶対位置付けが論理フローを混乱させていないかをチェックします。

4. ラベル、フォーム、テキスト代替表現

1. take_snapshot の出力でボタン、入力、画像を探します。
2. インタラクティブ要素にアクセス可能な名前があることを確認します（例：ボタンがアイコンのみを含む場合、"" だけであってはいけません）。
3. 孤立した入力: すべてのフォーム入力に関連するラベルがあることを確認します。references/a11y-snippets.md にある "Find Orphaned Form Inputs" スニペット で evaluate_script を使用します。
4. 画像に alt テキストがあるか確認します。

5. フォーカスとキーボードナビゲーション

キーボードトラップの検出と、視覚的なフィードバックなしに適切なフォーカス管理をテストするには、フォーカスされた要素をトラッキングに頼ります。

1. "Tab" または "Shift+Tab" を使用して press_key ツールでフォーカスを移動します。
2. take_snapshot を使用して更新されたアクセシビリティツリーをキャプチャします。
3. スナップショット内でフォーカスとしてマークされた要素を探し、フォーカスが予期された対話型要素に移動したことを確認します。
4. モーダルが開く場合、フォーカスはモーダル内に移動し、閉じるまで「トラップ」される必要があります。

6. タップターゲットと視覚

web.dev によると、タップターゲットは最低 48x48 ピクセルで十分な間隔を持つ必要があります。アクセシビリティツリーはサイズを表示しないため、references/a11y-snippets.md にある "Measure Tap Target Size" スニペット で evaluate_script を使用します。

スナップショットからの要素の uid を evaluate_script の引数として渡します。

7. 色のコントラスト

色のコントラスト比を確認するには、まずネイティブアクセシビリティの問題をチェックすることから始めます：

1. types: ["issue"] で list_console_messages を呼び出します。
2. 出力で「Low Contrast」の問題を探します。

ネイティブ監査が問題を報告しない場合（一部のヘッドレス環境では発生する可能性があります）または特定の要素を手動でチェックする必要がある場合は、references/a11y-snippets.md にある "Check Color Contrast" スニペット で evaluate_script を使用します。

8. グローバルページチェック

references/a11y-snippets.md にある "Global Page Checks" スニペット を使用して、コンポーネントテストで見落とされることが多いドキュメントレベルのアクセシビリティ設定を確認します。

トラブルシューティング

標準的な a11y クエリが失敗する場合、または evaluate_script スニペットが予期しない結果を返す場合：

• 視覚的検査: 自動スクリプトがコントラストを判定できない場合（例：グラデーション画像または複雑な背景上のテキスト）、take_screenshot を使用して要素をキャプチャします。モデルは画像から正確なコントラスト比を測定することはできませんが、可読性を視覚的に評価し、明らかな問題を特定できます。