accessibility

アクセシビリティ

アクセシブルなウェブアプリケーションを構築するための包括的なパターンです。WCAG 2.2 AA への準拠、キーボードフォーカス管理、React Aria のコンポーネントパターン、ネイティブ HTML を優先する考え方、認知面でのインクルージョン、ユーザー設定の尊重を扱います。各カテゴリのルールファイルは rules/ にあり、必要に応じて読み込まれます。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
WCAG 準拠	3	CRITICAL	色のコントラスト、セマンティック HTML、自動テスト
POUR 終了基準	1	CRITICAL	WCAG 2.2 AA の各基準に対する、反証可能な合否しきい値
静的解析で検出できるアンチパターン	1	HIGH	ブラウザーなしで検出可能な、grep で検索できるパターン
フォーカス管理	1	HIGH	キーボードナビゲーション。フォーカストラップと復元の仕組みは上流にあります
React Aria	2	HIGH	アクセシブルなコンポーネントとフォームフック。オーバーレイ API は上流にあります
最新のウェブアクセシビリティ	2	CRITICAL/HIGH	ネイティブ HTML の優先、ユーザー設定の尊重。認知面の上限は references/ork-delta.md にあります

全 6 カテゴリにわたるルール数：10

クイックスタート

// Semantic HTML with ARIA
<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
    </section>
  </article>
</main>

// Focus trap with React Aria
import { FocusScope } from 'react-aria';

<FocusScope contain restoreFocus autoFocus>
  <div role="dialog" aria-modal="true">
    {children}
  </div>
</FocusScope>

WCAG 準拠

インクルーシブで、法令に準拠したウェブアプリケーションのための WCAG 2.2 AA 実装です。

ルール	ファイル	主なパターン
色のコントラスト	rules/wcag-color-contrast.md	テキストは 4.5:1、UI コンポーネントは 3:1、フォーカスインジケーター
セマンティック HTML	rules/wcag-semantic-html.md	ランドマーク、見出し、ARIA ラベル、フォーム構造
テスト	rules/wcag-testing.md	axe-core、Playwright a11y、スクリーンリーダーのテスト

POUR 終了基準

WCAG 2.2 AA の各基準に対する具体的な合否しきい値です。「要件を満たしている」といった曖昧な確認に代わります。

ルール	ファイル	主なパターン
POUR 終了基準	rules/pour-exit-criteria.md	反証可能なチェックリスト：画像の代替テキスト、コントラスト比、フォーカスインジケーター、タッチターゲット、ARIA の状態

静的解析で検出できるアンチパターン

静的解析やコードレビューで検出できる、grep で検索可能なアンチパターンです。ブラウザーは不要です。

ルール	ファイル	主なパターン
アクセシビリティのアンチパターン（静的）	rules/a11y-antipatterns-static.md	フォーカスの除去、ラベルの欠落、自動再生、アイコンのみのボタン、div のクリックハンドラー

フォーカス管理

アクセシブルなインタラクティブウィジェットのための、キーボードフォーカス管理パターンです。

ルール	ファイル	主なパターン
キーボードナビゲーション	rules/focus-keyboard-nav.md	ロービング tabindex、スキップリンク、矢印キー

フォーカストラップと復元の仕組みは上流の担当です。React Aria の <FocusScope contain restoreFocus autoFocus> を使用してください（上流の対応範囲を参照）。React Aria を利用できない場合は、scripts/focus-trap-template.tsx をコピーしてください。どちらの場合のルールも references/ork-delta.md にあります。

React Aria

WCAG に準拠したインタラクティブ UI を構築するための、Adobe React Aria フックです。

ルール	ファイル	主なパターン
コンポーネント	rules/aria-components.md	useButton、useDialog、useMenu、FocusScope
フォーム	rules/aria-forms.md	useComboBox、useTextField、useListBox

オーバーレイのフック API（useModalOverlay、useTooltip、usePopover）は上流に記載されています（上流の対応範囲を参照）。このプロジェクト独自のオーバーレイレシピ（FocusScope と共有モーションプリセットの組み合わせ）は references/ork-delta.md にあります。

モダンなウェブアクセシビリティ

2026年のベストプラクティス：ネイティブ HTML を最優先し、認知面でのインクルージョンを実現し、ユーザーの設定を尊重します。

