check-fix-accessibility

フロントエンドのアクセシビリティを確認して修正する

あらゆるフロントエンドプロジェクトのアクセシビリティ問題を体系的に監査し、修正します。ユーザーから特別な指定がない限り、WCAG 2.2 レベル A および AA を優先します。AAA はオプトインです。reference.md を参照してください。

バージョン管理と最新性：このスキルはバージョン管理され（上記の version を参照）、last_reviewed の日付に特定の標準に照らしてレビューされています。WCAG とツールは進化します。これを信頼して使用する前に、標準と固定されたツールのバージョンが現在も最新であることを確認してください。ガイダンスを更新する場合は、version と last_reviewed、および Changelog を更新してください。

対象範囲

• Web（デスクトップ＋モバイル Web）：全面的に対象とします。このスキルは、レスポンシブや PWA を含む、HTML/CSS/JS、React、Next.js、Vue、Angular、その他の Web フレームワークに適用されます。Next.js では、ページの <title> に metadata または <Head> を使用してください。クライアント側のナビゲーションは SPA のルート変更として扱い、ルート変更時にフォーカスを更新するか、変更を通知してください（「注意が必要なケース」を参照）。フレームワークごとのラベル、ボタン、モーダル、ルーターのスニペット：frameworks.md。
• ネイティブモバイルアプリ（React Native、Swift/Kotlin、Flutter）：API やパターンが異なります（例：accessibilityLabel、accessibilityRole）。同じ原則（ラベル、フォーカス順序、セマンティクス）を適用しつつ、プラットフォーム API を使用してください。参考情報は reference.md を参照してください。

クイックワークフロー

1. 監査 – 自動チェックを実行するか、重要なページやコンポーネントをレビューします。
2. 優先順位付け – 重大（操作を妨げる）および深刻な問題から対処します。
3. 修正 – 以下のパターンに従って修正し、変更後に再確認します。
4. 検証 – キーボード操作の流れを確認し、可能であればスクリーンリーダーの動作も確認します。

監査の実行

自動ツールを少なくとも 1 つ使用し、重要な操作フローについては手動レビューも組み合わせてください。

再現性のため、ツールのバージョンを固定してください。 ツールは package.json とロックファイルで厳密なバージョンを指定し、devDependencies としてインストールします。以下の固定バージョンは、2026-10-01 にこのスキル内のスニペットに照らして確認したものです。これより新しいリリースが不適切だという意味ではありません。スニペットに変更が生じるメジャーバージョンは、そのバージョンを明記しています。

• Lighthouse（Chrome DevTools）：アクセシビリティ監査を実行します。ページ全体のスナップショットに適しています。レポートには Chrome/Lighthouse のバージョンを記載してください。
• axe DevTools（ブラウザー拡張機能、または @axe-core/cli、テストでは axe-core）：ルール ID を基準に問題を報告し、修正します。固定バージョン：npm i -D @axe-core/[email protected] [email protected]。
• pa11y（CLI）：npm i -D [email protected] を実行し、続けて npx pa11y <url> を実行します。pa11y 10 には Node ^22.13.0 または >=24 が必要です。同じコマンドで、古い Node でも動作する 9.1.1 を実行できます。
• ESLint + プラグイン：[email protected]（React）、[email protected]（Vue）。これらを CI に追加し、報告されたルールに対処します。

修正時は、ツールのルール ID（例：button-name、label、color-contrast）を使って該当する要件を確認し、適切な修正を適用してください。

デプロイ済み URL だけでなく、レンダリングされたコンポーネントをテストしてください。テスト ID よりもロールと名前によるクエリを優先してください。React、Vue、Angular の lint プラグインと axe の例：frameworks.md。React の実行時の詳細（cypress-axe、Playwright）：reference.md。

チェックリスト：よくある問題と修正方法

進捗リストとしてコピーして使用してください。これですべてではありません。監査結果に基づいて項目を追加してください。

セマンティクスと構造

