Claude Code アクセシビリティ対応｜WCAG準拠コード生成ガイド

私がこれまで複数の企業でフロントエンド開発チームと伴走してきた経験の中で、アクセシビリティ対応は「後回しにされがちだが、実装段階で組み込まないと手戻りが大きい」領域の筆頭です。特に、WCAG 2.1 や 2.2 の要件を満たすコードを最初から生成できれば、QA工程での指摘や修正コストを大幅に削減できます。Claude Code は、適切なプロンプト設計と検証フローを組み合わせることで、アクセシビリティ要件を開発プロセスの初期から組み込む実務的な手段となります。本記事では、WCAG 基準別の具体的なプロンプト例、axe-core などの検証ツール連携パターン、そして修正優先度の判断基準を、実装レベルで解説します。

アクセシビリティ対応を Claude Code で扱う意義

アクセシビリティは「あとから対応」すると、DOM 構造の再設計やイベントハンドラの書き直しが発生し、工数が膨らみます。Claude Code を使う利点は、コード生成時点で ARIA 属性・セマンティック HTML・キーボード操作への対応を織り込める点です。

従来の開発フローでは、デザイナーがモックアップを作成し、開発者が実装した後、QA 段階で axe DevTools や Lighthouse のスコアを見て「ラベルが不足している」「コントラスト比が 4.5:1 を下回る」といった指摘を受け、コードを修正するケースが一般的でした。Claude Code を導入すると、プロンプトに WCAG レベル A・AA の要件を記述しておくことで、初回生成時からセマンティックなマークアップと適切な ARIA 属性を含むコードが得られ、修正サイクルが短縮されます。

ただし、Claude Code が生成するコードも完璧ではありません。特に動的なインタラクション（モーダル・ドロワー・タブ切り替え等）では、フォーカス管理やライブリージョンの設定が不足する場合があるため、生成後の検証が不可欠です。既存の Claude Code アクセシビリティ対応記事では概論を扱っていますが、本記事では WCAG 基準ごとの具体的なプロンプト例と、検証ツール連携の実装パターンに焦点を当てます。

WCAG 基準別のプロンプト設計

WCAG 2.1 の達成基準は、レベル A・AA・AAA に分かれ、それぞれ知覚可能性・操作可能性・理解可能性・堅牢性の4原則に沿って構成されています。Claude Code へのプロンプトでは、関連する達成基準の番号と要件を明示すると、生成コードの精度が上がります。

1.4.3 コントラスト（最低限）への対応

WCAG 2.1 の達成基準 1.4.3（レベル AA）では、通常のテキストで 4.5:1、大きなテキスト（18pt 以上または 14pt 太字以上）で 3:1 のコントラスト比を求めます。Claude Code にカラーパレットとともに要件を渡すプロンプト例は以下の通りです。

以下のボタンコンポーネントを React + Tailwind CSS で生成してください。

要件:
- primary ボタンは背景色 #3B82F6、テキスト色 #FFFFFF
- secondary ボタンは背景色 #E5E7EB、テキスト色 #1F2937
- WCAG 2.1 達成基準 1.4.3（コントラスト最低限）を満たすこと（4.5:1 以上）
- コントラスト比が不足する組み合わせがあれば、代替色を提案してください

このプロンプトで生成されたコードには、text-white と bg-blue-500 の組み合わせが含まれます。実際のコントラスト比は 4.6:1 程度で基準を満たしますが、secondary ボタンの #1F2937（gray-800 相当）と #E5E7EB（gray-200 相当）の組み合わせは約 8:1 となり、十分なコントラストが確保されます。

生成後、WebAIM Contrast Checker や Lighthouse の監査結果で確認し、不足があれば「コントラスト比を 7:1 に引き上げてください（WCAG AAA 基準）」と追加指示を出すことで、再生成が可能です。

2.1.1 キーボード操作への対応

達成基準 2.1.1（レベル A）では、すべての機能をキーボードで操作できることが求められます。カスタムコンポーネント（ドロップダウン・タブパネル等）では、tabindex・role・aria-* 属性の適切な設定が必要です。

以下のタブ切り替えコンポーネントを生成してください。

要件:
- タブは `role="tablist"`、各タブボタンは `role="tab"` とする
- 選択中のタブには `aria-selected="true"` を設定
- 矢印キー（ArrowLeft / ArrowRight）でタブ間を移動できるようにする
- Tab キーでフォーカスが次の要素に移動する動作を保つ
- WCAG 2.1 達成基準 2.1.1（キーボード操作）を満たすこと

Claude Code が生成するコードには、onKeyDown ハンドラで ArrowLeft・ArrowRight の処理が含まれ、tabindex="0"（選択中）と tabindex="-1"（非選択）の切り替えロジックが組み込まれます。ただし、Home / End キーでの先頭・末尾タブへのジャンプは追加指示が必要な場合があるため、生成後に「Home キーで最初のタブ、End キーで最後のタブに移動する処理を追加してください」と補足すると良いでしょう。

