a11y-check-code

ソースコードのアクセシビリティチェック

ソースコードを読んで、アクセシビリティに関して優先的に対処するべき問題を発見する。 基準は WCAG 2.2 のレベル AA を目安とする。

このチェックの限界を最初に理解する

ソースコードから判定できるのは、主に実装に起因する問題である。以下は判定できない。

• 実際のコントラスト比（色が実行時に決まる場合）
• フォーカス順序が利用者にとって自然かどうか
• 200% ズームや 320px 幅での表示崩れ
• ホバーやフォーカスで表示される追加コンテンツの実挙動
• スクリーンリーダーでの実際の読み上げ

判定できないものを、判定できたかのように書いてはならない。 判定できなかった観点は 「要追加確認」としてレポートに記録し、a11y-check-page スキルへの引き継ぎ指示を生成する。

また、アクセシビリティに留まらない一般的なユーザビリティの問題や、実害はないものの HTML や WAI-ARIA の仕様・ベストプラクティスに反するものを見つけた場合も、「アクセシビリティには 関係ない」という理由で握り潰さずに報告する。

手順

1. 対象の把握

引数でファイルパス、グロブ、ディレクトリが指定されていればそれを対象とする。指定がなければ、 何を対象とするかを利用者に確認する。

次に、対象の import を辿ってコンポーネントの構成を把握する。 手順は references/component-tracing.md に従う。 辿った結果をコンポーネントツリーとして 利用者に提示し、チェックの範囲を明示してから次に進む。

あわせて、対象が何のための画面かを把握する。重篤度の判定には「そのページの主要な目的」が 必要であり、目的を把握せずに重篤度は判定できない。コードから読み取れない場合は利用者に尋ねる。

• どんな人が利用するものか（広く一般の人か、登録された利用者のみか）
• 想定されている使用デバイス（PC、スマートフォン、タブレット）
• 利用の目的（フォームの送信か、情報の閲覧か、業務の遂行か）
• 操作の流れ（画面遷移の順序、操作の順序、システムの挙動）

2. 状態バリエーションの列挙

この手順を飛ばすと、初期表示しか見ないチェックになる。必ず行う。

条件分岐、state、props、権限、データの有無によって出し分けられる表示をすべて列挙する。

• モーダル・ダイアログ・ドロップダウン・メニュー・アコーディオンの開閉
• ローディング中、エラー、空状態、権限による表示差
• フォームのバリデーションエラー表示、送信中、送信完了
• レスポンシブによる表示の分岐（モバイル用の UI は PC 用とは別のチェック対象になる）

以降の観点は、列挙したそれぞれの状態に対して適用する。

3. 観点の適用

references/ の観点表を読み、確認手段: が code または both の観点を適用する。

• references/checklist-semantics.md — 機械可読性（最も指摘が多く出る）
• references/checklist-keyboard.md — キーボード操作
• references/checklist-visual.md — 視覚・マウス操作
• references/checklist-reflow.md — ズーム・文字サイズ・ウィンドウサイズ
• references/checklist-spec.md — 仕様から判断できる問題

ファイルごとではなく、観点ごとに処理する。 ファイルを順に読んでいくと観点の抜けが 起きやすい。観点表を上から辿り、各観点について Grep で対象範囲を横断的に検索する。

使用しているフレームワークやライブラリに応じて references/framework-notes.md を参照する。 フレームワーク固有の典型的な問題と、その検出方法が書かれている。

各観点について、問題あり / 問題なし / 判定不能 / 対象なし の4値で結果を記録する。 「該当なし」を「問題なし」と書いてはならない。

4. コントラスト比の算出

色が静的に決まる箇所（Tailwind のクラス、CSS 変数、デザイントークン、CSS-in-JS のリテラル） については、同梱のスクリプトで比率を計算する。目視や暗算で判断してはならない。

node <スキルのディレクトリ>/scripts/contrast.mjs "#767676" "#ffffff"
node <スキルのディレクトリ>/scripts/contrast.mjs "#767676" "#ffffff" --size 24 --bold

<スキルのディレクトリ> は、この SKILL.md が置かれているディレクトリ（.claude/skills/ a11y-check-code など）。作業ディレクトリからの相対パスではないことに注意する。

複数の組み合わせをまとめて確認する場合は --json にペアの配列を渡せる。

node <スキルのディレクトリ>/scripts/contrast.mjs --json \
  '[{"label":"本文","fg":"#767676","bg":"#fff"},{"label":"補足","fg":"#aaa","bg":"#fff"}]'

使い方の詳細は --help を参照する。

色が実行時に決まる箇所は「判定不能」として実ページでの確認に回す。

5. レポートの出力

references/report-format.md の形式で Markdown ファイルを出力する。重篤度の判定は references/severity.md の手順に従う。影響するユーザーの多さを考慮に入れてはならない。

ソースコード対象のレポートでは、以下を必ず守る。

• すべての指摘に ファイルパス:行番号 を記載する
• 「実施しなかった手順」に、実ページでの確認（axe-core、ズーム、実際のフォーカス順序、 スクリーンリーダー）を行っていないことを明記する
• 「要追加確認」の末尾に、a11y-check-page への引き継ぎ用の指示文を生成する。 対象 URL（不明なら空欄）と、重点的に確認すべき観点 ID を列挙した形にする

会話には要約のみを出す。

判断に迷ったとき

• 推測で断定しない。 「aria-label は付いているが、表示されている文言と一致するかは 実行時の値に依存する」といったものは、指摘ではなく要確認事項として分ける
• 正しさは対象の目的に依存する。 何が正しい実装かはページの内容と目的によって変わる。 コードだけでは判断できない場合、製作者への確認事項としてレポートに挙げる
• ライブラリの内部実装を推測で断定しない。 直接依存（dependencies）については、型定義や JSDoc で props の契約（label が必須か、aria-* を forward するか等）を確認してよいが、 そこからレンダリング結果の DOM を推論して「問題なし」と書いてはならない。実装が適切かは バージョンによっても変わる。ライブラリ起因の観点は確実でなければ「要追加確認」に回し、 実ページでの確認を促す。詳しい範囲は references/component-tracing.md に従う