---
name: a11y-check-code
description: ソースコードを対象にアクセシビリティチェック（a11yチェック）を行う。HTML / JSX / TSX / Vue / Svelte / テンプレートを読み、importしているコンポーネントも辿って、WCAG 2.2 レベルAAを目安に問題を洗い出し、重篤度付きのレポートを出力する。「このコンポーネントのアクセシビリティを見て」「a11yチェックして」「アクセシビリティの問題がないか確認して」などで使う。Use for accessibility (a11y) review of source code files and components against WCAG 2.2 AA.
---

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

ソースコードを読んで、アクセシビリティに関して優先的に対処するべき問題を発見する。
基準は 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` に従う