Web Accessibility

Web Accessibility

Product 実装や UI レビューで、a11y を後付けの監査ではなく設計・実装フローの中へ入れるための skill。

When to Use

• Web UI を新規実装するとき
• 既存 UI の keyboard / focus / form / ARIA / contrast 問題を直すとき
• Dialog、navigation、table、toast、validation などの振る舞いを見直すとき
• React / Next.js、Angular、Vue の framework 癖込みで review したいとき
• 「merge 前に a11y の観点で見てほしい」という依頼を受けたとき

Not the Best Fit

• Web UI ではない extension host / CLI 中心の変更
• 既にブラウザ上で再現済みで、runtime の証跡収集と検証を主目的にするケース
• その場合は Accessibility Runtime Tester のような runtime 検証 agent を優先する
• Markdown 文書だけのアクセシビリティ改善

Operating Principles

• Native HTML first. div role="button" より <button> を優先する
• Severity first. CRITICAL を潰してから IMPORTANT、最後に SUGGESTION を見る
• Keyboard first. マウスでしか確認していない UI は未完了とみなす
• Name / role / state を明確にする。見た目だけで意味が伝わっても不十分
• Review と fix を往復しやすいよう、指摘は component 単位・flow 単位で束ねる

Workflow

1. Scope the surface 対象の page / flow / component、主要タスク、入力手段、利用者制約を確認する。 2. Hit the blocking issues first semantics、keyboard、focus、label、error identification、accessible name を優先する。 3. Check the UI pattern form、dialog、navigation、table、media、notification などの pattern ごとに要件を確認する。 4. Apply framework-safe fixes React / Next.js、Angular、Vue で壊れやすい箇所を framework の流儀で直す。 5. Re-check responsive and visual access contrast、320px reflow、reduced motion、color-only signaling を見直す。 6. Close with a verification note 直した点、未確認の runtime リスク、残件を短く残す。

Decision Points

• Native element で解けるなら ARIA を増やさない
• Browser 上の focus trap、route announce、hover/focus popup を確証付きで見たいなら runtime 検証へ切り替える
• Quick review 依頼なら review checklist を先に回す
• 実装中なら common UI failures から直しやすい欠陥を先に潰す

Escalation Paths

• 深い設計レビューや WCAG 観点の広い棚卸しが必要なら Accessibility Expert を使う
• Browser 上の keyboard flow、dialog、focus return、live region を証跡付きで確認したいなら Accessibility Runtime Tester を使う
• Markdown 文書の読みやすさや GitHub 上の文書 a11y が主題なら markdown-accessibility を使う

Expected Output

• 主要な blocking issue を severity 順に並べる
• 修正する場合は component / flow 単位でまとめて直す
• 未検証の runtime 挙動は「推測で完了」にせず明示する
• Browser 実機確認が必要な場合は、可能な static guard や checklist も添える

Reference Map

• Priority and legal baseline: references/wcag-priority-map.md
• Common defects and fixes: references/common-ui-failures.md
• Framework notes: references/framework-patterns.md
• Final pass checklist: references/review-checklist.md

Done Criteria

• [ ] Keyboard だけで主要フローを操作できる
• [ ] Focus が見え、閉じた dialog や overlay から適切に戻る
• [ ] Interactive element に accessible name / role / state がある
• [ ] Form の label、required、error、status message が関連付いている
• [ ] Contrast、reflow、color-only signaling、motion の見落としがない
• [ ] Framework 固有の a11y regressions を確認した
• [ ] 未検証の runtime 挙動があれば明示した

Common UI Failures

実装で頻出する欠陥を、直し方の方向まで含めて短くまとめる。

Structure and Semantics

• div soup で landmark がない
• header nav main footer を使う
• Heading level が飛ぶ
• 見た目ではなく文書構造で選ぶ
• Link text が click here や more
• 行き先や動作が text だけで分かるようにする
• Layout table と data table が混ざる
• Layout は CSS、data table には caption と th を付ける

Keyboard and Focus

• div や span に click だけある
• <button> へ戻す。戻せないなら role、tabIndex、Enter / Space を実装する
• outline: none で focus ring が消えている
• :focus-visible を作る
• Custom dialog に Escape、Tab trap、focus return がない
• Native dialog か、等価の keyboard/focus 管理を入れる
• Hover-only UI
• focus / blur でも同じ内容へ到達できるようにする

Forms and Validation

• Placeholder を label 代わりにしている
• Visible label を置く
• Error message が input と結び付いていない
• aria-describedby と aria-invalid を使う
• Required が色や * だけ
• required と説明文を加える
• Submit 後に最初の error へ focus しない
• error summary か first invalid field へ誘導する

Dynamic Content

• Toast や save message が screen reader に届かない
• role="status" または role="alert"
• Icon-only button に name がない
• aria-label を付ける
• Hidden 状態と focusable 状態が矛盾する
• aria-hidden、hidden、inert、focusability の整合を取る

