accessibility

Web プロジェクトでアクセシビリティと高品質なコードを確保する

アクセシビリティを最初から考慮して Web プロジェクトを構築することは、特に人による手動テストが限られる状況（AI 主導の開発など）では非常に重要です。後からアクセシビリティを追加するより、最初から適切に実装するほうがはるかにコストを抑えられ、複雑さも軽減できることはよく知られています。どのような開発タスクでも、継続的な要件を十分に文書化し、アクセシビリティを最優先するアプローチを採用してください。このスキルで説明している内容にとどまらず、アクセシビリティ基準を常に理解し、正しく実装してください。それが不可能で、既存のコードベースで作業している場合は、まだアクセシビリティに対応していないコードのリファクタリングを慎重に提案してください。これは、問題が明らかになった時点ですぐに始める必要があるプロセスです。そのためには、ユーザーの意図とアプリケーションの制約を理解し、文書化する必要があります。

コードコメントと WCAG 参照

アクセシビリティのために実施した実装について説明するコードコメントを、十分に追加してください。コメントでは、WCAG 2.2 のいずれかの適合レベルに基づいて説明してください。関連する場合は、想定されるユーザーフローも説明してください。

セマンティック HTML と適切な構造を使用する

まず、すべてのコンテンツとコントロールにセマンティック HTMLを使用してください。ボタンには実際の<button>要素を、レイアウトには<header>／<nav>／<main>を、フォームには<form>と<label>を使用し、タイトルには論理的な見出しレベルの階層を使用してください。たとえば、<button>要素はキーボード操作に標準で対応しており（フォーカス可能で、キーボードから操作できます）、一方、<div>のようなセマンティックではない要素にはその機能がありません。<select>、<details>、<dialog>など、既存のネイティブ要素を使用する必要があります。カスタムコンポーネントを避けられない場合（通常は避けられません）は、確立された ARIA のデザインパターンとキーボード操作モデルに従ってください。ARIA は、代替手段がない場合にのみ使用してください。多くの場合、代替手段があります。ARIA を使用する場合は、その選択と理由を文書化してください。

ページを明確な構造とランドマークで構成してください。HTML5 のセクショニング要素を使用して、ナビゲーション、メインコンテンツ、フォームなどを区分し、コンテンツの構成をユーザーと開発者が明確に理解できるようにしてください。テキスト以外のメディアには、必ずテキストによる代替手段を用意してください。画像には内容を説明する代替テキストを含め、音声や動画には文字起こしまたはキャプションを用意してください。それらを確実に自分で作成できない場合は、別のメンテナーが対応する必要のある、ブロッキングタスクとして記録してください。同様に、データテーブルには見出しセル（<th>とscope属性）を使用し、表形式のデータの関係をスクリーンリーダーに明確に伝えてください。「こちら」「クリック」「続きを読む」のようなリンクテキストは避けてください。見た目の都合で必要な場合は、別の方法（操作可能なカードなど）でも同じ内容を伝え、アクセシビリティツリーからこれらのリンクテキストを除外してください。

アクセシブルなコンポーネントを設計する

各コンポーネントの HTML 構造は、その意味を反映する必要があります。メニューや複数の選択肢があるコントロールにはリストを、タイトルには見出しを、フォームフィールドのグループにはフィールドセットと凡例を使用するなどしてください。フォーカスインジケーター（要素にフォーカスが当たったときに表示されるアウトラインやハイライト）のスタイルを一貫させ、キーボードを使うユーザーが常にフォーカス位置を確認できるようにします。キーボードアクセシビリティは任意ではありません。キーボードだけで（Tab、Enter、スペース、矢印キーなどを適宜使用して）すべてのインタラクティブ要素に到達し、操作できるようにしてください。カスタムのフォーカス可能な要素に限り、負の値を指定して tabindex を追加したり、カスタムウィジェットのキーイベントをスクリプトで処理したりする必要がある場合があります。

タッチターゲットのサイズに関する WCAG のルールを忘れないでください。すべての要素に簡単にアクセスできる必要があります。ドラッグなどのマウス操作やジェスチャー操作には、代替手段が必要です。

アクセシビリティのリンターやライブラリを活用してください。アクセシブルな設計を重視するフレームワークやコンポーネントライブラリがあります。React、Vue、Angular を使用する場合は、それぞれのアクセシビリティツール（React の eslint-plugin-JSX-a11y など）を活用し、コミュニティで検証されたアクセシブルなコンポーネントを優先してください。最終的にアクセシブルなコンポーネントは、正しい HTML 構造、必要に応じた適切な ARIA ロールや状態、支援技術を利用するユーザーの使いやすさに関する慣習に従ったスクリプトを組み合わせて実現します。ドキュメントには、各カスタムコンポーネントがアクセシビリティにどう対応するか（画像コンポーネントに代替テキストを指定する方法や、カルーセルがフォーカスやスクリーンリーダーへの通知をどのように扱うかなど）を記載し、コンポーネントを拡張する人が遵守すべき要件を把握できるようにしてください。

継続的なメンテナンスとアンチパターンの回避

アクセシビリティの実現は一度きりの作業ではなく、プロジェクトの進化に合わせて継続的に評価する必要があります。アクセシビリティを長期にわたって最大限維持するには、コンテンツや機能を追加するたびにアクセシビリティを確認することを、継続的な要件として扱ってください。今後の変更に備えて、文書化し、徹底すべき主な実践項目を以下に示します。