• ページの言語（3.1.1 A）：<html> に lang を設定します。
• ページタイトル：各ページに、内容がわかる固有の <title> を1つ設定します。
• ランドマーク：<main>、<nav>、<header>、<footer>、<aside> を使用します（要素を使用できない場合に限り、ARIA の role="main" などを使用します）。各ページに <main> は1つだけ配置します。
• 見出し（2.4.6 AA）：見出しのテキストでセクションの内容がわかるようにします。レベルを飛ばすことはベストプラクティス上の問題であり、2.4.6 の検査対象ではなく、AA の自動的な不適合にもなりません。
• リスト：リストの内容には <ul>／<ol>／<li> を使用します。div と CSS だけで実装しないでください。
• ボタンとリンクの使い分け：操作（送信、モーダルを開く、切り替え）には <button> を使用します。移動には <a href="..."> を使用します。ボタンやリンクに <div> や <span> を使用しないでください。
• 一貫したヘルプ（3.2.6 AA）：すべてのページで、ヘルプを同じ相対的な順序に配置します。理由を参照してください。

フォーカスとキーボード

• フォーカスの可視化（2.4.7 AA）：すべてのインタラクティブ要素に、視認できるフォーカスインジケーターを設定します。代替手段を用意せずにアウトラインを削除しないでください。
• タブ順序（2.4.3 A）：DOM の順序を視覚的な順序と一致させます。正の値の tabindex は使用しないでください。aria-flowto 属性はありません。
• キーボードトラップなし（2.1.2 A）：意図的にフォーカスをトラップするモーダルを除き、常にフォーカスを移動できるようにします。モーダルは閉じた後にフォーカスを解放します。
• キーボード操作可能（2.1.1 A）：マウスで行える操作はすべて、キーボードでも行えるようにします（Enter／Space を使うか、ホバー時のみではなくフォーカス可能なコントロールにします）。
• フォーカストラップ：モーダルが開いている間はフォーカスをトラップし、閉じた後は起動元にフォーカスを戻します。
• スキップリンク（2.4.1 A）：「メインコンテンツへスキップ」をフォーカス時に表示し、<main> にフォーカスを移動します。
• フォーカスが隠れないこと（2.4.11 AA）：固定ヘッダー、フッター、バナーで、フォーカス中の要素が完全に覆われないようにします。理由を参照してください。
• 文字キーのショートカット（2.1.4 A、AA ではない）：1文字のショートカットは、無効化、再割り当て、またはコントロールにフォーカスがある場合にのみ有効化できるようにします。
• ドラッグ操作の代替手段（2.5.7 AA）：ドラッグ操作は、クリック、タップ、またはテキストフィールドによる操作でも行えるようにします。

フォームとラベル

• ラベル：すべてのコントロールに <label>（for／id または内包形式）または aria-label／aria-labelledby を設定します。プレースホルダーはラベルではありません。
• 名前にラベルのテキストを含める（2.5.3 AA）：アクセシブルネームに、視覚的に表示されるテキストを含めます。aria-label は内容を置き換えるため、すでにラベルが表示されているコントロールには使用しないでください。
• エラー（3.3.1 A）：エラーは色やライブリージョンだけではなく、テキストとして表示します。aria-describedby でエラーを示し、aria-invalid="true" を設定して、該当する間はエラーを DOM 内に保持します。
• 必須／任意：必須フィールドはテキストと aria-required または required 属性で示します。
• グループ化：ラジオボタンやチェックボックスのグループには、<fieldset> と <legend> を使用します。
• 利用できないコントロール：disabled を設定すると、そのコントロールはタブ順序から除外されます。ユーザーがフォーカスして理由を聞く必要がある場合は、aria-disabled="true" を使用します。
• 入力目的（1.3.5 AA）：autocomplete（name、email、tel、street-address など）を設定します。
• アクセシブルな認証（3.3.8 AA）：貼り付けやパスワードマネージャーを利用できるようにします。パズルや文字の書き起こしを唯一の認証方法にしないでください。
• 重複入力（3.3.7 AA）：1つのプロセス内で同じ情報を再度求めないでください。自動入力するか、ユーザーが選択できるようにします。
• フォーカス時や入力時に予期しない動作をさせない（3.2.1 A、3.2.2 A）：コントロールにフォーカスしたり入力したりしただけで、コンテキスト（送信、移動、新しいウィンドウの表示）が変わらないようにします。

