アクセシビリティ（a11y）検査をCIに入れると、緑のチェックマークで安心したくなります。ですが自動検査で見つかるのは、問題全体の一部だけだとされています。この記事では、実装とテストの工程で「何を機械に任せ、何を人が見るか」の線引きを整理します。

自動検査は3層に分けて考える

検査には、見つけられる問題の種類が異なる3つの層があります。

静的検査（書いた時点）：ESLintの eslint-plugin-jsx-a11y など。ソースコードを読むだけなので、画面を起動せずに動きます。
実行時検査（画面を描画した後）：@axe-core/playwright など。実際のDOMを調べるので、色のコントラストや重複したIDも拾えます。
手動確認（人が操作する）：キーボード操作やスクリーンリーダーの読み上げなど、機械が判断できない部分です。

自動で拾えるもの・拾えないもの

自動で拾える例

画像の alt 属性がない
フォーム部品にラベルが結び付いていない
文字と背景のコントラスト比が基準未満
aria-* 属性の綴りや値の誤り
ボタンやリンクに名前がない

自動では拾えない例

alt の文言が内容に合っているか（「image1」でも機械は通してしまいます）
Tabキーで移る順番が、画面の読み順と合っているか
モーダルを閉じたとき、フォーカスが元の場所に戻るか
エラーが出たことを、読み上げで知らせているか
マウスでしか開けない操作が隠れていないか

つまり「属性があるか」は機械が見られますが、「使えるか」は人が確かめる必要があります。

手動確認の最小セット（5分でできる）

画面を変えたら、次の4つだけは必ず人が確かめます。

マウスを置いて、Tabキーだけで操作する。すべての入力欄・ボタンに届くか、現在地の枠線が見えるかを確認します。
モーダルやメニューを開閉する。Escで閉じられるか、閉じた後にフォーカスが開いたボタンへ戻るかを見ます。
ブラウザを200%に拡大する。文字が切れたり、横スクロールが必要になったりしないかを見ます。
スクリーンリーダーで1画面だけ読ませる。macOSならVoiceOver（Command+F5）で、ボタンの名前とエラー通知が聞こえるかを確かめます。

CIへの組み込み例

実行時検査は、主要画面ごとに次のような短いテストを置くところから始められます。

import AxeBuilder from '@axe-core/playwright';

test('お問い合わせ画面にa11y違反がない', async ({ page }) => {
  await page.goto('/ja/contact');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

最初から全画面に広げず、「新しく作った画面は必ず通す」という運用にすると、既存の違反に足を取られずに続けられます。

よくある失敗

緑だから大丈夫と判断する：手動確認の4項目が抜け落ちます。PRのチェック欄に手動確認の項目を足しておきましょう。
違反を一括で無視設定にする：後から誰も見なくなります。無視するなら理由と期限をコメントに残します。
報告が開発者に届かない：利用者や社内のテスターが気づいても、「読み上げがおかしい」だけでは再現できません。

Bugoon での実践

手動確認で見つけた問題は、その場で報告できないと記憶から消えます。Bugoon のウィジェットをサイトに埋め込めば、テスターは気づいた画面でスクリーンショットに印を付けて報告できます。操作ステップも記録されるので、「どのキーを押したらフォーカスが消えたか」を再現の手がかりとして残せます。報告はGitHub Issueに連携され、カンバンボードで状況を追えます。

将来的に、コントラスト比やフォーカスの状態も報告と一緒に取れるようになると、非エンジニアでもa11yの問題を伝えやすくなります。

a11y自動検査で拾える範囲と手動確認の最小セット