Communitygithub.com

wcag-audit

Web UIのアクセシビリティをWCAG 2.2に基づいて監査・修正します。静的ソーススキャン、実ブラウザでのランタイムスキャン、検証、修正、レポート出力を段階的に実行します。

wcag-audit とは?

このスキルは、Claude CodeやCursorなどのAIエージェントがWeb UIのアクセシビリティ(a11y)をWCAG 2.2に準拠して監査・修正するためのものです。ユーザーが「アクセシビリティを監査して」「スクリーンリーダー対応を確認して」「カラーコントラストを修正して」などと依頼した際に、5つのフェーズからなる手順を自動実行します。 まず、HTML/JSX/TSX/Vue/Svelte/Astro/MDX/Angular/CSSなどのソースコードを静的にスキャンし、カスタムコンポーネントや動的値などツールでは検出できない問題も手動レビューで追加します。次に、実際のブラウザ(Playwrightベース)でページを開き、axe-coreによるランタイムスキャンとキーボード操作チェックを実行します。すべての候補に対して、ソーストレースやDOM確認による反証(verification)を行い、疑似問題を排除します。確認された問題のみに最小限の修正を適用し、再検証を実施。最後にマシンリーダブルなJSONレポートとMarkdownサマリーを生成します。 対応プラットフォームはNode.js環境で、CLIツール「@mintwork/wcag-audit-skill」を利用。オフラインなどでCLIが使えない場合は、マニュアルモードでルールリストに従って同様の手順を進めます。重要な原則として、「ネイティブHTMLを優先」「最小限の修正で動作を変えない」「自動化は過信しない」を掲げ、修正はフレームワークのイディオム(ReactのhtmlFor、Vueの:aria-labelなど)に従います。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

WCAG 監査

あなたはユーザーインターフェースのアクセシビリティ障壁を監査し、修正しています。障害を持つユーザーは、マウスを使えるユーザーのようにラベルの欠落を回避できません。確認された各発見は、実際の人を妨げる本当のバグとして扱ってください。

目標: 検証済みの発見事項のリストを作成し、それぞれをWCAG 2.2の達成基準に関連付け、正確な場所、証拠、最小限の修正を示すこと。そして修正を適用し、再検証することです。

原則

  1. 検証されなければ出荷しない。 すべての発見事項はフェーズ3を通過しなければなりません。ユーザーが無視することを覚える長いリストよりも、真の問題が含まれる短いリストの方が優れています。
  2. まずネイティブHTML。 最善のARIAはARIAを使わないことです。<div onClick>は、role、tabindex、キーハンドラを付け足すのではなく、<button>にすることで修正してください。
  3. 最小限で動作を維持する修正。 問題のあるマークアップだけを変更し、周囲のコードを再スタイル、リファクタリング、再フォーマットしないでください。発見事項が視覚的なもの(コントラスト、フォーカスリング、ターゲットサイズ)でない限り、ビジュアルデザインは変更しないでください。
  4. コンテンツを決して invent しない。 代替テキスト、ラベル、リンクテキストは、UIが実際に意味するものを反映しなければなりません。画像が何を伝えているか分からない場合は、発見事項をneeds_validationとしてマークして質問し、alt="image"と書かないでください。
  5. 自動化は下限であり、上限ではない。 ツールはWCAG違反の約3分の1から半分しか検出しません。テストされなかった項目を報告してください(手動チェックリストを参照)。

セットアップ

ユーザーのリクエストからスコープを決定します: リポジトリ全体、ディレクトリ、特定のコンポーネント、またはURL。次にツールを確認します:

npx --yes @mintwork/wcag-audit-skill --version        # CLIは利用可能か?

CLIが利用できない場合(オフライン、Nodeなし)、手動モードで続行します: references/RULES.mdのルールリストを自分でソースを読んで適用し、ユーザーの環境に他のブラウザツールがない限りフェーズ2はスキップします。

すべての成果物はリポジトリルートの.wcag-audit/に書き込みます(作成し、.gitignoreに追加を提案することを推奨。プロジェクトがCIベースラインをコミットする場合は.wcag-audit/baseline.jsonは保持)。ユーザーが要求しない限り、他の場所には書き込まないでください。

ワークフロー

フェーズを順に実行します。どのフェーズにいるかをユーザーに伝えてください。小規模なスコープ(1コンポーネント)ではフェーズは簡潔で構いませんが、フェーズ3はスキップしないでください。

フェーズ1 — 静的スキャン(ソース)

npx @mintwork/wcag-audit-skill scan <path> --json -o .wcag-audit/static.json --fail-on none

プロジェクトがベースライン(.wcag-audit/baseline.json)をコミットしている場合でも、--baselineなしで監査してください: ベースラインはCIが既知の発見事項を無視するためのものであり、それらは依然としてレビューが必要です。

次に、references/STATIC-SCAN.mdを読み、ツールではできないレビューを行います: ネイティブ要素をラップするカスタムコンポーネント、条件付きレンダリング、デザインシステムのプロパティ(<Icon label=…>)、CSS-in-JSで削除されたり別のスタイルシートで置き換えられたフォーカススタイル(CLIは.css / .scss / .lessおよびTailwindクラスをファイルごとに1つずつチェックします)、色のみの状態、そしてスプレッドプロパティや動的な値のためにスキャナーがスキップしたものすべて。これらを"source": "static"、"confidence": "medium"で候補として追加します。