画像とメディア

• 代替テキスト：意味のある画像すべてに、内容や機能を説明する alt を設定します。装飾目的の画像には alt="" を使用します。
• 複雑な画像：グラフや図などには、詳しい説明（詳細説明ページ、aria-describedby、または表示されるテキスト）を用意します。
• 動画／音声：必要に応じて字幕や文字起こしを提供し、コントロールがキーボードで操作でき、ラベルが付いていることを確認します。

ARIA（HTML だけでは不十分な場合）

• ロール：まずネイティブ要素（button、link、heading など）を使用します。カスタムウィジェット（例：role="dialog"、role="tablist"）に限り、ARIA ロールを追加します。
• 名前：インタラクティブ要素や領域には、アクセシブルな名前を付けます。aria-label、aria-labelledby、または表示されるテキストコンテンツを使用します。
• ライブリージョン：アナウンスが必要な動的コンテンツ（トースト、エラー、更新）には、aria-live、aria-atomic、aria-relevant を使用します。緊急でない場合は、aria-live="polite" を優先します。
• 状態：aria-expanded、aria-selected、aria-current などを使って状態（展開／折りたたみ、選択済み、現在）を公開し、UI と同期させます。
• 避けること：すでにそのセマンティクスを持つ要素に role／aria-* を使用しないでください（例：<button> に role="button" を指定する）。フォーカス可能なコンテンツに aria-hidden="true" を追加することも、できるだけ避けてください。
• ホバー時またはフォーカス時のコンテンツ（1.4.13 AA）：ツールチップは閉じることができ（Escape）、ホバー可能で、表示を維持できるようにします。根拠を参照してください。
• ステータスメッセージ（4.1.3 AA）：フォーカスを移動させない結果（トースト、「保存しました」、フォームエラー）は、ライブリージョンを通じて通知します。

色とコントラスト

• コントラスト（1.4.3 AA）：通常のテキストは 4.5:1、大きなテキストは 3:1 です。reference.mdを参照してください。
• 非テキストのコントラスト（1.4.11 AA）：意味のあるアイコンやコントロールの境界は、隣接する色に対して少なくとも 3:1 のコントラスト比を確保します。
• 色だけに頼らない（1.4.1 A）：テキスト、アイコン、またはパターンを追加します。色だけを手がかりにすることはできません。
• 強制カラー：意味を伝えるために背景画像に頼らないでください。根拠を参照してください。

動きとアニメーション

• 一時停止、停止、非表示（2.2.2 A）：5 秒を超えて動く、点滅する、または自動更新するコンテンツは、一時停止、停止、または非表示にできるようにします。
• 動きを減らす（2.3.3 AAA）：必須ではないアニメーションでは、prefers-reduced-motion: reduce を尊重します。これは AAA であり、AA ではありません。

レスポンシブ対応とズーム

• テキストの拡大（1.4.4 AA）：テキストを 200% まで拡大しても、切り取られないようにします。user-scalable=no は設定せず、テキストが切れてしまう場合はサイズを px に固定しないでください。
• リフロー（1.4.10 AA）：ズーム率 400% で、二次元スクロールが必要になるのは、地図、表、図など、二次元スクロールが必要なコンテンツに限られます。これは 1.4.4 とは別の基準です。
• テキストの間隔（1.4.12 AA）：ユーザーによる間隔の上書きで、コンテンツが切り取られないようにします。根拠を参照してください。
• タッチターゲット（2.5.8 AA）：少なくとも 24×24 CSS px にするか、この基準を満たす間隔を確保します。44×44 は AAA／プラットフォームでの慣例であり、AA の最低基準ではありません。reference.mdを参照してください。

特殊なケースと例外的なケース

自動ツールでは見落とされがちなので、これらには明示的に対応してください。

スクリーンリーダー

