Claude Codeでa11y対応を可能な限り自動化する

---
paths:
  - "frontend/src/**/*.{tsx,ts}"
---

# アクセシビリティ（a11y）規約

## 基本方針
- 視覚だけでなくキーボード操作でも利用可能にする
- WCAG 2.1 AAに準拠する

## セマンティックHTML
適切なHTMLタグを使用する。インタラクティブ要素にdivを使わない。

## ARIA属性
- 必要な場合のみ使用する
- アイコンボタンにはaria-labelを必ず付与する

## 画像
- すべての画像にalt属性を付与する
- 装飾画像はalt=""を使用する

## フォーム
- labelとinputを必ず関連付ける

## キーボード操作
- すべての操作がキーボードで可能であること
- tabindexの乱用禁止（特にtabindex > 0）

## カラーとコントラスト
- 十分なコントラスト比を確保する（AA: 4.5:1 以上）
- 色だけで情報を伝えない

## フォーカス管理
- フォーカス状態を必ず可視化する
- モーダル表示時はフォーカスを内部に閉じる（フォーカストラップ）

## 見出し構造
- h1 → h2 → h3 の順序を守る
- 見出しレベルを飛ばさない

## 禁止事項
- 非インタラクティブ要素へのクリックイベント付与
- alt属性の欠落
- キーボード操作不可のUI

npm install --save-dev eslint-plugin-jsx-a11y

#!/bin/bash
# a11y静的解析チェック（PostToolUse hook）
# Claude Codeはstdin経由でイベントJSONを渡す
 
INPUT=$(cat)  # stdinからJSONを読み込む
file=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# TSX/JSXファイルの場合のみ実行
if [[ "$file" =~ \.(tsx|jsx)$ ]]; then
  echo "🔍 a11y チェック: $file" >&2
  npx eslint "$file" --plugin jsx-a11y --rule 'jsx-a11y/alt-text: error' \
    --rule 'jsx-a11y/aria-props: error' \
    --rule 'jsx-a11y/aria-role: error' \
    --rule 'jsx-a11y/interactive-supports-focus: error' \
    --rule 'jsx-a11y/label-has-associated-control: error' \
    --rule 'jsx-a11y/no-noninteractive-element-interactions: warn' \
    --rule 'jsx-a11y/no-static-element-interactions: error'
fi

chmod +x .claude/hooks/a11y-check.sh

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/a11y-check.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

// __tests__/a11y.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('アクセシビリティ', () => {
  test('トップページに重大なa11y違反がないこと', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });

  test('フォームが正しくラベル付けされていること', async ({ page }) => {
    await page.goto('/contact');

    const results = await new AxeBuilder({ page })
      .include('#contact-form')
      .withTags(['wcag2a'])
      .analyze();

    expect(results.violations).toEqual([]);
  });
});

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx playwright test tests/a11y.spec.ts --reporter=line 2>&1 | tail -20",
            "timeout": 120,
            "async": true
          }
        ]
      }
    ]
  }
}