a11y-debugging

コアコンセプト

アクセシビリティツリーと 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）、整形された生の Markdown 版を取得できます。こちらのほうがずっと読みやすくなります！

ワークフローのパターン

1. 自動監査（Lighthouse）

まず Lighthouse のアクセシビリティ監査を実行し、包括的なベースラインを取得します。このツールは全体的なスコアを提示し、修正方法のアドバイスとともに、問題がある具体的な要素を一覧表示します。

1. 監査を実行します：
   • ページを再読み込みして読み込み時の問題を検出するため、mode を "navigation" に設定します。
   • 完全な JSON レポートを保存するため、outputDirPath（例：/tmp/lh-report）を設定します。
2. 概要を分析します：
   • scores（0～1 の範囲）を確認します。スコアが 1 未満の場合、違反があります。
   • audits.failed の件数を確認します。
3. レポートを確認します（重要）：
   • 解析：ファイル全体を行ごとに読み込まないでください。失敗項目を絞り込むには、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 にある 「フォーム入力欄のラベル漏れを検索」スニペットを使って、evaluate_script を実行します。
4. 画像に alt テキストがあるか確認します。

5. フォーカスとキーボード操作

キーボードトラップや適切なフォーカス管理を視覚的なフィードバックなしでテストするには、フォーカスされている要素を追跡します。

1. press_key ツールで "Tab" または "Shift+Tab" を使い、フォーカスを移動します。
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. ページ全体のチェック

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

トラブルシューティング

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

• 目視確認：自動スクリプトでコントラストを判定できない場合（グラデーション画像や複雑な背景の上にテキストがある場合など）は、take_screenshot を使って要素を撮影してください。モデルは画像から正確なコントラスト比を測定できませんが、視認性を目視で評価し、明らかな問題を特定できます。