Codexにアクセシビリティ修正を任せる前に決めること

3行まとめ

Label

名前。

Keyboard

操作。

Focus

位置。

Contrast

読める。

アクセシビリティ修正は、指摘を分類してから小さく直します。

• Codexにアクセシビリティ修正を任せる時は、label、keyboard、focus、contrast、ARIAを分け、1つのPRで直す範囲を絞ります。
• axeやLighthouseの自動指摘は入口です。keyboard操作、focus移動、screen reader向けの名前は人間確認も必要です。
• ARIAを足す前に、まず標準HTML、既存component、操作仕様を見直します。ARIAの足しすぎは別の不具合になります。

アクセシビリティ修正は、Codexと相性がよい作業です。labelがない。buttonの名前が弱い。keyboardで閉じられない。focusが飛ぶ。contrastが足りない。こうした問題は、差分としては小さく見えます。

ただし、雑に任せると壊れます。自動検査の指摘を消すためだけにARIAを足す。buttonをdivのままroleでごまかす。focus trapを直したつもりでkeyboard操作を壊す。見た目のcontrastだけを上げてdesign tokenから外れる。こうした修正は、見た目の差分が小さいぶんレビューで見落としやすいです。

この記事では、Codexにアクセシビリティ修正を任せる前に、指摘の分け方、依頼packet、確認方法、PRレビュー観点を整理します。Figmaから実装する時のaccessibility確認は、公開済み記事のCodexでFigmaを実装に渡す前に決めることで扱いました。ここでは、既存UIのa11y修正PRに絞ります。

この記事でわかること

Issue

指摘。

Packet

依頼。

Check

検査。

Review

承認。

Codexに任せる前に、直す範囲と確認方法を分けます。

• WCAG、ARIA、自動検査、人間確認の役割
• label、keyboard、focus、contrast、ARIAの指摘分類
• Codexへ渡すアクセシビリティ修正packet
• keyboard操作を先に固定する理由
• accessible nameを確認する見方
• ARIAを足す前に標準HTMLを見直す考え方
• axe、Playwright aria snapshot、manual確認の分担
• PRレビューで見るdiff、evidence、not fixed

アクセシビリティ修正の目的は、自動検査を緑にすることではありません。利用者が操作でき、理解でき、迷わず戻れる状態にすることです。

前提知識

項目	内容	見方
WCAG		基準。
ARIA		意味。
axe		自動。
Manual		人手。

WCAG、ARIA、自動検査、人間確認は同じものではありません。

W3CのWCAG 2.2は、Web contentのaccessibilityを評価するためのsuccess criteriaを持つ標準です。WAI-ARIAは、roles、states、propertiesを使ってUIの意味や状態を支援技術へ伝える仕組みです。WAI-ARIA Authoring Practices Guideは、dialog、combobox、menuなどのpatternとkeyboard interactionを扱います。

axe-coreは、既存のtest環境に組み込みやすいaccessibility engineです。PlaywrightにはARIA snapshot testingがあり、accessibility treeをYAML representationとして扱えます。これらは強力ですが、人間の操作確認を完全に置き換えるものではありません。

WCAGとARIAを分ける

WCAGは、満たすべき基準です。ARIAは、必要な時に意味を補う技術です。

WCAGの問題を見つけたからといって、必ずARIAを足すとは限りません。buttonならbutton要素を使う。inputならlabelを結びつける。dialogならfocus管理と閉じ方を決める。標準HTMLで解ける問題は、まず標準HTMLで解きます。

自動検査で全部は分からない

自動検査は、抜け漏れを見つける入口として有効です。

一方で、keyboardだけで目的を達成できるか、screen readerで文脈が自然か、focusが戻る位置が妥当か、error messageが実務上分かりやすいかは、人間が見る必要があります。

Codexには、自動指摘の修正だけでなく、人間確認が必要な点を出させます。

指摘を5分類に分ける

項目	内容	見方
Label		名前。
Keyboard		操作。
Focus		移動。
Contrast		色。
ARIA		意味。

分類すると、ARIA追加で全部解決しようとする失敗を避けられます。

アクセシビリティ修正は、まず分類します。

分類せずに「a11yを直して」と依頼すると、Codexは広く触りすぎます。label、keyboard、focus、contrast、ARIAのどれを直すのかを分けます。

label

labelは、formやcontrolの名前です。

inputにlabelが結びついているか。buttonの目的が分かるか。icon-only buttonにaccessible nameがあるか。error messageがどのfieldに対応するか。ここを見ます。

label修正では、表示文言を変えるのか、screen reader向けのnameを補うのかを分けます。

keyboard

keyboardは、mouseなしで操作できるかです。

Tabで移動できるか。EnterやSpaceで実行できるか。Escapeで閉じられるか。modal内でfocusが迷子にならないか。操作後にfocusが戻るか。ここを確認します。

keyboard修正は、見た目の差分が出ないこともあります。だからこそ、PRに確認手順を残します。

focus

