accessibility

アクセシビリティ

Web アクセシビリティが適切に実現されているとは、障害のある人、つまりスクリーンリーダーのユーザー、キーボードのみで操作するユーザー、弱視、運動障害、認知障害のある人が、UI を操作し、理解し、利用できることです。このスキルでは、構造上の問題を最も早く見つけられるスクリーンリーダー優先の視点を採用しています。ただし、弱視のユーザー（コントラスト、ズーム、リフロー）や認知障害のあるユーザーも同じように重要です。実際、コントラストの低いテキストは Web 上で最も一般的な障壁であり、ホームページの約 84% に影響しています。WebAIM Million の調査では、検出可能な WCAG 違反があるホームページは一貫して約 96% にのぼります。また、問題のうち約 96% は、コントラストの低いテキスト、代替テキストの欠落、フォームラベルの欠落、空のリンク、空のボタン、文書言語の指定漏れという 6 種類に集中しています。これらは、公開されたすべての年で WebAIM Million の調査結果の上位を占めています（リンクを参照）。適切な考え方を身につければ、その多くは防止できます。

基本となる考え方

スクリーンリーダーは、2D のページを1D の音声ストリームに直列化します。視覚障害のあるユーザーはページ全体を一度に見ることはできず、キーボードショートカットを使って、見出し、ランドマーク、フォームフィールド、リンク、インタラクティブなコントロールを順番に移動します。行うすべての判断について、次の問いに答えられるようにしてください。「スクリーンリーダーは何を読み上げるか。それだけで意味が通じるか」

ここから導かれる 3 つのルールは次のとおりです。

1. スタイルよりセマンティクスを優先する - ARIA を使う前に、ネイティブの HTML 要素（<button>、<nav>、<h2>）を使ってください。ネイティブ要素には、キーボード操作、アクセシブルな名前、適切なロールが標準で備わっています。
2. 要素には文脈を持たせる - Tab キーやリンク一覧で移動するスクリーンリーダーのユーザーには、視覚的に隣接する要素が見えません。ラベル、説明、状態は近くにあることで暗示するのではなく、プログラムで要素に関連付ける必要があります。
3. 動的な変更は読み上げる - スクリーンリーダーが変更に気づくのは、フォーカスが新しいコンテンツに移動した場合、またはライブリージョンが変更を通知した場合だけです。AT から通知されない DOM の変更は認識できません。

---

既存の UI を監査する場合

次の優先順位で確認してください。影響の小さい問題を整える前に、重大な問題を修正してください。

優先度	カテゴリ	WCAG レベル	参照先
1	アクセシブルな名前（ボタン、入力欄、リンク）	A	references/aria-patterns.md
2	キーボード操作（すべてのインタラクティブ要素）	A	references/focus-management.md
3	フォーカス管理（ダイアログ、SPA、ライブリージョン）	A/AA	references/focus-management.md
4	セマンティックな構造（見出し、ランドマーク、リスト）	A	references/wcag-checklist.md
5	フォームのエラーと検証	A/AA	references/common-fixes.md
6	色のコントラストと視覚的な状態	AA	references/wcag-checklist.md
7	動的コンテンツの通知	AA	references/aria-patterns.md
8	画像とメディア	A	references/wcag-checklist.md
9	モーション、点滅、時間制限（動きを減らす設定、発作への配慮、自動更新コンテンツ）	A/AA	references/wcag-checklist.md

問題のある箇所を正確に引用し、該当する WCAG 達成基準を明記したうえで、実行可能な最小限の修正を提案してください。無関係なコードはリファクタリングしないでください。

---

新しい UI を構築する場合

簡単な判断フロー

Need an interactive control?
  ↓
Does a native HTML element do this?  → YES → Use it. Done.
  ↓ NO
Use the correct ARIA role + required attributes + keyboard handler.

Adding dynamic content?
  ↓
Does focus move to the new content? → YES → No live region needed.
  ↓ NO
Is it a transient status (toast, cart count, form error)?
  → Use aria-live="polite" (or role="alert" for errors)

