web-accessibility

開発時のウェブアクセシビリティ

UI の構築またはレビュー時にこのスキルを使用します。すべてに適用されるルールは以下に記載しています。 機能固有のパターンは references/ ファイルに記載されています。その機能を扱う場合は、該当するファイルを 読んでください。

すべてのコンポーネントに適用

以下のルールは、構築するすべてのものに例外なく適用されます。

セマンティック HTML を優先する（SC 1.3.1, 4.1.2）

動作に合ったネイティブ要素を使用します。操作には <button>、ナビゲーションには <a href>、データ入力には <input>、選択には <select>、オーバーレイには <dialog> を使用します。<div> や <span> にクリックハンドラーを付けて、インタラクティブな要素として扱ってはいけません。適切なネイティブ要素がない場合は、role、 tabindex="0"、およびキーボード操作ハンドラー（必要に応じて Enter、Space、矢印キー）を追加します。

キーボード操作（SC 2.1.1, 2.1.2, 2.4.3）

すべてのインタラクティブ要素に Tab キーで移動でき、キーボードで操作できる必要があります。 標準的な割り当ては、ボタンとリンクの実行には Enter/Space、複合ウィジェット（ラジオグループ、タブパネル、メニュー、リストボックス）には矢印キー、オーバーレイを閉じるには Escape です。意図的にモーダルを使用する場合を除き、キーボードトラップを作ってはいけません。

Tab の移動順序は、視覚上および読み上げ上の順序に従う必要があります。1 より大きい tabindex 値は使用しないでください。使用できるのは tabindex="0"（Tab 順序に追加）または tabindex="-1" （プログラムからフォーカス可能、通常の Tab 順序には含まれない）のみです。

フォーカスの視認性（SC 2.4.7, 2.4.11, 1.4.11）

すべてのインタラクティブ要素に、視認できる :focus-visible インジケーターが必要です。代替を用意せずに outline: none を指定してはいけません。フォーカスインジケーター自体は、隣接する色との非テキストコントラスト比が 3:1 以上である必要があります（SC 1.4.11）。

色のコントラスト（SC 1.4.1, 1.4.3, 1.4.11）

テキストのコントラスト比は、通常のテキストで 4.5:1 以上、大きなテキスト（18pt 以上／太字で 14pt 以上）で 3:1 以上である必要があります。テキスト以外の UI 要素（境界線、アイコン、フォーカスリング、フォームフィールドの境界）は 3:1 以上である必要があります。

比率を丸めてはいけません。 計算された比率が 4.4999 の場合、4.5:1 のしきい値を満たしません。確認には、 contrast-check.md に記載された計算方法と確認手順を使用してください。

情報を伝える唯一の手段として色を使ってはいけません。テキスト、アイコン、またはパターンを併用してください。

テキストによる代替（SC 1.1.1）

• 情報を伝える画像：文脈に沿って意味を伝える説明的な alt を指定します。
• 装飾用画像：alt="" を指定します。
• アイコンのみのコントロール：コントロールに aria-label、アイコン／SVG に aria-hidden="true" を指定します。
• 複雑な画像（グラフ、図）：aria-describedby または隣接するテキストで詳しい説明を提供します。

アクセシブルネーム（SC 4.1.2, 2.5.3）

すべてのインタラクティブ要素に、認識可能なアクセシブルネームが必要です。表示テキストがあるコントロールでは、アクセシブルネームにその表示テキストを含める必要があります（SC 2.5.3「ラベル名の一致」）。

視覚的に隠すコンテンツ（sr-only）

sr-only は、アクセシビリティツリーに要素を残したまま、視覚的に隠します。プロジェクトに既存のユーティリティがあれば、それを使用してください。ない場合は、次のようにします。

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
  border: 0;
}

display: none、visibility: hidden、width: 0; height: 0 は使用しないでください。いずれも要素をアクセシビリティツリーまたはドキュメントフローから除外します。

次の場合に sr-only を適用します。

• ネイティブ入力を視覚的にカスタム要素へ置き換える場合（ネイティブ入力に sr-only を適用し、カスタム要素に aria-hidden="true" を指定します）。
• わかりにくい操作の文章による説明を、入力欄の前に配置する場合。
• 視覚的な表現（例：色分けされた差分）に、スクリーンリーダーの利用者向けの文章による代替が必要な場合。

ページレベルの構造

ランドマークと見出し（SC 1.3.1, 2.4.6）

• ページごとに <main> を 1 つ使用します。
• ランドマークの役割には <nav>、<header>、<footer> を使用します。同じ種類のランドマークを繰り返す場合（例：<nav> 要素が 2 つ）、それぞれに一意の aria-label を指定します。
• ページごとに <h1> を 1 つ使用します。見出しはレベルを飛ばさず、論理的なアウトラインを構成します。

ページタイトル（SC 2.4.2）

すべてのページ（または SPA のルート）に、内容を説明する <title> を設定します。SPA では、ナビゲーション時にタイトルを更新します。目的が異なるルートには、それぞれ異なるタイトルを設定します。

言語（SC 3.1.1, 3.1.2）

<html> の lang 属性で言語を指定します。別の言語で書かれたインラインテキストには、その言語を示す独自の lang 属性を指定します。

スキップリンク（SC 2.4.1）

「メインコンテンツへスキップ」リンクは、ページ上で最初にフォーカス可能な要素です。フォーカスされると表示され、<main> ランドマークにフォーカスを移動します。

ライブリージョンと動的コンテンツ（SC 4.1.3）