• スクリーンリーダー専用テキスト：表示ラベルが冗長になる場合（アイコンのみのボタンなど）は、SR に表示されるラベル（.sr-only／aria-label など）を追加し、コントロールに明確な名前を付けます。重要なラベルを title だけに頼らないでください。
• テーブル：データテーブルには <table>、scope または headers を指定した <th>、および <caption> または aria-labelledby を使用し、スクリーンリーダーのユーザーがセル単位で移動できるようにします。レイアウト目的でテーブルを使用しないでください。
• iframe：すべての <iframe> に説明的な title（または aria-label）を指定し、SR ユーザーがその領域の内容を把握できるようにします。
• リンクの目的（2.4.4 A）：リンクの目的が、リンクテキストとその文脈（文、リスト項目、セル）から明確に分かるようにします。「続きを読む」は、文脈からリンク先が分かる場合、A／AA に適合します。単独で目的が分かるリンクテキストは 2.4.9 AAA の要件です。reference.md を参照してください。
• 重複した読み上げ：同じ内容が二度読み上げられないようにします（例：aria-label と表示テキストの両方で同じ内容を示す、1 回の更新に複数のライブリージョンを使用する）。情報源は明確なものを 1 つにします。
• 部分ごとの言語：ページと異なる言語のコンテンツを含む要素には lang を指定します（例：<span lang="fr">）。SR が適切な発音を使用できるようにします。
• 読み上げ順序：ライブリージョンやフォーカス移動によって、分かりにくい順序にならないようにします（例：「読み込み中」が消える前に結果が読み上げられる）。読み込み中は aria-busy を設定し、コンテンツの準備ができたら解除します。

音声コントロールと VoiceView

これらは異なるツールです。VoiceView を音声入力として扱わないでください。

• 音声コントロール（Voice Access、macOS Voice Control、Dragon）：ユーザーはアクセシブルな名前を声に出します（「登録を送信をクリック」など）。名前は短く、一意にします。「1 番目のボタン／2 番目のボタン」よりもこちらを優先してください。
• VoiceView（Amazon Fire OS のスクリーンリーダー）：TalkBack と同様に、名前、ロール、状態を読み上げます。音声コマンドを使う製品ではありません。テスト手順：reference.md。

シングルページアプリ（SPA）と動的コンテンツ

• ルート／ビューの変更：ナビゲーション時に <title> を更新し、フォーカスをメインコンテンツに移動するか、変更を読み上げます（例：aria-live="polite" のリージョンを使用する、または <main>／見出しにフォーカスを移動する）。これにより SR ユーザーはページが変わったことを把握できます。スキップリンクと <main> は同じ移動先にします。React Router、Next.js、Vue Router、Angular：frameworks.md。React のフォーカストラップライブラリ：reference.md。
• 読み込み状態：読み込み中のコンテナーに aria-busy="true" を指定し、完了したら false に設定します。任意でライブリージョンを使用して、「読み込み中…」の後に結果を読み上げることもできます。
• 非表示だがフォーカス可能：非表示のコンテンツ（display: none、hidden、非アクティブなタブパネルなど）にフォーカス可能な要素を含めないでください。含める場合は、アクセシビリティツリーからそれらの要素を除外する必要があります（例：コンテナーに aria-hidden="true" を指定する、または対応環境では inert を使用する）。そうしないと、キーボード／SR ユーザーが「見えない」要素にフォーカスできてしまいます。

その他

• 時間制限：コンテンツに時間制限（セッションのタイムアウト、クイズなど）がある場合、時間を延長、無効化、または調整する方法を提供します（WCAG 2.2）。
• CAPTCHA／認証：アクセシブルな代替手段（音声 CAPTCHA、代替タスクなど）を提供し、キーボード／SR で操作できるフローにします。
• RTL：右から左に記述する言語では、文書またはコンテナーに dir="rtl"（または適切な dir）を設定し、レイアウトと読み上げ順序が正しくなるようにします。
• サードパーティの埋め込みコンテンツ：制御できないウィジェットや iframe を埋め込む場合、アクセシブルにするよう明記するか、代替手段（同じコンテンツへの別の場所にあるリンクなど）を提供します。

修正パターン（簡潔版）