4.1.2 名前・役割・値への対応

達成基準 4.1.2（レベル A）では、すべての UI コンポーネントに名前（aria-label や aria-labelledby）、役割（role）、状態（aria-expanded 等）が適切に設定されていることが求められます。

以下のアコーディオンコンポーネントを生成してください。

要件:
- 各セクションのボタンには `aria-expanded` を設定し、開閉状態を反映
- 展開可能な領域には `role="region"` と `aria-labelledby` を設定
- ボタンには視覚的な見出しテキストを `aria-label` として含める
- WCAG 2.1 達成基準 4.1.2（名前・役割・値）を満たすこと

生成されるコードでは、ボタンに aria-expanded={isOpen} が含まれ、対応するコンテンツ領域に id と aria-labelledby の紐付けが行われます。このプロンプトに「スクリーンリーダーが読み上げるテキストを明示してください」と追記すると、aria-label の内容も具体的に生成されます。

検証ツール連携の実装パターン

Claude Code で生成したコードが WCAG 基準を満たしているかを機械的に検証するため、axe-core・Lighthouse・Pa11y 等のツールを CI/CD パイプラインに組み込むパターンが有効です。

axe-core を使った自動テスト

axe-core は、Deque Systems が提供するオープンソースのアクセシビリティ検証エンジンで、Jest や Playwright との統合が容易です。以下は Playwright を使った検証例です。

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('生成されたボタンコンポーネントが WCAG AA を満たす', async ({ page }) => {
  await page.goto('http://localhost:3000/button-demo');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();
  expect(results.violations).toHaveLength(0);
});

このテストを GitHub Actions で実行すると、プルリクエスト時点でアクセシビリティ違反を検出できます。Claude Code で生成したコンポーネントに aria-label の不足やコントラスト不足がある場合、violations 配列に詳細が記録され、修正箇所が明確になります。

検証結果の violations には、違反した達成基準（wcag2a・wcag2aa 等）、対象要素のセレクタ、修正方法の説明が含まれます。この情報を Claude Code に再度渡すことで、修正コードを生成できます。

以下の axe-core 違反レポートを修正してください。

違反内容:
- ルール: button-name
- 要素: button.primary-btn
- 説明: ボタンに判別可能な名前がありません
- 修正方法: aria-label または内部テキストを追加してください

現在のコード:
[ここに生成されたコード全体を貼り付け]

このプロンプトにより、Claude Code は該当のボタンに aria-label="送信" を追加するか、<span>送信</span> のような内部テキストを挿入した修正版を出力します。

Lighthouse CI の活用

Lighthouse は、Google が提供するパフォーマンス・アクセシビリティ監査ツールで、CI 環境で実行できる Lighthouse CI を使うと、継続的なスコア管理が可能です。

# .github/workflows/lighthouse.yml
name: Lighthouse CI
on: [pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - run: npx lhci autorun --collect.url=http://localhost:3000

lighthouserc.json で Accessibility スコアの閾値を設定すると、スコアが基準を下回った場合に CI が失敗します。

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", {"minScore": 0.9}]
      }
    }
  }
}

Claude Code で生成したページが Lighthouse の Accessibility スコア 90 未満になった場合、レポートの「Opportunities」セクションに改善項目が列挙されるため、それをプロンプトに含めて再生成すると効率的です。コード品質メトリクス記事でも触れていますが、Lighthouse スコアは単一の指標として扱いやすく、チーム内で合意形成しやすい利点があります。

修正優先度の判断基準

アクセシビリティ違反が複数検出された場合、どの順序で修正するかの優先順位付けが必要です。WCAG レベル（A・AA・AAA）と影響範囲（ユーザー数・頻度）を軸に判断します。

この優先順位を Claude Code へのプロンプトに反映させる例を示します。

以下のフォームコンポーネントに、アクセシビリティ違反の修正を適用してください。

修正対象（優先度順）:
1. input 要素に label を関連付ける（WCAG 4.1.2 レベル A）
2. エラーメッセージを aria-live="assertive" でライブリージョン化（WCAG 4.1.3 レベル AA）
3. 送信ボタンのコントラスト比を 4.5:1 以上に引き上げる（WCAG 1.4.3 レベル AA）

現在のコード:
[ここにコードを貼り付け]

このプロンプトにより、Claude Code は番号順に修正を適用したコードを生成します。優先度をプロンプトに明示することで、部分的な修正や段階的なリリースにも対応しやすくなります。

動的コンポーネントでの注意点