ルール	ファイル	主なパターン
ネイティブ HTML を最優先	rules/wcag-native-html-first.md	<dialog>、<details>、カスタム ARIA よりネイティブ HTML を優先
ユーザー設定	rules/wcag-user-preferences.md	prefers-reduced-motion、forced-colors、prefers-contrast、ズーム

認知面でのインクルージョン（ADHD／自閉症／ディスレクシアへの対応）は、上流の W3C COGA で扱われています（上流でのカバー範囲を参照）。プロジェクト固有の認知負荷の上限（通知数、ナビゲーション項目数、読解レベルの目標）は references/ork-delta.md に記載されています。

主な決定事項

決定事項	推奨
適合レベル	WCAG 2.2 AA（法的基準：ADA、Section 508）
コントラスト比	通常のテキストは 4.5:1、大きなテキストと UI コンポーネントは 3:1
ターゲットサイズ	最小 24px（WCAG 2.5.8）、タッチ操作では 44px
フォーカスインジケーター	3px の実線アウトライン、コントラスト比 3:1
コンポーネントライブラリ	操作の制御には React Aria hooks、迅速な実装には react-aria-components
状態管理	react-stately hooks（アクセシビリティを考慮して設計）
フォーカス管理	モーダルには FocusScope、ウィジェットには roving tabindex
テスト	jest-axe（ユニット）＋ Playwright axe-core（E2E）

アンチパターン（禁止）

• Div の多用：セマンティック要素（<nav>、<main>、<article>）の代わりに <div> を使用する
• 色だけによる情報表現：アイコンやテキストを伴わず、色だけで状態を示す
• ラベルの欠落：対応する <label> または aria-label のないフォーム入力
• キーボードトラップ：Escape キーを使わないとフォーカスから抜け出せない状態
• フォーカスアウトラインの削除：代替のインジケーターなしで outline: none を指定する
• 正の tabindex：tabindex > 0 を使用する（自然な順序を乱します）
• onClick を持つ div：<button> または useButton の代わりに <div onClick> を使用する
• モーダル内での手動フォーカス：FocusScope の代わりに useEffect ＋ ref.focus() を使用する
• メディアの自動再生：ユーザーの操作なしに再生される音声／動画
• ARIA の過剰使用：セマンティック HTML で十分な場合に ARIA を使用する

上流でのカバー範囲（内容を重複して記載しない）

2026-07-31 の wrap-plus-delta による削減では、ベンダーのチュートリアル、API リファレンス、達成基準の解説を削除しました。一次情報を参照してください。references/ork-delta.md に記載されているのは、プロジェクト固有の最低基準、過去の問題、独自の決定事項のみです。

トピック	一次情報
WCAG 2.2 の達成基準の解説と監査チェックリスト	WCAG 2.2 クイックリファレンス および WCAG 2.2 仕様
ARIA ウィジェットのパターンとキーボード操作モデル	WAI-ARIA オーサリング・プラクティス・ガイド
React Aria のフック API（useButton、useMenu、useComboBox、useModalOverlay、useTooltip、usePopover）、コンポーネントのチェックリスト、実例	React Aria ドキュメント
フォーカストラップ、フォーカス復元、roving tabindex、スキップリンクのアルゴリズム	React Aria FocusScope および APG のパターン
認知アクセシビリティのガイダンス（COGA）	W3C Making Content Usable
スクリーンリーダーのテスト手順（NVDA、JAWS、VoiceOver、TalkBack）	WebAIM のスクリーンリーダーテスト

詳細ドキュメント

リソース	説明
scripts/	テンプレート：アクセシブルなフォーム、フォーカストラップ、React Aria コンポーネント
references/ork-delta.md	Ork 固有の最低基準、過去の問題、独自の決定事項（認知負荷の上限、オーバーレイの実装例、標準のフォーカストラップセレクター）
references/ux-thresholds-quick.md	UI/UX のしきい値クイックリファレンス：コントラスト、タッチターゲット、認知負荷、タイポグラフィ、フォーム
examples/wcag-examples.md	アクセシブルなフォーム、モーダル、ナビゲーションの完全な例

関連スキル

• ork:testing-e2e - アクセシビリティテストを含むE2Eテストのパターン
• design-system-starter - アクセシブルなコンポーネントライブラリのパターン
• ork:i18n-date-patterns - RTLレイアウトとロケールに応じたフォーマット
• motion-animation-patterns - モーションの低減とアニメーションのアクセシビリティ