a11y-audit

アクセシビリティ監査

WCAG 2.2 アクセシビリティ監査と修正スキル

説明

a11y-audit スキルは、最新の Web アプリケーション向けに、アクセシビリティ監査の完全なパイプラインを提供します。Scan、Fix、Verify の 3 フェーズのワークフローを実装しており、WCAG 2.2 レベル A および AA の違反を特定し、フレームワークごとの正確な修正コードを生成し、関係者向けのコンプライアンスレポートを作成します。

検出した違反ごとに、使用しているフレームワーク（React、Next.js、Vue、Angular、Svelte、またはプレーン HTML）に合わせて、修正前と修正後の正確なコードを提示します。

このスキルの機能：

1. コードベースをスキャンし、WCAG 2.2 レベル A および AA の違反をすべて重大度（Critical、Major、Minor）別に分類します
2. フレームワーク固有の修正前・修正後のコードパターンで各違反を修正します
3. 修正によって元の違反が解消され、リグレッションが発生していないことを検証します
4. 開発者、PM、コンプライアンス関係者に適した構造化形式で検出結果を報告します
5. CI/CD パイプラインに統合し、アクセシビリティのリグレッションを防止します

機能

機能	説明
WCAG 2.2 の完全スキャン	コードベース全体のレベル A および AA の達成基準をすべてチェックします
フレームワーク検出	React、Next.js、Vue、Angular、Svelte、またはプレーン HTML を自動検出します
重大度の分類	各違反を Critical、Major、Minor に分類します
修正コードの生成	すべての問題について、修正前・修正後のコード差分を生成します
色のコントラストチェッカー	前景色と背景色の組み合わせを AA および AAA の比率で検証します
コンプライアンスレポート	合否の概要を含む関係者向けレポートを生成します
CI/CD 統合	GitHub Actions、GitLab CI、Azure DevOps のパイプライン設定
キーボード操作の監査	フォーカス管理の不足やタブ順の問題を検出します
ARIA の検証	不適切、冗長、または不足している ARIA 属性をチェックします

重大度の定義

重大度	定義	例	SLA
Critical	ユーザーグループ全体のアクセスを妨げます	alt テキストの欠落、キーボードでナビゲーションを操作できない	リリース前に修正
Major	利用体験を損なう重大な障壁です	色のコントラスト不足、フォームラベルの欠落	現在のスプリント内に修正
Minor	操作に支障をきたすユーザビリティ上の問題です	冗長な ARIA ロール、最適でない見出し階層	次の 2 スプリント以内に修正

使い方

クイックスタート

# Scan entire project
python scripts/a11y_scanner.py /path/to/project

# Scan with JSON output for tooling
python scripts/a11y_scanner.py /path/to/project --json

# Check color contrast for specific values
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

# Check contrast across a CSS/Tailwind file
python scripts/contrast_checker.py --file /path/to/styles.css

スラッシュコマンド

/a11y-audit                    # Audit current project
/a11y-audit --scope src/       # Audit specific directory
/a11y-audit --fix              # Audit and auto-apply fixes
/a11y-audit --report           # Generate stakeholder report
/a11y-audit --ci               # Output CI-compatible results

3 フェーズのワークフロー

フェーズ 1：Scan -- ソースツリーを調べ、フレームワークを検出し、ルールセットを適用します。

python scripts/a11y_scanner.py /path/to/project --format table

フェーズ 2：Fix -- 各違反に対してフレームワーク固有の修正を適用します。

修正パターンの完全なカタログについては、references/framework-a11y-patterns.md を参照してください。

フェーズ 3：Verify -- スキャナーを再実行し、修正を確認してリグレッションがないかチェックします。

python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

例：React コンポーネントの監査

// BEFORE: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}

#	WCAG	重大度	問題
1	1.1.1	Critical	<img> に alt 属性がありません
2	2.1.1	Critical	<div onClick> をキーボードで操作できません
3	1.4.3	Major	白地に #aaa の色ではコントラストが不足します（2.32:1、必要な比率は 4.5:1）
4	1.4.3	Major	白地に #999 の色ではコントラストが不足します（2.85:1、必要な比率は 4.5:1）
5	4.1.2	Major	インタラクティブ要素にロールとアクセシブルネームがありません