focusは、いまどこを操作しているかを示します。

focus indicatorが見えるか。dialogを開いた時に適切な場所へfocusが移るか。閉じた後に元のtriggerへ戻るか。validation error後にユーザーが次に何をすればよいか分かるか。ここを見ます。

focusを直す時は、tab orderを勝手に大きく変えないようにします。

contrast

contrastは、文字やUI部品が読めるかです。

contrast修正では、単に濃い色へ変えるだけでなく、design token、theme、disabled state、hover state、error stateを見ます。1箇所だけ直接色を変えると、別の画面で崩れることがあります。

ARIA

ARIAは、role、state、propertyを使って意味を補います。

ただし、ARIAは足せばよいものではありません。標準HTMLの意味を壊すこともあります。Codexには、ARIA追加の前に、標準要素で解けない理由を出させます。

Codexへ渡す修正packet

項目	内容	見方
Target		対象。
Evidence		根拠。
Allowed		許可。
Forbidden		禁止。

a11y修正では、変えてよい見た目と変えないUI挙動を明示します。

Codexへは、アクセシビリティ修正packetを渡します。

packetには、対象、根拠、許可する変更、禁止する変更、確認方法を入れます。

target

targetには、対象画面、component、stateを書きます。

例: 「検索modalのopen/close」「注文formの住所欄」「icon-onlyの削除button」「table rowのexpand操作」。

対象をcomponent単位へ絞ると、PRが小さくなります。

evidence

evidenceには、指摘の根拠を入れます。

axeの指摘、Lighthouseの項目、Playwright aria snapshot、keyboard確認の失敗、screen readerで読まれない名前、screenshot、該当fileなどです。

根拠が曖昧な指摘は、まず再現確認にします。

allowed change

allowed changeには、変えてよいものを書きます。

例: 「button要素へ置き換えてよい」「label文言は変えずにaria-labelを追加してよい」「focus管理hookを対象component内で修正してよい」「design token内の色へ差し替えてよい」。

forbidden change

forbidden changeには、変えてはいけないものを書きます。

例: 「layoutを大きく変えない」「keyboard shortcutを変えない」「既存component APIを広く変えない」「ARIAを追加するためだけにsemantic HTMLを壊さない」「snapshotを承認なしに更新しない」。

キーボード操作を先に固定する

1. 1Tab

   移動。

2. 2Enter

   実行。

3. 3Esc

   閉じる。

4. 4Return

   戻る。

keyboardで完了できるかを先に見ると、見た目だけの修正を避けられます。

アクセシビリティ修正では、keyboard操作を先に固定します。

見た目の修正だけだと、keyboardで使えるかが分かりません。

tab order

Tab orderは、自然な順番かを見ます。

画面の見た目に沿って移動するか。非表示要素へfocusしないか。modal内で背後のpageへ抜けないか。disabled要素が不自然にfocusされないか。ここを確認します。

activation

activationは、操作実行です。

buttonはEnterやSpaceで動くか。linkはEnterで動くか。custom controlは期待されるkeyで動くか。mouse clickだけで実装されていないかを見ます。

escape and close

dialog、dropdown、popover、toast、menuでは、閉じ方を決めます。

Escapeで閉じるか。外側clickで閉じるか。閉じた後のfocusはどこへ戻るか。閉じない場合は、その理由を仕様として残します。

labelとnameを確認する

Input

label。

Button

目的。

Icon

名前。

Status

通知。

screen reader向けの名前は、見た目の文言とは別に確認します。

screen reader向けの名前は、見た目の文言とは別に確認します。

見た目にはiconだけでも、支援技術には目的が伝わる必要があります。

form

formでは、inputとlabelの関係を見ます。

placeholderだけに頼らない。error messageがfieldと結びついている。requiredの意味が伝わる。helper textが必要なら関連付いている。これを確認します。

button

buttonでは、目的が分かる名前にします。

「開く」「削除」「保存」だけで足りる場合もありますが、同じbuttonが複数あるなら「行を削除」「添付ファイルを削除」のように文脈を足します。

icon only

icon-only buttonは、accessible nameを必ず確認します。

見た目のtooltipだけでは足りないことがあります。aria-label、visually hidden text、既存componentのlabel propなど、projectの方針に合わせます。

ARIAを足す前にHTMLを見直す

項目	内容	見方
Native		標準。
Role		役割。
State		状態。
Pattern		型。

ARIAは便利ですが、標準HTMLで足りるならそちらを優先します。

ARIAを足す前に、標準HTMLで解けないかを見ます。

Codexには、「ARIAを足す前にnative elementで解けるか確認して」と明示します。

native element

button、input、select、label、fieldset、legend、details、summaryなど、標準要素には既に意味とkeyboard behaviorがあります。

divにroleとkeydownを足すより、buttonへ戻すほうが安全なことが多いです。

role

roleは、要素の役割を伝えます。