フェーズ2 — ランタイムスキャン(実際のブラウザ)

URLが利用可能な場合、またはアプリケーションを起動できる場合のみ実行します。開発コマンド(package.jsonのscripts、README)を見つけ、バックグラウンドで起動し、応答するのを待ってから:

npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# さらにページ/状態:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none

重要なページ(ホーム、主要フロー、フォーム、開いたモーダル)をスキャンします — カバーすべき状態、SPAの待機、認証についてはreferences/RUNTIME-SCAN.mdを参照してください。状態(モーダルを開く、空のフォームを送信する、ダークモード、320px)を設定ファイルにまとめ、scan --config .wcag-audit/config.jsonを実行します。ログインが必要なページには、ユーザーから提供された--storage-state <file>を使用し、決して認証情報を使用しないでください。プロジェクトにStorybookがある場合は、scan --storybook storybook-static(または実行中のStorybook URL)も実行してすべてのコンポーネント状態をカバーします。各ランタイムの発見事項のsourceHintは検索結果です。修正する前にそこで確認してください。ランタイムの発見事項は、静的分析では捕捉できないものを捉えます: 計算されたコントラスト、実際のアクセシブルな名前、フォーカス順序、キーボードトラップ、見えないフォーカス。

フェーズ3 — 検証(誤検出の除去)

すべての候補について、references/VERIFICATION.mdに従います。反証を試みます: 報告された行のソースを開き、props/slots/spreadsを値が設定されている場所までトレースし、親がラベルを提供しているかどうかを確認し、ランタイムの発見事項についてはレンダリングされたDOMを確認します。次のいずれかの判定を割り当てます:

  • confirmed — トレースして基準に違反していることが確認できた。どのようにして分かったかを記録する。
  • needs_validation — 妥当だが確定できなかった(例: 代替テキストの品質、見えないコンテンツ、到達できないページ)。修正は適用しない。
  • rejected — 反証された。理由を記録する(これにより、ユーザーはどのルールを調整すべきかを学ぶ)。

重複をマージします: 静的スキャンとランタイムスキャンの両方で報告された同じ根本原因は、両方の場所を持つ1つの発見事項とします。

フェーズ4 — 修正

confirmedの発見事項を、最も深刻度の高いものから順にreferences/FIX-PATTERNS.mdを使用して修正します。各修正について:

  1. 基準を満たす最も小さな変更を、フレームワークのイディオム(ReactではhtmlFor、Vueでは:aria-labelなど)で行います。
  2. 1~2文で説明します: 何が間違っていたのか、誰に影響したのか、何が変わったのか。
  3. ユーザーが既に了承していない限り、可視UIやコピーを変更する修正(コントラスト色、新しい可視ラベル、リンクテキスト)の前に確認を取ります。

機械的な発見事項(html-langの修正、meta-viewport-zoom、aria-attr-validのタイポ)はCLIで修正できます: scan <path> --dry-runを実行し、ユーザーに差分を表示してからscan <path> --fixを実行します。欠落しているlangは、ページの言語が分かった場合にのみ--lang <code>で追加します。

その後、機械的に再検証します:

npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json   # 開発サーバーは実行中

verifyは、問題が残っているか、修正が新しい発見事項を導入した場合に0以外で終了します。確認された発見事項が解決されるか、コードで修正できない理由(例: ユーザーからのキャプションコンテンツが必要)を説明するまで反復します。プロジェクト自身のテスト/リントを実行します。

フェーズ5 — レポート

assets/report-schema.jsonに準拠した.wcag-audit/findings.jsonを書き、検証します:

node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json

次に.wcag-audit/REPORT.mdを書き、references/REPORTING.mdに従ってユーザーに短いサマリーを提供します: 深刻度と判定別の件数、修正されたもの、ユーザーの入力を必要とするもの、テストされなかったもの。

深刻度

深刻度意味例
critical一部のユーザーがタスクを完全に実行できなくなるラベルのないフォームフィールド、唯一の送信方法としての<div onClick>、キーボードトラップ、ズーム無効化
serious大きな困難または情報の欠落低コントラストの本文テキスト、ページ言語の欠落、名前のないリンク
moderate摩擦、混乱する構造見出しレベルのスキップ、文脈の中で冗長または曖昧なリンクテキスト
minor洗練、ベストプラクティス曖昧な代替テキスト、autofocus

深刻度は、このUIにおけるユーザーへの影響を反映し、ルールのデフォルトではありません: フッターにあるラベルのない検索ボックスは、ログインページにあるラベルのないパスワードフィールドよりも深刻度が低くなります。

アンチパターン(やってはいけないこと)

  • 表示テキストと重複または矛盾するaria-labelを追加しないでください(WCAG 2.5.3違反)。
  • <button>が機能する場合にrole="button" + tabindex="0"を追加しないでください。
  • 見出し順序の問題を視覚的なサイズを変更して「修正」しないでください。レベルを変更し、CSSはそのままにしてください。
  • 情報を伝える画像にスキャナーを黙らせるためにalt=""を設定しないでください。
  • コメントの横に文書化された理由なしに発見事項を抑制(wcag-audit-ignore)しないでください。
  • WCAG「準拠」を主張しないでください — 自動化とエージェントのレビューは違反を示すことはできても、適合性を示すことはできません。
  • 生成されたコード、ベンダーコード、node_modulesのコードを変更しないでください。ソースコンポーネントを修正してください。

ファイル

関連スキル