accessibility-excellence

アクセシビリティの卓越性

キーボードだけで操作するユーザー、スクリーンリーダーを使うユーザー、弱視のユーザーなど、誰もが製品を使えるようにします。実際のコードを WCAG のチェック項目に照らして監査し、失敗項目を優先順位の高いものから修正します。**最優先の原則：まずセマンティック HTML を使い、ネイティブ要素では補えない部分に限って ARIA を使います。アクセシビリティの問題の大半は、適切な役割に誤った要素が使われていることが原因です。**優先順位を付けた監査結果と実装済みの修正を提供し、コンプライアンスの講義はしません。

使用する場面／使用しない場面

次の用途に使用します：アクセシビリティ監査、WCAG 準拠作業、キーボード／フォーカスの動作、ARIA とスクリーンリーダーのサポート、コントラストの問題、アクセシブルなフォーム／モーダル／メニュー、代替テキストとキャプション。

実際のニーズが次の場合は、代わりに適切なスキルへ引き継ぎます：

• カラーパレット自体の設計（初めからアクセシブルなトークン）→ skills/frontend-design/color-system
• 動きの低減とアニメーションの安全性を詳しく扱う → skills/frontend-design/interaction-physics（このスキルでは監査し、そちらでは動きのレイヤーを実装します）
• ARIA の配線を超えたエラーメッセージの UX → skills/frontend-design/error-handling-recovery
• アクセシビリティ対応の前に、乱雑なコンポーネントを再構成する → skills/frontend-design/component-architecture

ステップ 0 — コードベースを調べてから、残ったことだけを尋ねる

1. 現在の ARIA／セマンティクスの使用状況を測定します：aria-、role=、alt=、tabIndex、<main、<nav、<button、div／span 上の onClick、outline: none、label／htmlFor を grep します。クリック可能な div と実際のボタンの比率は、状態を素早く把握するための指標です。
2. インタラクティブな箇所を洗い出します：フォーム、モーダル／ダイアログ、メニュー／ドロップダウン、タブ、ツールチップ、カスタムウィジェット（ドラッグ＆ドロップ、スライダー、コンボボックス）。ここがキーボード／ARIA のリスクの大部分を占めます。
3. 見出し構造（h1 は 1 つ、レベルを飛ばさない）、ランドマークの使用状況、<html lang>、スキップリンク、画像の代替テキストの網羅状況、動画のキャプションを確認します。
4. 実行可能な環境がある場合は、自動スキャン（axe-core／Lighthouse a11y）を実行して基準値を確認します。ただし、実際の問題の約 3 分の 1 から半分程度を検出するものとして扱い、監査全体の代わりにはしません。
5. コンポーネントスタックを確認します：すでにヘッドレスのアクセシビリティライブラリ（Radix、React Aria、Headless UI、ネイティブの <dialog>）があれば、手作りするより採用して修正するほうが効果的です。

**状況に応じて WCAG の目標を選びます。不明確な場合に限り尋ねてください：**デフォルトは WCAG 2.2 AA（法令や規制への対応で一般的な基準です。ADA、EAA、Section 508 では AA が参照されます）。政府／公共部門／教育機関では → AA が必須です。AAA の特定の基準も検討してください。全体を AAA にするのは現実的ではありません。特定の AAA 基準（例：コントラスト 7:1）は、弱視のユーザーが多い対象者にサービスを提供する場合、またはユーザーから求められた場合に限って適用してください。ユーザーに尋ねるのは、コンプライアンスの期限／要件があるか、アプリが大規模な場合は最も重要なフローはどれか、だけにしてください。それ以外の場合は「WCAG 2.2 AA に準拠する形で監査します」と明示して進めます。

ワークフロー

1. POUR のチェック項目に照らして監査する

references/checkpoints.md のチェック項目表に沿って、4 つの原則を確認します（監査時に参照してください）。適用する AA の主な基準値は次のとおりです。概算せず、正確な数値を使ってください。