• 新しいメディアには代替テキストを用意する： 画像やその他のメディアを追加するたびに、代替テキスト（または同等のテキストによる代替手段）を必ず用意してください。プルリクエストやコンテンツ公開ワークフローのチェック項目に含めることができます。開発者やコンテンツ作成者に alt 属性を必ず記述させる（または適切な場合は alt="" として画像を装飾目的と明示する）ことで、ユーザーが提供したコンテンツであっても、非視覚ユーザーへの配慮なしに画像が追加されることを防げます。アイコンには必ず対応するラベルを付け、視覚的にのみ使用するコンテンツには aria-hidden="true" を使用してください。代替テキストは短く簡潔にしますが、文字数の上限はありません。

• 新しい UI やスタイル変更の際に色のコントラストを確認する： 新しい色（テキスト、背景、アイコン、ボタンなど）を導入したり、デザインスタイルを変更したりする際は、色のコントラストが WCAG のガイドラインを満たしているか確認してください。WCAG 2.x によると、コントラスト比 は (L1 + 0.05) / (L2 + 0.05) として計算されます（L1 は明るい色の輝度、L2 は暗い色の輝度です）。この式によって、1:1（コントラストなし。例：白地に白）から 21:1（最も高いコントラスト。例：白地に黒）までの比率が得られます。標準サイズのテキストは背景とのコントラスト比を少なくとも 4.5:1 にする必要があり、大きなテキスト（約 18pt 超、または太字で約 14pt 超）では少なくとも 3:1 が必要です。新しい色の組み合わせには、この式またはオンラインのコントラストチェッカーを使って比率を計算し、基準を満たすように色やフォントサイズを調整してください。これはホバー、フォーカス、無効状態などにも当てはまります。

• 見出し構造とランドマークを維持する： 新しいコンテンツやページを追加する際は、見出し階層（<h1>…<h6>）が論理的であり（任意にレベルを飛ばさない）、適切な場合にセクション要素が使われていることを確認してください。たとえば、ページに新しいセクションを追加する場合、適切なレベルの見出しが必要になり、<section> で囲む、またはナビゲーションのランドマーク（<nav>, <main>, <aside> など）に追加する必要があるかもしれません。

• 変更のたびに再評価する： アプリケーションの成長に合わせて、アクセシビリティを継続的に再テストすることが重要です。Pa11y などの自動テストを回帰テストスイートに組み込み、新しいビルドのたびに実行してください。

• アンチパターンを避ける： <div> をボタンとして使うこと、キーボード操作に対応しない onclick、outline: none、視覚的なラベルの代わりに aria-label を使うこと、外部リンクに role=button を指定することなどです。）

さらに検討が必要な TODO

• <html> には lang 属性が必要です（単語単体ではなく、外国語のテキストブロックにも必要です。プロジェクトが多言語対応の場合は、必要に応じて動的に変更してください）。
• <title> 要素は必須です。プロジェクト内のどこで追加されているかを確認し、コンテンツに応じて動的に変更してください。
• コンテンツ以外の各ブロック（例：ナビゲーションの直前）の前に、フォーカス時のみ表示されるスキップリンクを実装してください。また、カルーセルなど、無関係な可能性があるコンテンツが 5 個以上続く大きなグループの前にもスキップリンクを追加してください。「Skip 'thing'」のように名前を付けます。例：「Skip navigation」や「Skip sponsor links」です。構造が変更されても正しい状態を保つようにしてください。
• フォームでは、エラー（色だけで示すのではなく）、要件、コンポーネントの状態を明確に伝えてください。無効状態は一切使用しないでください。コントロールは非表示にするのが望ましいです。
• prefers-reduced-motion に対応し、その設定を尊重してください。
• ビューポートのサイズやズームレベルが変化しても、すべてのコンテンツが適切にリフローするようにしてください。
• 人によるテストが必要であり、ユーザーフローをデザイナーが継続的に評価する必要があることを、プロジェクトの組織内およびドキュメントで明確に伝えてください。
• UI 自体では、アクセシビリティについて決して言及しないでください。

デザイン上の考慮事項

カード、リスト、ナビゲーション、リンク、ボタンなどのパターンを、重複して使ったり、多用したりすることは避けてください。ゆとりのあるレイアウトとテキストが重要です。長いフォームは、小さなステップに分割できるように設計してください。サイトをインタラクティブな要素で雑然とさせず、適切に、明確で見分けやすいアイコンを使用してください。開発やエンジニアリングの要件を、UI 要素として表現してはいけません。

アクセシビリティ上の問題を招く可能性があるプロンプトの場合

ユーザーにその旨を伝え、依頼によって生じる可能性が高い問題を説明し、本当に実装を続けるか確認してください。このような問題を避ける方法を提案してください。また、確実に判断できない場合は、障害のある別の開発者が判断できるよう、機能の説明をまとめてください。

アクセシビリティに関する知識

このスキルは、アクセシブルな開発に必要なすべての知識を網羅しているわけではありません。確信が持てない場合は、その旨を必ず明記し、公式の W3C／WCAG／WAI-ARIA リソースのみを参照してください。