ただし、roleを付けても動作は自動で付くとは限りません。role="button" を付けたdivは、buttonのkeyboard動作を自動では持ちません。だから、まずnative elementを優先します。

state

stateは、開閉、選択、無効、現在位置などを伝えます。

aria-expanded、aria-selected、aria-current、aria-invalid などは便利ですが、実際の状態と同期していないと逆に混乱します。

ARIAを足しすぎない

ARIAは、足しすぎると読みにくくなります。

不要なrole、重複したlabel、実態と違うstate、見た目だけのためのARIAは避けます。Codexの修正では、ARIAを足した理由をPR本文へ書かせます。

自動検査と人間確認を分ける

項目	内容	見方
axe		自動。
Snapshot		構造。
Keyboard		手動。
Reader		確認。

自動検査は入口であり、keyboardや読み上げ確認の代替ではありません。

自動検査と人間確認は役割が違います。

どちらか一方ではなく、修正内容に応じて組み合わせます。

axe

axe-coreは、よくあるaccessibility問題を自動で検出する入口として使えます。

CIやPlaywright testに組み込めば、regressionを拾いやすくなります。ただし、自動で拾えない問題もあります。axeが通っても、keyboard操作や読み上げ文脈が良いとは限りません。

Playwright aria snapshot

PlaywrightのARIA snapshotは、accessibility treeをsnapshotとして確認できます。

button名、heading構造、landmark、dialog内の構造など、変化を見たい時に使えます。ただし、snapshot更新はreview対象です。意図しないname変更を見逃さないようにします。

manual screen reader check

screen reader確認は、人間が行う確認です。

すべてのPRで重い確認をする必要はありませんが、dialog、form、custom widget、navigation、error handlingを直す時は、manual確認の有無を明記します。

PRレビューで見るもの

項目	内容	見方
Diff		差分。
Evidence		証拠。
Scope		範囲。
Not fixed		保留。

a11y修正PRでは、何を直し、何を見送ったかを明記します。

アクセシビリティ修正PRでは、diffだけでなく証拠を見ます。

何を直したか、どう確認したか、何を見送ったかをPR本文に入れます。

diff

diffでは、semantic HTML、ARIA、CSS、focus management、event handler、testを見ます。

見た目だけの変更に見えても、keyboardやscreen readerへの影響がある場合があります。

evidence

evidenceには、検査結果を入れます。

axe結果、keyboard操作メモ、aria snapshot差分、screenshot、manual確認、該当WCAG観点、未確認理由などです。

not fixed

not fixedも重要です。

今回のPRで直さない指摘、別componentの問題、design token側の課題、manual確認が必要なものを残します。全部を1PRで直そうとすると、reviewが重くなります。

よくある失敗

ARIA all

足しすぎ。

No key

keyboardなし。

Color only

色だけ。

No proof

証拠なし。

自動指摘を消すことと、使えるUIになることは別です。

よくある失敗は、自動指摘を消すことを目的にすることです。

1つ目は、ARIAを足しすぎることです。標準HTMLで解けるなら、ARIAではなくHTMLを直します。

2つ目は、keyboard確認をしないことです。mouseで動くUIがkeyboardでも使えるとは限りません。

3つ目は、contrastだけを局所的に直すことです。design tokenから外れると、別状態で読みづらくなることがあります。

4つ目は、証拠なしでPRを出すことです。a11y修正は、どう確認したかがないとreviewしづらくなります。

FAQ

項目	内容	見方
全部直す?		分割。
ARIA?		慎重。
axe?		入口。
誰が見る?		人間。

迷ったら、keyboardだけで目的を達成できるかへ戻ります。

axeで出た指摘は全部直すべきですか

まず分類します。

同じ原因で複数出ている指摘もあります。影響が大きいもの、component共通で直せるもの、ユーザー操作を妨げるものから扱います。

ARIAを付ければ解決しますか

解決する場合もありますが、最初の選択肢ではありません。

標準HTMLで解けるなら標準HTMLを使います。ARIAを使う場合は、role、state、keyboard behaviorが揃っているかを確認します。

Codexにscreen reader確認まで任せられますか

一部の構造確認やaria snapshot確認は任せられます。

ただし、実際の読み上げ体験や操作感は、人間確認を残します。Codexには、manual確認が必要な箇所を出させます。

1PRでどこまで直せばいいですか

1つのcomponent、1つのflow、1つの指摘分類に絞るのが扱いやすいです。

label修正、keyboard修正、contrast修正を同時に広く触ると、reviewが難しくなります。共通componentを直す場合は、影響範囲と確認画面を明記します。

参照した主な情報源

• Web Content Accessibility Guidelines (WCAG) 2.2 | W3C
• ARIA Authoring Practices Guide | W3C WAI
• WAI-ARIA Overview | W3C WAI
• ARIA snapshots | Playwright
• axe-core | GitHub

次に読むなら

更新履歴

1. 2026.05.31

   初版。

アクセシビリティ基準やツールは、導入時に公式docsで見直します。

• 2026.05.31 初版公開。