Claude CodeでWebアクセシビリティを自動化する実践ガイド｜axe-core・Pa11y CI・WCAG 2.2 AA準拠

## アクセシビリティ基準（WCAG 2.2 AA準拠）

### 必須ルール
- すべての画像にalt属性を付与（装飾画像はalt=""）
- インタラクティブ要素にはaria-labelまたはvisible labelを必須
- 色コントラスト比: 通常テキスト4.5:1以上、大テキスト(18px+ bold/24px+)3:1以上
- キーボード操作: すべての機能がキーボードのみで操作可能
- フォーカスインジケータ: カスタムスタイル時も視認可能に（outline: none禁止）
- タッチターゲット: 最小24x24 CSSピクセル（WCAG 2.5.8）
- フォームエラー: aria-describedbyでエラーメッセージをプログラム的に関連付け
- 見出し階層: h1→h2→h3の順で飛ばさない
- ランドマーク: main, nav, header, footer を適切に使用

### 自動チェックツール
- ESLint: eslint-plugin-jsx-a11y（strictモード）
- テスト: @axe-core/playwright でE2Eテスト時にa11yチェック
- Storybook: addon-a11yでコンポーネント単位チェック
- CI: Pa11y CIでPR時に自動チェック

### 禁止パターン
- div/spanにonClick付与（button要素を使用すること）
- autofocusの無秩序な使用
- aria-hiddenをフォーカス可能な要素に付与
- tabindex > 0 の使用
- CSSのoutline: noneでフォーカスインジケータ削除

eslint-plugin-jsx-a11y をstrictモードで導入してください。

要件:
- Flat Config（eslint.config.js）形式
- strictプリセット（recommendedより厳格）
- 以下を error に設定:
  - alt-text, aria-props, aria-role, click-events-have-key-events,
    heading-has-content, label-has-associated-control
- 設定後に全ファイルでlintを実行してエラー一覧を出してください

import jsxA11y from "eslint-plugin-jsx-a11y";

export default [
  // ... other config
  {
    plugins: { "jsx-a11y": jsxA11y },
    rules: {
      ...jsxA11y.flatConfigs.strict.rules,
      // 追加で厳格にする項目
      "jsx-a11y/alt-text": "error",
      "jsx-a11y/click-events-have-key-events": "error",
      "jsx-a11y/no-noninteractive-element-interactions": "error",
      "jsx-a11y/label-has-associated-control": ["error", {
        controlComponents: ["Input", "Select", "Textarea"],
      }],
    },
  },
];

npm install --save-dev @axe-core/playwright

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

test.describe("アクセシビリティ", () => {
  test("トップページがWCAG 2.2 AA準拠", async ({ page }) => {
    await page.goto("/");
    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
      .analyze();
    expect(results.violations).toEqual([]);
  });

  test("フォームページがWCAG 2.2 AA準拠", async ({ page }) => {
    await page.goto("/contact");
    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
      .exclude("#third-party-widget") // サードパーティ部分は除外
      .analyze();
    expect(results.violations).toEqual([]);
  });
});

{
  "defaults": {
    "standard": "WCAG2AA",
    "runners": ["axe"],
    "timeout": 10000,
    "viewport": { "width": 1280, "height": 1024 }
  },
  "urls": [
    "http://localhost:3000/",
    "http://localhost:3000/about",
    "http://localhost:3000/contact",
    "http://localhost:3000/products"
  ],
  "concurrency": 4
}

name: Accessibility Check
on: pull_request

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run build

      - name: Start preview server
        run: npm run preview &

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Run Pa11y CI
        run: npx pa11y-ci

npx storybook add @storybook/addon-a11y

import type { Preview } from "@storybook/react";

const preview: Preview = {
  parameters: {
    a11y: {
      options: {
        runOnly: {
          type: "tag",
          values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"],
        },
      },
    },
  },
};

export default preview;

const meta = {
  component: Button,
  parameters: {
    a11y: {
      test: "error", // "error" = テスト失敗 / "todo" = 警告のみ / "off" = スキップ
    },
  },
} satisfies Meta<typeof Button>;

Pa11y CIの結果、以下のWCAG違反が検出されました。
すべて修正してください。

1. /about: img要素にalt属性がない（WCAG 1.1.1）
2. /contact: フォームのinputにlabelが関連付けされていない（WCAG 1.3.1）
3. /products: テキストの色コントラスト比が3.2:1（AA基準4.5:1未満）（WCAG 1.4.3）
4. /: ボタンがdiv+onClickで実装されている（WCAG 2.1.1）
5. /: フォーカスインジケータがCSSでoutline:noneされている（WCAG 2.4.7）

各違反について修正コードを生成してください。

// NG: divにonClick（キーボード操作不可）
<div onClick={handleAction} className="btn">
  送信
</div>

// OK: button要素（キーボード操作・フォーカス・スクリーンリーダー自動対応）
<button onClick={handleAction} className="btn">
  送信
</button>

// NG: スクリーンリーダーが「ボタン」としか読み上げない
<button onClick={onClose}><XIcon /></button>

// OK: ボタンの目的を伝える
<button onClick={onClose} aria-label="閉じる"><XIcon /></button>

// NG: labelとinputが関連付けされていない
<label>メールアドレス</label>
<input type="email" name="email" />

// OK: htmlForとidで関連付け
<label htmlFor="email">メールアドレス</label>
<input type="email" id="email" name="email" />

// OK: labelでinputをラップ
<label>
  メールアドレス
  <input type="email" name="email" />
</label>

import { useRef, useEffect } from "react";

interface DialogProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

export function Dialog({ isOpen, onClose, title, children }: DialogProps) {
  const dialogRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (isOpen) dialogRef.current?.focus();
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      ref={dialogRef}
      role="dialog"
      aria-modal="true"
      aria-labelledby="dialog-title"
      tabIndex={-1}
      onKeyDown={(e) => e.key === "Escape" && onClose()}
    >
      <h2 id="dialog-title">{title}</h2>
      {children}
      <button onClick={onClose}>閉じる</button>
    </div>
  );
}