モーダル・ドロワー・トースト通知など、動的に表示される要素は、フォーカス管理とライブリージョンの設定が重要です。Claude Code が生成するコードでは、これらが不足するケースがあるため、プロンプトで明示的に要求します。

モーダルのフォーカストラップ

モーダルが開いたとき、フォーカスがモーダル内に閉じ込められ（focus trap）、背景の要素に移動しないようにする必要があります。

以下のモーダルコンポーネントを生成してください。

要件:
- モーダル開閉時に、最初のフォーカス可能要素にフォーカスを移動
- Tab キーでモーダル内の要素を巡回し、最後の要素から最初の要素に戻る
- Escape キーでモーダルを閉じ、フォーカスを開く前の要素に戻す
- 背景の要素に aria-hidden="true" を設定
- WCAG 2.1 達成基準 2.4.3（フォーカス順序）を満たすこと

Claude Code は、useEffect 内で querySelector('[tabindex="0"]') を使ってフォーカス移動を実装しますが、focus trap のライブラリ（focus-trap-react 等）を使う場合は、「focus-trap-react を使ってフォーカストラップを実装してください」と追記すると、ライブラリの統合コードが生成されます。

ライブリージョンでの通知

トースト通知やエラーメッセージなど、画面に動的に表示される情報は、aria-live 属性でスクリーンリーダーに通知します。

以下のトースト通知コンポーネントを生成してください。

要件:
- 通知が表示されたとき、スクリーンリーダーが内容を読み上げる
- 成功メッセージは aria-live="polite"、エラーメッセージは aria-live="assertive" とする
- role="status" または role="alert" を適切に使い分ける
- WCAG 2.1 達成基準 4.1.3（ステータスメッセージ）を満たすこと

生成されるコードでは、成功通知に <div role="status" aria-live="polite"> が、エラー通知に <div role="alert" aria-live="assertive"> が適用されます。この違いにより、緊急性の高いエラーは即座に読み上げられ、情報提供の通知は現在の読み上げが終わった後に伝えられます。

既存コードへの適用パターン

Claude Code を使って、既存のアクセシビリティ違反を修正する場合のワークフローを示します。

1. axe DevTools で違反を特定 — ブラウザの開発者ツールで axe DevTools 拡張機能を実行し、違反リストを取得します。
2. 違反レポートを Claude Code に渡す — 違反内容（ルール名・要素セレクタ・説明）と現在のコードをプロンプトに含めます。
3. 修正コードを生成 — Claude Code が違反箇所を特定し、修正版を出力します。
4. 再検証 — axe-core の自動テストを実行し、violations が 0 になるか確認します。
5. コミット — 修正内容をコミットし、プルリクエストを作成します。

このサイクルを繰り返すことで、段階的に WCAG 準拠度を高められます。プロダクト開発記事でも述べていますが、Claude Code は「一度の生成ですべてが完成する」ツールではなく、検証と再生成を繰り返して精度を上げるプロセスを前提としています。

まとめ

Claude Code を使ったアクセシビリティ対応では、WCAG 基準をプロンプトに明示し、生成コードを axe-core や Lighthouse で検証するサイクルを回すことが実務上の核心です。コントラスト比・キーボード操作・ARIA 属性の設定など、個別の達成基準ごとに具体的な要件を記述すれば、初回生成時点で基準を満たすコードが得られる確率が上がります。

ただし、動的なインタラクション（モーダル・ライブリージョン等）では、フォーカス管理やスクリーンリーダーへの通知が不足するケースがあるため、生成後の検証と追加指示が不可欠です。修正優先度は、WCAG レベル A 違反を最優先し、高頻度利用箇所のレベル AA 違反を次点とする基準で判断すると、限られたリソースで効果的に対応できます。

アクセシビリティは「後回しにできない」領域であり、開発初期段階から Claude Code に組み込む体制を作ることで、QA 工程での手戻りと修正コストを大幅に削減できます。

---

Claude Code のアクセシビリティ対応を組織全体に定着させたい方へ

株式会社デジライズでは、WCAG 基準に基づくプロンプト設計と検証ツール連携を含む Claude Code 法人導入支援 を提供しています。フロントエンド開発チーム向けの実践研修では、axe-core・Lighthouse CI の統合方法や、修正優先度の判断基準をハンズオン形式で学べます。また、既存プロジェクトへの適用コンサルティングでは、違反レポートの分析から段階的な修正計画の策定まで伴走します。

初回の無料相談では、現在のアクセシビリティ対応状況をヒアリングし、Claude Code を使った具体的な改善フローをご提案します。まずはお気軽にお問い合わせください。

関連記事

• Claude Code アクセシビリティ対応｜実装から監査までの完全ガイド
• Claude Code コード品質メトリクス｜測定・改善・可視化の実践手法
• Claude Code プロダクト開発｜要件定義から運用までの実践ガイド