• カスタムコントロール：ネイティブ要素を使用します。使用できない場合は、role、tabindex="0"（またはスクリプトでフォーカスを管理する場合は -1）、アクセシブルな名前、Enter／Space キーへの対応を追加します。
• モーダル：showModal() で開く <dialog> を優先します。現在のブラウザーではフォーカスがトラップされます。aria-modal は保証されないため、ダイアログに aria-labelledby を指定します。カスタムダイアログには、role="dialog"、aria-modal="true"、aria-labelledby を指定し、ダイアログ内にフォーカスを移動し、フォーカスをトラップし、Escape キーで閉じられるようにして、トリガーにフォーカスを戻す必要があります。
• 展開／折りたたみ：トリガーに aria-expanded と aria-controls、パネルに id を指定し、Enter／Space キーで切り替えます。
• タブ：role="tablist"、role="tab"（aria-selected、aria-controls を指定）、role="tabpanel"（id を指定）を使用します。矢印キーでタブを切り替え、Enter／Space キーで有効化します。
• エラーメッセージ：コントロールに aria-describedby="id-of-error" を指定し、無効な場合は aria-invalid="true" を指定します。無効な場合に、エラー要素に id があり、DOM 内に存在することを確認します。

フィードバックの提供

問題を報告するときは、次の分類を使用します。

• 重大：アクセスを妨げます（例：フォーカスできない、ラベルがない、キーボードで操作する方法がない）。最初に修正します。
• 深刻：大きな障壁になります（例：コントラストが不十分、セマンティクスが誤っている）。早めに修正します。
• 軽微：使いやすさを向上させます（例：不要な ARIA、見出しの順序）。可能なときに修正します。

次の内容を含めます：重大度、ファイルまたはコンポーネント、要素またはセレクター、ルールまたはガイドライン、具体的な修正方法。

例

深刻 — src/components/IconButton.tsx — button.icon-delete — axe button-name（4.1.2 名前、ロール、値、A）。この削除コントロールはアイコンのみの <button> で、アクセシブルな名前がありません。aria-label="Delete item" または視覚的に隠したテキストを追加します。このコンポーネントで axe を再実行し、button-name が解消されたことを確認します。その後、Tab キーでボタンに移動し、Enter キーと Space キーで操作します。

修正後

• 同じ監査ツールを再実行し、違反が解消されたか、理由が説明されていることを確認します。
• その一連の操作をキーボードのみで行い、ナビゲーションをテストします。
• 可能であれば、変更したコンポーネントをスクリーンリーダー（例：NVDA、VoiceOver）でテストします。

参考資料

WCAG の基準、ARIA パターン、コンポーネントの例について詳しくは、より詳細なガイダンスが必要なときに reference.md を参照してください。上記のチェックリストと reference.md の内容が重複する場合（例：コントラスト比、ターゲットサイズ、テーブル）は、reference.md を正式な情報源とし、まずこちらを更新してチェックリストも同期してください。

変更履歴