• **コントラスト：**通常のテキストは 4.5:1 以上、大きなテキスト（24px 以上、または太字で 18.66px 以上）は 3:1 以上、テキスト以外の UI コンポーネントとフォーカスインジケーターは 3:1 以上。（AAA：7:1／4.5:1）
• **ターゲットサイズ（WCAG 2.2 AA）：**ポインターのターゲットは 24×24 CSS px 以上。44×44 は AAA／モバイル HIG の基準です。
• **キーボード：**すべての操作をキーボードで実行可能にすること。すべての場所でフォーカスを視認できること。tabindex を 0 より大きくしないこと。（意図的に設けた、解除可能なモーダルのフォーカストラップを除き）トラップを作らないこと。
• **点滅：**1 秒間に 3 回を超えて点滅するものがないこと。

2. すべての指摘に重大度を付ける

• ブロッカー — ユーザーが主要なタスクを完了できません（操作部品に到達できない、フォーカストラップ、チェックアウト画面のラベルのないフォーム、キーボード操作の経路がない）。
• 深刻 — タスクは完了できますが、大幅に使いづらくなっています（読み上げの欠落、主要なテキストのコントラスト不足、読み上げ順序の誤り）。
• 中程度 — 操作に手間がかかります（リンクテキストが曖昧、読み上げが冗長、補助的なテキストの軽微なコントラスト不足）。
• 軽微 — 仕上げの問題です（装飾画像の代替テキストが冗長、aria-current の欠落）。

修正順：ブロッカー → 深刻 → 中程度。指摘を重大度順に提示してください。大規模なコードベースでは、一括修正の前に対象範囲をユーザーに確認し、それ以外の場合は修正を進めてください。

3. 次の判断ルールに従って修正する

• ネイティブ要素と ARIA による後付けのどちらにするか： <div onClick> がボタン／リンク／チェックボックスとして動作している場合は、ネイティブ要素に置き換えてください。その変更だけで、ロール、キーボード操作、フォーカスがまとめて解決します。ネイティブ要素では対応できない場合に限り、role／tabIndex／キーイベントハンドラーを追加してください。
• カスタムウィジェットとライブラリのどちらにするか： モーダル、メニュー、コンボボックス、タブには、フォーカストラップや矢印キーの処理を独自実装する前に、プロジェクトで既に使われているヘッドレスライブラリ、またはネイティブの <dialog> を採用してください。ライブラリが存在せず、追加も望ましくない場合に限り、独自実装してください。
• コントラストの修正： 個別の箇所ではなく、トークンを調整してください。問題のある色が定義されている場所を探し、定義元を修正してください（パレットの再設計が必要な場合は skills/frontend-design/color-system と連携してください）。
• 読み上げ： タスクを妨げるエラーには role="alert" を使い、バックグラウンドの状態通知には aria-live="polite" を使ってください（領域はあらかじめ DOM に存在している必要があります）。フォーカスを移動するのは、ナビゲーション規模のコンテキスト変更がある場合に限ってください。
• ラベル： 表示される <label for> を優先し、次に aria-label、その次に aria-labelledby の連鎖を使ってください。プレースホルダーは決してラベルの代わりにはなりません。

標準的なパターン（フォーカストラップ、スキップリンク、ライブリージョン、フィールドエラーの関連付け、ウィジェットごとの想定キー）：references/checkpoints.md。

4. 検証する

修正したフローについて、最低限、キーボードだけで一通り操作し（到達、操作、フォーカスの確認、終了）、可能であれば自動スキャンを再実行し、ズームを 200％ に設定して、アクセシビリティツリーを確認しながら読み上げ内容と名前を検証してください。実際のスクリーンリーダーでのテストなど、検証できなかったことは明記し、ユーザーにも実施するよう伝えてください。確認していない範囲について、適合していると決して主張しないでください。

必須の出力形式

次の成果物を両方提出してください。

