a11y-debugging

コアコンセプト

ページの指定：ページスコープのツール（take_snapshot、list_console_messages、evaluate_script、press_key、take_screenshot、lighthouse_auditなど）には、pageIdパラメーターが必要です。list_pagesまたはnew_pageから、利用可能なページIDを取得します。

アクセシビリティツリーと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"に設定します。
   • outputDirPathを省略すると、レポートはデフォルトの一時ディレクトリに保存されます（report.jsonの正確なパスはReportsの下に返されます）。または、ワークスペース内のディレクトリをoutputDirPathに設定します。
2. 概要を分析します：
   • デフォルトのテキスト出力では、カテゴリスコアは0～100の尺度（100が満点）で示され、その後に監査の件数としてPassed: NとFailed: Nが続きます。
   • サーバーが--experimentalStructuredContent付きで起動された場合は、代わりに構造化コンテンツ内のsummary.scores[].score（0～1の尺度）とsummary.audits.failedを確認します。
3. レポートを確認します（重要）：
   • 解析：ファイル全体を1行ずつ読まないでください。lighthouse_auditから返されたレポートパスを使い、jqなどのCLIツールやNode.jsのワンライナーで失敗項目を絞り込みます：

     # 失敗した監査項目とその詳細を抽出します（ツールの応答にあるreport.jsonのパスに置き換えてください）
     node -e "const r=require('<path/to/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. 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. 色のコントラスト

色のコントラスト比を確認するには、evaluate_script と references/a11y-snippets.md にある 「Check Color Contrast」スニペットを使用します。

8. ページ全体のチェック

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

トラブルシューティング

標準の a11y クエリが失敗する場合や、evaluate_script のスニペットが想定外の結果を返す場合：

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