• 1.8.0（2026-10-01）：ツールのバージョン固定を再確認し、7月の固定バージョンを最新として扱うのをやめました。axe CLI と axe-core は 4.13.0、Vue ESLint プラグインは 2.6.0、pa11y は 10.0.0（Node 22.13+）、jest-axe は 11.0.0 です。@testing-library/jest-dom は、7.0.1 が Vitest のみをピア依存関係としているため、6.9.1 のままです。ルート変更時のフォーカスはアプリシェル内の <main> 1つに設定し、初回読み込み時はスキップします。Axe の例では expect.extend を呼び出します。文脈を踏まえたリンクの目的は 2.4.4 A であり、文脈を離れたリンクテキストは引き続き AAA です。見出しに関する 2.4.6 は説明であり、アウトラインではありません。1.4.4 のテキストサイズ変更、3.3.1 のエラーの可視化、コンボボックスのパターン、サイトナビゲーションは role="menu" ではないという警告、ネイティブのモーダル、装飾画像、動的な文字サイズに関する注記を追加しました。showModal() が aria-modal を設定するという記述は削除しました。
• 1.7.0（2026-10-01）：オプトイン方式の WCAG AAA セクションを追加しました（コントラスト 7:1、フォーカスの視認性向上、フォーカスの外観、44×44 のターゲット、リンクテキストのみから判断できるリンクの目的、動きの軽減、アクセシブルな認証の強化）。A と AA が引き続きデフォルトです。コピーして貼り付けられる a11y:axe / a11y:pa11y npm スクリプトの例を追加しました。このリポジトリにはランナーは含まれていません。
• 1.6.0（2026-10-01）：スクリーンリーダーに関する一行の注記を、NVDA、JAWS、VoiceOver、TalkBack、Amazon VoiceView の合否判定手順に置き換えました。移動と有効化に使うジェスチャーも含みます。VoiceView は引き続きスクリーンリーダーとして扱い、両者を混同しないよう Samsung Voice Assistant も明記しました。視覚的に隠す CSS の例は、テキストを実際に隠すようになりました。
• 1.5.0（2026-10-01）：ラベルと ID、ネイティブボタン、モーダル（createPortal、<Teleport>、cdkTrapFocus / CDK ダイアログ）、ルート変更時のフォーカス（React Router、Next.js、Vue Router、Angular NavigationEnd）に関する React、Vue、Angular のパターンをまとめた frameworks.md を追加しました。Vue と Angular のコンポーネント axe テストを、既存の React テストと並べて配置しました。共通のアンチパターンは引き続きこのファイルに記載しています。
• 1.4.0（2026-10-01）：チェックリストの正確性を修正しました。存在しない aria-flowto 属性を削除し、2.1.4「文字キーショートカット」は AA ではなくレベル A であること、見出しの飛ばしはベストプラクティスであり AA の自動不合格ではないことを明記しました。3.1.1 の言語、2.5.3 の名前に含まれるラベル、2.1.2 のキーボードトラップなし、1.4.11 の非テキストコントラスト、4.1.3 のステータスメッセージ、2.2.2 の一時停止／停止／非表示、3.2.1／3.2.2 を追加しました。prefers-reduced-motion に 2.3.3 AAA のラベルを付けました。<dialog> / showModal() を推奨するようにしました。音声コントロールと Amazon VoiceView を区別しました。詳細な WCAG の根拠を reference.md に移し、記入例付きの課題報告を追加しました。1.1.0～1.3.0 のツールバージョン固定は変更していません。
• 1.3.0（2026-07-05）：チェックリストから漏れていた新しい WCAG 2.2 AA 達成基準、すなわち 2.4.11「フォーカスが隠されない」、2.5.7「ドラッグ操作」、3.2.6「一貫したヘルプ」、3.3.7「冗長な入力」、3.3.8「アクセシブルな認証」に加え、1.3.5「入力目的」（autocomplete）、1.4.13「ホバーまたはフォーカス時のコンテンツ」、2.1.4「文字キーショートカット」、1.4.12「テキストの間隔」、強制カラー／ハイコントラストに関するガイダンスを追加しました。2.2 で追加されたすべての達成基準を reference.md に列挙しました。スキルフォルダー名をスキルの name とリポジトリに合わせて check-fix-accessibility に変更し、重複するガイダンスの正式な参照元は reference.md であることを記載しました。
• 1.2.0（2026-07-04）：React 固有の reference.md ガイダンスを追加しました。「React での自動テスト」（jest-axe/vitest-axe、Testing Library のロールクエリ、cypress-axe / @axe-core/playwright。すべてバージョン固定）と「React のフォーカスとルーティング」（useEffect+ref によるフォーカス、react-router、フォーカストラップライブラリ、React Aria/Radix/Headless UI などのアクセシブルなプリミティブ）を含みます。SKILL.md から相互リンクしました。
• 1.1.0（2026-07-04）：WCAG 2.2 勧告の日付（2023 年 10 月。改訂版は 2024 年 12 月）を修正しました。Robust から旧式の 4.1.1「構文解析」を削除し、ターゲットサイズ（2.5.8 AA は 24×24 CSS px、44×44 は AAA／プラットフォームのベストプラクティス）を明確にしました。ツールのバージョンを固定し、Vue ESLint プラグインのパッケージ名を修正しました。version／last_reviewed メタデータと、この変更履歴を追加しました。
• 1.0.0：初期スキル（監査ワークフロー、チェックリスト、例外ケース、修正パターン、参照資料）。