// AFTER: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}

Vue、Angular、Next.js、Svelte の例については、references/examples-by-framework.md を参照してください。

ツールのリファレンス

a11y_scanner.py

Usage: python scripts/a11y_scanner.py <path> [options]

Options:
  --json                  Output results as JSON
  --format {table,csv}    Output format (default: table)
  --severity {critical,major,minor}  Filter by minimum severity
  --framework {react,vue,angular,svelte,html,auto}  Force framework (default: auto)
  --baseline FILE         Compare against previous scan results
  --report                Generate stakeholder report
  --output FILE           Write results to file
  --quiet                 Suppress output, exit code only
  --ci                    CI mode: non-zero exit on critical issues

contrast_checker.py

Usage: python scripts/contrast_checker.py [options]

Options:
  --fg COLOR              Foreground color (hex)
  --bg COLOR              Background color (hex)
  --file FILE             Scan CSS file for color pairs
  --tailwind DIR          Scan directory for Tailwind color classes
  --json                  Output results as JSON
  --suggest               Suggest accessible alternatives for failures
  --level {aa,aaa}        Target conformance level (default: aa)

よくある落とし穴

落とし穴	正しい方法
<div> に role="button" を設定する	ネイティブの <button> を使います。キーボード操作への対応が標準で備わっています
すべての要素に tabindex="0" を設定する	フォーカスが必要なのはインタラクティブな要素だけです。ネイティブ要素を使います
インタラクティブでない要素に aria-label を設定する	表示されているテキストを参照する aria-labelledby を使います
スクリーンリーダーから隠すために display: none を使う	代わりに .sr-only クラスを使います
色だけで意味を伝える	色とともにアイコン、テキストラベル、またはパターンを追加します
プレースホルダーだけをラベルとして使う	常に表示される <label> を用意します
代替手段なしで outline: none を使う	focus-visible を使って、常に視認できるフォーカスインジケーターを用意します
情報を伝える画像に空の alt="" を設定する	情報を伝える画像には説明的な代替テキストが必要です
見出しレベルを飛ばす（h1 -> h3）	見出しレベルは順番に並べる必要があります
onKeyDown なしで onClick を使う	キーボード操作への対応を追加するか、ネイティブ要素を使います
prefers-reduced-motion を無視する	アニメーションは @media (prefers-reduced-motion: no-preference) で囲みます

関連スキル

スキル	関連性
senior-frontend	a11y の修正で使用するフロントエンドのパターン
code-reviewer	コードレビューのワークフローに a11y のチェックを含める
senior-qa	QA プロセスへの a11y テストの統合
playwright-pro	アクセシビリティのアサーションを用いた自動ブラウザーテスト
epic-design	WCAG 2.1 AA に準拠したアニメーションとスクロールによるストーリーテリング
tdd-guide	a11y テストケースのテスト駆動開発パターン

参考ドキュメント

参考資料	説明
wcag-quick-ref.md	WCAG 2.2 レベル A および AA の基準クイックリファレンス
wcag-22-new-criteria.md	WCAG 2.2 の新しい達成基準（フォーカスの表示、ターゲットサイズなど）
aria-patterns.md	ARIA パターン、キーボード操作、ライブリージョン
framework-a11y-patterns.md	フレームワーク固有の修正パターン（React、Vue、Angular、Svelte、HTML）
color-contrast-guide.md	色のコントラストチェッカーの詳細、Tailwind パレットのマッピング、sr-only クラス
ci-cd-integration.md	GitHub Actions、GitLab CI、Azure DevOps、pre-commit フックの設定
audit-report-template.md	関係者向けの監査レポートテンプレート
testing-checklist.md	手動テストのチェックリスト（キーボード、スクリーンリーダー、視覚、フォーム）
examples-by-framework.md	Vue、Angular、Next.js、Svelte の監査例（全編）

リソース

• WCAG 2.2 仕様
• WAI-ARIA オーサリングプラクティス 1.2
• Deque axe-core ルール
• eslint-plugin-jsx-a11y