Opening a dialog/modal?
  → Trap focus inside. Restore focus to trigger on close.
  → See references/focus-management.md

インタラクティブコンポーネントをリリースする前の必須チェック項目

• すべての input、select、textarea に関連付けられた <label> がある（プレースホルダーだけでは不可）
• すべてのボタンにアクセシブルな名前がある（テキストコンテンツ、aria-label、または aria-labelledby）
• アイコンのみのコントロールには aria-label があり、アイコンには aria-hidden="true" がある
• すべてのインタラクティブ要素でフォーカスが視認できる（代替手段なしに outline: none を指定しない）
• Tab キーの移動順序が論理的で、視覚的な順序と一致している
• すべてのポインター操作にキーボードでの代替手段がある
• 0 より大きい tabindex がない
• インタラクティブなターゲットは少なくとも 24×24 CSS px であるか、間隔を空けて配置されている（WCAG 2.5.8）
• 必須でない動きは prefers-reduced-motion に従い、1 秒あたり 3 回を超えて点滅するものがない（WCAG 2.3.1）

---

スクリーンリーダーで特に重大な 5 つの問題（および修正方法）

このスキルのスクリーンリーダーの観点から、最もよく遭遇する問題です。（サイト全体で最も件数の多い問題である、低コントラストのテキストや代替テキストの欠落については、以下の「色とコントラスト」および「画像」で説明しています。）

1. アクセシブルな名前のないアイコンのみのボタン - 単に「ボタン」と読み上げられます。ボタンに aria-label、アイコンに aria-hidden="true" が必要です。
2. ラベルのない入力欄 - プレースホルダーはラベルではありません。関連付けられた <label for> が必要です。
3. ボタンとして使われている div または span - キーボード操作に対応せず、ロールもありません。<button> を使ってください。
4. フィールドに関連付けられていないエラー - 視覚的に隣接するテキストは読み上げられません。aria-describedby と aria-invalid で関連付けてください。
5. 動的コンテンツが通知されずに更新される - ライブリージョンがないと、AT では DOM の変更を認識できません。

上記 5 つすべての修正前後の例：references/common-fixes.md（それぞれ修正 1、2、5、3、23）。

---

スクリーンリーダーのテスト

自動化ツールで検出できるアクセシビリティの問題は約 30～40％です。残りには AT でのテストが必要です。

最低限必要なテストマトリックス：

• NVDA + Firefox または Chrome（Windows） - 無料で厳格にテストでき、デスクトップで最もよく使われている 2 つのリーダーの 1 つです
• VoiceOver + Safari（macOS/iOS） - Apple プラットフォーム全体で主流のリーダーです
• 企業での利用を想定した JAWS + Chrome - もう 1 つの主要なデスクトップリーダーです

手動でテストする基本的なナビゲーションパターン：

1. Tab キーですべてのインタラクティブ要素を順に移動する - 名前とロールは正しく読み上げられますか？
2. H を押して見出し間を移動する - ページ構造は論理的ですか？
3. D を押してランドマーク間を移動する - 各領域に明確なラベルが付いていますか？
4. ダイアログを開閉する - フォーカスはダイアログ内にとどまり、その後元の位置に戻りますか？
5. エラーのある状態でフォームを送信する - エラーメッセージは読み上げられますか？
6. 動的コンテンツの更新を発生させる - 変更は読み上げられますか？

NVDA/JAWS/VoiceOver のコマンド、ブラウズモードとフォームモード、およびテストスクリプトについては、references/screen-readers.md を参照してください。

---

ARIA：ルール

ルール 0： ネイティブ HTML で解決できる場合は、ARIA を使わないでください。不適切な ARIA は、ARIA を使わない場合よりも悪影響があります。

ルール 1： aria-label と aria-labelledby はアクセシブルな名前（要素が何であるか）を提供します。 ルール 2： aria-describedby は補足的な説明（要素が何をするか、または何を必要とするか）を提供します。 ルール 3： 緊急性のない更新には aria-live="polite" を使い、エラーには role="alert"（暗黙の assertive）を使います。 ルール 4： ライブリージョンはページ読み込み時に DOM 内に存在している必要があります。テキストをその中に挿入し、リージョン自体を挿入してはいけません。 ルール 5： aria-hidden="true" を指定すると、AT のツリーから完全に除外されます。フォーカス可能な要素には決して適用しないでください。