Visual Access

• Text contrast 不足
• Normal text は 4.5:1、large text は 3:1 を下回らない
• Color だけで error / success を伝える
• icon、text、border などを重ねる
• Narrow viewport で横スクロール前提になる
• 320px 幅で reflow する layout に戻す
• 強い motion を常時出す
• prefers-reduced-motion を考慮する

Media

• Informational image に alt がない
• 意味を伝える alt か、装飾なら空 alt にする
• Video に captions がない
• track kind="captions" を付ける
• Audio / video autoplay
• 原則避ける。必要でも mute と control を前提にする

Framework Patterns

React / Next.js

• JSX の label は for ではなく htmlFor
• Route change 後は page title と main heading の整合を保つ
• Re-render で focus が飛ぶなら DOM identity を安定させる
• Rich text を注入するなら heading、alt、ARIA を含めて sanitize する
• Icon-only button、dialog close、toast announce は component 化して再利用する

Angular

• (click) を div に置くより button を使う
• Modal は Angular CDK Dialog / cdkTrapFocus を優先する
• Router 遷移時の announce は LiveAnnouncer を使う
• Template-driven form でも aria-invalid と aria-describedby を忘れない

Vue

• @click を non-interactive element に置くなら role、tabindex、keyboard handling まで実装する
• v-if で開く panel / dialog は nextTick 後の focus 移動を入れる
• v-html は sanitize と structure validation を前提にする

Cross-framework Guardrails

• Native component に寄せられるところは headless custom control を増やしすぎない
• Design system component を直すときは a11y fix を利用側ではなく component 側へ寄せる
• Browser runtime でしか確証が持てない挙動は、実装レビューだけで完了扱いにしない

Review Checklist

Perceivable

• [ ] 画像に適切な alt がある
• [ ] Decorative image は空 alt か aria-hidden で処理されている
• [ ] Headings と landmarks が論理的
• [ ] Text contrast が十分
• [ ] Color だけで状態や意味を伝えていない
• [ ] 320px 幅でも主要 UI が崩れない
• [ ] Media には captions や control がある

Operable

• [ ] Keyboard だけで主要操作が完了できる
• [ ] Focus indicator が見える
• [ ] No keyboard trap
• [ ] Dialog / menu / popover に Escape と focus return がある
• [ ] Hover-only interaction になっていない
• [ ] Skip link が必要な画面にある

Understandable

• [ ] Form field に label がある
• [ ] Required と error が text でも伝わる
• [ ] Error が input と関連付いている
• [ ] Unexpected context change を起こさない
• [ ] SPA route change の title / announce / focus が整理されている

Robust

• [ ] Interactive element に name / role / state がある
• [ ] Invalid / redundant ARIA がない
• [ ] Dynamic status が live region で伝わる
• [ ] Focusable element と hidden state が矛盾していない

Close-out Note

• [ ] 直した点を component / flow 単位で要約した
• [ ] Runtime 未確認の点を明記した
• [ ] 追加テストが必要なら残件として分離した

WCAG Priority Map

Web product 実装でまず見るべき順番を、WCAG 2.2 AA ベースで圧縮した地図。

Baseline

• Target: WCAG 2.2 AA
• Legal shorthand:
• EAA: EU 向け digital product なら無視しにくい前提
• ADA Title II: 公共系では 2026 以降さらに重い
• Section 508: 米国 federal 調達文脈では継続して意識が必要

Priority Order

P0: Blocking issues

• lang がない、heading / landmark が壊れている
• Keyboard で操作できない
• Focus trap から出られない、focus が見えない
• Label がない、error が text で伝わらない
• Button / link / custom control に accessible name がない
• Table header がない
• Alt text や captions が欠けている
• Text contrast が不足している

P1: Significant barriers

• Skip link がない
• Dialog close 後に focus が戻らない
• Hover / focus で出る content が dismissible でない
• Color だけで状態を伝えている
• 320px で reflow しない
• Dynamic status が screen reader に伝わらない
• Route change が SPA で告知されない

P2: Quality improvements

• prefers-reduced-motion への追従
• target size と spacing の改善
• redundant ARIA の削減
• heading の細かな階層改善

Native Before ARIA

1. Native element で解けるならそれを使う 2. Native semantics を ARIA で上書きしない 3. ARIA control を置くなら keyboard support まで実装する 4. Focusable element に aria-hidden="true" を付けない 5. Interactive element の accessible name を欠かさない

Quick Triage by Request

• "操作できない": keyboard / focus / trap を最優先
• "フォームが使いづらい": label / required / error / describedby を最優先
• "見た目は平気だが不安": contrast / landmarks / headings / names を先に見る
• "SPA 遷移で違和感": title / live region / focus management を見る