axe-core の検出をエージェントに渡して直す — アクセシビリティ改善を CI に組み込む実装メモ

// tests/a11y/scan.spec.ts
// 主要ページを axe-core で走査し、違反を results/ に JSON 出力する
import { test } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";
import { mkdirSync, writeFileSync } from "node:fs";
 
// 検査対象。サイトの導線上で重要なページから始めるのが現実的
const PAGES = ["/", "/articles", "/membership", "/support"];
 
test.describe("accessibility scan", () => {
  for (const path of PAGES) {
    test(`scan ${path}`, async ({ page }) => {
      await page.goto(path, { waitUntil: "networkidle" });
 
      const results = await new AxeBuilder({ page })
        // WCAG 2.2 の A / AA に絞る。AAA まで入れるとノイズが急増する
        .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
        .analyze();
 
      mkdirSync("results", { recursive: true });
      const safe = path.replace(/\W+/g, "_") || "root";
      writeFileSync(
        `results/${safe}.json`,
        JSON.stringify(results.violations, null, 2),
      );
    });
  }
});

// scripts/build-fix-tasks.mjs
// results/*.json を読み、critical/serious の違反だけを修正タスクへ整形する
import { readdirSync, readFileSync, writeFileSync } from "node:fs";
 
const ALLOW = new Set(["critical", "serious"]);
const tasks = [];
 
for (const file of readdirSync("results")) {
  const violations = JSON.parse(readFileSync(`results/${file}`, "utf8"));
  for (const v of violations) {
    if (!ALLOW.has(v.impact)) continue;
    for (const node of v.nodes) {
      tasks.push({
        rule: v.id,                       // 例: "button-name"
        impact: v.impact,
        help: v.help,                     // 人間向けの一文説明
        selector: node.target.join(" "),  // 該当要素の CSS セレクタ
        html: node.html.slice(0, 200),    // 修正の手がかりになる断片
        fixHint: node.failureSummary,     // axe が示す直し方の要約
      });
    }
  }
}
 
// ルール単位でまとめると、エージェントが「同種をまとめて直す」判断をしやすい
writeFileSync("results/fix-tasks.json", JSON.stringify(tasks, null, 2));
console.log(`fixable tasks: ${tasks.length}`);

# AGENTS.md — アクセシビリティ修正タスクの制約
 
## 対象
- `results/fix-tasks.json` に列挙された違反のみを直す
- 1 PR で扱うのは同一 rule（例: button-name）に限定する
 
## 直し方の優先順位
1. まずネイティブ要素・属性で解決する（例: アイコンボタンには可視ラベルか aria-label）
2. ネイティブで足りないときだけ ARIA を最小限で足す
3. role の追加・上書きは禁止。必要なら人間にエスカレーションする
 
## 禁止事項
- 見た目（レイアウト・色・余白）を変更しない
- color-contrast 違反はコードで勝手に色を変えず、課題として報告するに留める
- セレクタに一致しない要素には触れない

# .github/workflows/a11y.yml
name: accessibility-gate
on: pull_request
 
jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
 
      # PR ブランチを走査
      - run: npx playwright test tests/a11y
      - run: node scripts/build-fix-tasks.mjs
 
      # ベースライン（main で生成済みの件数）と比較して新規増分だけを判定
      - name: Compare against baseline
        run: |
          CURRENT=$(node -e "console.log(require('./results/fix-tasks.json').length)")
          BASE=$(cat .a11y-baseline 2>/dev/null || echo 0)
          echo "baseline=$BASE current=$CURRENT"
          if [ "$CURRENT" -gt "$BASE" ]; then
            echo "::error::新規のアクセシビリティ違反が $((CURRENT - BASE)) 件増えています"
            exit 1
          fi