ARIA パターンライブラリの全文 → references/aria-patterns.md

---

視覚的に隠すコンテンツ

スクリーンリーダーには表示し、視覚的には隠すには、.visually-hidden ユーティリティクラスを使います。標準的な CSS については、references/common-fixes.md の「The Visually Hidden Utility Class」を参照してください。

用途：スキップリンク、リンクの補足的な文脈（「さらに読む about caching」）、翻訳上の理由から aria-label の使用が難しい場合のアイコンボタンのラベル。

使用しないでください： 視覚でコンテンツを確認するユーザーにも必要なコンテンツ。意味のあるコンテンツを特定のグループから隠すことは、アクセシビリティではなく格差を生みます。

---

色とコントラスト（WCAG AA）

コンテンツの種類	最小比率
本文（<18pt / 24px、かつ<14pt 太字 / 18.5px）	4.5:1
大きな文字（≥18pt / 24px、または≥14pt 太字 / 18.5px）	3:1
UI コンポーネント（境界線、アイコン、フォーカスリング）	3:1
プレースホルダーテキスト	4.5:1
無効化された要素	対象外

色だけで情報を伝えないでください。必ず形、パターン、またはテキストラベルを組み合わせてください。

ユーザーの色設定を尊重してください。prefers-color-scheme をサポートし、Windows High Contrast / forced-colors: active でテストしてください。これを上書きしてはいけません（意味のあるコンテンツに forced-color-adjust: none を指定しないでください）。references/wcag-checklist.md を参照してください。

accessibility スキルディレクトリにある、正確な前景色と背景色の組み合わせを確認してください。

python3 scripts/contrast-check.py '#333333' '#ffffff'
python3 scripts/contrast-check.py '#767676' '#ffffff' --json
python3 scripts/contrast-check.py '#949494' '#ffffff' --target large-text
python3 scripts/contrast-check.py '#949494' '#ffffff' --target ui-component

終了ステータスを該当するしきい値に従わせるには、--target normal-text（デフォルト）、large-text、ui-component、aaa-normal-text、または aaa-large-text を使用してください。コントラスト値を切り上げないでください。測定値が 4.499:1 の場合、4.5:1 の要件を満たしません。

WCAG 2 AA（この表）だけを適合性の目標とします。 比率の計算は対称で極性を考慮しないため、ダークモードの組み合わせを過大評価する場合があります。合格した組み合わせでも暗い背景で読みにくい場合は、デザイン上の問題として扱い、知覚的なツール（APCA）で妥当性を確認してください。APCA は、草案段階で日付未定の WCAG 3 に向けた候補アルゴリズムです（合意形成待ちで、2023年7月の草案から削除されたこともあります）。あくまでデザインの補助であり、適合性評価の代替には決してなりません。

---

参照ファイル

ファイル	内容
references/screen-readers.md	NVDA／JAWS／VoiceOver のコマンド、ブラウズモードとフォームモード、コンポーネントの種類ごとのテスト用スクリプト
references/aria-patterns.md	ARIA ロール、ラベル付けの階層、ライブリージョンのパターン、複雑なウィジェットの ARIA（コンボボックス、タブ、ツリー）
references/focus-management.md	モーダルのフォーカストラップ、SPA のルート変更時のフォーカス、スキップリンク、フォーカス復元のパターン
references/wcag-checklist.md	WCAG 2.2 AA の達成基準ごとのチェックリストと合格／不合格の例
references/common-fixes.md	監査でよく見つかる20項目に対する、コードレベルの修正テンプレート
scripts/contrast-check.py	前景色と背景色の16進数の組み合わせを対象とする、決定論的な WCAG コントラスト比チェッカー
tests/test_contrast_check.py	チェッカーの動作テスト（比率、終了コード、16進数の解析） - uv run --with pytest -- pytest tests/