フォーカスを移動せずに変化するコンテンツは、aria-live リージョンを通じてスクリーンリーダーに通知する必要があります。

これには、入力内容の検証結果、成功／エラーメッセージ、読み込み状態、保存確認、フィルター結果の件数、スコアの更新、トースト通知、非同期処理の結果が含まれます。

ライブリージョンのコンテナーは、コンテンツを挿入する前に DOM に存在している必要があります。 コンテナーを作成して同じ処理内で内容を設定しても、通知されません。空のコンテナーをレンダリングしてから、内容を挿入してください。

多くの場合、次の 2 つのセマンティックロールで対応できます。

<div role="status"></div>



<div role="alert"></div>

role="status" または role="alert" の要素に、aria-live や aria-atomic を明示的に追加しないでください。これらのロールには、すでに設定されています。

単独の aria-live リージョン（例：カスタムログウィジェット）が必要な場合：

• aria-live="polite" — ユーザーが現在の操作を終えるまで待ちます。
• aria-live="assertive" — ただちに割り込みます。本当に緊急性の高いエラーに限って使用してください。多用すると、ユーザーは通知を無視するようになります。
• aria-atomic="true" — 変更があるたびに、リージョン全体を読み上げ直します。一部分だけの読み上げでは意味が通じない、自己完結したメッセージ（トースト通知やステータス行など）に使用してください。
• aria-atomic="false"（デフォルト） — 変更されたノードのみを通知します。新しい項目だけを読み上げるべきコンテンツの追加（チャットログやエラーリストなど）に使用してください。

読み込み中、空、エラーの各状態は、スピナーや空白の画面だけでなく、テキストで表す必要があります。読み込みインジケーターには role="status" を使用してください。

アニメーションと動き（SC 2.2.2、2.3.1、2.3.3）

prefers-reduced-motion を尊重してください。推奨されるパターンは、ユーザーが動きを有効にする方式です。

/* No motion by default */
.element {
  opacity: 1;
}

/* Motion only when the user hasn't opted out */
@media (prefers-reduced-motion: no-preference) {
  .element {
    transition: opacity 200ms ease-in-out;
  }
}

1 秒間に 3 回を超えて点滅するものがあってはなりません。自動再生またはループするアニメーションは、5 秒を超える場合、一時停止または停止できるようにしてください。

無効なコントロール（SC 4.1.2、1.4.3）

コントロールは有効な状態を保ち、操作時に入力内容を検証して、回復可能なエラーメッセージを表示する方法を優先してください。

コントロールを利用できない状態にする必要がある場合は、HTML の disabled 属性ではなく、aria-disabled="true" を使用してください。

aria-disabled を使用する場合：

• ポインターイベントとキーボードイベントの両方で、JS によって操作をブロックしてください。
• CSS の [aria-disabled="true"] を使って、利用できない状態をスタイル設定してください。
• 要素は引き続きコントラスト要件を満たす必要があります。

ターゲットサイズとタッチ操作（SC 2.5.1、2.5.8）

インタラクティブなターゲットは、少なくとも 24×24 CSS ピクセルである必要があります（SC 2.5.8、AA）。ターゲットがこれより小さい場合は、ターゲットを中心とする直径 24px の円が、隣接するターゲットの円と重ならない場合に限り、要件を満たします。

快適にタッチ操作できるよう、特に主要な操作ポイントとなるコントロールは 44×44 CSS px を目標にしてください。

パスベースまたは複数点を使うジェスチャー（スワイプ、ドラッグ、ピンチ）も、単一のポインター（タップ／クリック）で操作できる必要があります。この基準ではキーボードのみの代替手段では不十分です。マウス／タッチのユーザーには、マウス／タッチで操作できる、ドラッグを必要としない方法が必要です。

レスポンシブ対応とリフロー（SC 1.4.4、1.4.10、1.4.12）

ビューポート幅が 320 CSS px のときに、コンテンツが横スクロールなしでリフローする必要があります（SC 1.4.10）。テキストは、クリッピングや重なりを起こさずに 200% まで拡大できる必要があります（SC 1.4.4）。ユーザーがテキスト間隔を変更したときにテキストがクリッピングされる、固定高のコンテナーは避けてください（SC 1.4.12）。

キーボードショートカット（SC 2.1.4）

アプリで Ctrl／Alt／Cmd を使わない印字可能な単一文字（英字、数字、句読点）をショートカットに割り当てる場合、そのショートカットを無効にできる、修飾キーを含むように割り当て直せる、または関連コンポーネントにフォーカスがある間だけ有効にする必要があります。少なくとも、フォーカスが <input>、<textarea>、または contenteditable 内にあるときは、単一文字のショートカットを無効にしてください。

機能固有のパターン

上記のセクションはすべての機能に共通です。特定の機能に該当する場合は、このスキルの references/ ディレクトリにある対応するリファレンスファイルを確認してください。

機能の種類	参照するファイル
フォーム、入力、検証、フィールドセット	forms.md
ダイアログ、モーダル、ドロワー、サイドバー	overlays.md
ドロップダウンメニュー、ディスクロージャー、メニューボタン	menus.md
オーディオ、動画、メディアコントロール	media.md
タブ、ツリービュー、データグリッド、コンボボックス、ドラッグ＆ドロップ、アコーディオン、カルーセル、ツールバー、リストボックス	complex-patterns.md

コンポーネントが上記のリファレンスに該当しない場合は、 WAI-ARIA Authoring Practices Guide pattern indexを確認してください。 文書化されたパターンが存在しない場合は、実装方法を提示し、実装前にユーザーに確認を求めてください。