1. コード — 既存のコンポーネント規約に従って実装した修正（セマンティック要素への置き換え、ラベル、フォーカス管理、ARIA の関連付け、コントラストトークンの変更）。

2. アクセシビリティ監査（Markdown）：

## Scope & target
Pages/flows audited; target: WCAG 2.2 AA; tools used (axe/Lighthouse/manual keyboard).

## Findings
| # | Severity | Issue | WCAG criterion | Location | Fix | Status |
| 1 | Blocker | Checkout "Pay" is a div, keyboard-unreachable | 2.1.1 | Checkout.tsx | native <button> | fixed |
| 2 | Serious | Placeholder-only labels on signup | 3.3.2 | SignupForm.tsx | <label for> added | fixed |
| 3 | Serious | Body text #9CA3AF on #F9FAFB ≈ 2.5:1 | 1.4.3 | tokens.css | darkened token to pass 4.5:1 | fixed |
| 4 | Moderate | No skip link | 2.4.1 | layout | added | fixed |

## Verified
- Keyboard walk-through: [flows] ✓
- Automated scan: [before → after issue count]

## Not verified — user action required
- Screen reader pass (VoiceOver/NVDA) on [flows]
- [anything environment prevented]

## Recurring root causes
[e.g. "clickable divs pattern-wide — adopt lint rule jsx-a11y"]

品質基準（提出前に確認）

• すべての指摘に WCAG の達成基準と重大度を記載する — 感覚的な指摘は不可
• すべてのブロッカーを修正するか、ユーザーが明示的に対応しないと判断している
• 提出するコードのどこにも、新たな <div onClick>、置き換えなしの outline: none、正の値の tabindex、ラベルとしてのプレースホルダーを導入していない
• コントラストの修正はトークン／定義元で行い、計算後の値を使って 4.5:1／3:1 の基準を満たすことを検証している
• 対象範囲内のすべてのモーダル／メニューで、フォーカスが内部に移動し、正しくトラップされ、Escape キーが機能し、トリガーにフォーカスが戻る
• すべてのフォームコントロールにプログラムで認識可能なラベルがあり、すべてのエラーが aria-describedby で関連付けられ、読み上げられる
• 見出しの階層が正しく、ランドマークがあり、lang が設定され、スキップリンクが最初にフォーカス可能になっている
• 「未検証」セクションに未テストの対象範囲を正直に記載しており、適合性を過大に主張していない

絶対にしてはいけないこと：正常に機能するネイティブ要素に ARIA をむやみに追加しない。自動スキャンだけを根拠に「WCAG に準拠」と主張しない。場当たり的な新しい色を作ってコントラストを修正しない。同等以上に視認できる代替手段を用意せずに、フォーカスアウトラインを削除しない。

統合

• skills/frontend-design/component-architecture → コンポーネント一覧を提供します。修正は共有コンポーネントに適用されるため、その変更は各所に反映されます。繰り返し発生する問題は、コンポーネントレベルの規約としてフィードバックしてください。
• skills/frontend-design/color-system → コントラストの問題が単一のトークンではなく、システム全体に及ぶ場合にパレットの再設計を担当します。
• skills/frontend-design/error-handling-recovery → エラー文言と復旧時の UX を担当します。このスキルでは、従うべき role="alert"／aria-invalid／フォーカスのルールを示します。
• skills/frontend-design/interaction-physics → モーション低減とフラッシュ安全性の実装を担当し、このスキルではそれらを監査します。

参考資料

• references/checkpoints.md — WCAG 達成基準番号付きの POUR チェックポイント一覧表、セマンティック HTML のリファレンス、キーボード操作のパターン（フォーカストラップ、スキップリンク、ウィジェットごとに期待されるキー操作）、ARIA パターン集とよくある ARIA の誤り、メディア／コンテンツのルール、テストツールに関するガイダンスを掲載しています。監査の実施時と修正の作成時に参照してください。