auditing-wcag

어떤 스킬인가요?

Perform formal WCAG 2.2 A/AA conformance audits and assign Pass/Fail/NT/NA to every success criterion with evidence. Use reviewing-a11y instead for issue discovery and improvement feedback.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: 'WCAG Conformance Audit'
  short_description: 'Audit WCAG 2.2 A/AA with evidence'
  default_prompt: 'Use $auditing-wcag to audit the provided target and report Pass, Fail, NT, or NA for every applicable WCAG 2.2 A/AA criterion.'

# auditing-wcag

[English version](./README.md)

WCAG 2.2 AA準拠を体系的に監査し、達成基準ごとにPass/Fail/NT/NA判定を行うスキル。

## アーキテクチャ

テスト方法ベースの参照ガイドを使用した**ハイブリッドパターン**:

```
┌─────────────────────────────────────┐
│   auditing-wcag                     │
│   - 入力受付（URL/ファイル）         │
│   - スコープ契約の確立              │
│   - 体系的なチェック実行            │
│   - 準拠レポート生成                │
└──────────┬──────────────────────────┘
           │
    ┌──────┴────────┬─────────────┬──────────────┐
    │               │             │              │
    ▼               ▼             ▼              ▼
┌──────────┐  ┌───────────┐  ┌────────┐  ┌─────────┐
│自動チェック│  │インタラク │  │手動チェック│  │コンテンツ│
│          │  │ティブ    │  │        │  │チェック  │
└──────────┘  └───────────┘  └────────┘  └─────────┘
```

## reviewing-a11yとの使い分け

| 観点 | reviewing-a11y | auditing-wcag |
|------|----------------|---------------|
| **目的** | 問題発見・改善提案 | 準拠状況の体系的確認 |
| **出力** | 重大度別の問題リスト | 達成基準ごとのPass/Fail/NT/NA |
| **スコープ** | 実用的な問題にフォーカス | 全WCAG 2.2 A/AAを網羅 |
| **ユースケース** | 開発中のフィードバック | 監査、準拠証明 |

### 振り分けルール
- **auditing-wcag**: 「監査」「準拠確認」「コンプライアンス」、正式なレポート
- **reviewing-a11y**: 「レビュー」「チェック」「問題を見つけて」、開発フィードバック

## ワークフロー（6ステップ）

1. **入力受付**: URLまたはファイルパスの識別
2. **スコープ契約**: レベル、ページ範囲、制限事項について合意
3. **自動チェック**: Playwrightでアクセシビリティツリー解析
4. **インタラクティブチェック**: キーボード・フォーカス確認
5. **手動確認項目提示**: NTとなる項目をユーザーに提示
6. **レポート生成**: 達成基準ごとのPass/Fail/NT/NA判定

## 自動化の範囲と制限

Playwrightで取得できるのはアクセシビリティツリー（role/name/state）のみ:
- ❌ スクリーンリーダー検証（NVDA/JAWS/VoiceOver）
- ❌ 支援技術×ブラウザの互換性テスト
- ❌ 認知的なアクセシビリティ判断

自動化できない項目は**NT（Not Tested）**としてマークされます。

## レポートのステータス値

| ステータス | 意味 |
|----------|------|
| **Pass** | 達成基準を満たしている |
| **Fail** | 違反を検出 |
| **NT** | 未テスト - 支援技術/人間の確認が必要 |
| **NA** | 適用外 - 対象コンテンツが存在しない |

## ファイル構成

```
skills/auditing-wcag/
├── SKILL.md                        # メインスキル（英語）
├── SKILL.ja.md                     # メインスキル（日本語）
├── agents/openai.yaml               # Codex UIメタデータ
├── README.md                       # 英語README
├── README.ja.md                    # このファイル
└── references/
    ├── automated-checks.md         # 自動テスト可能な基準
    ├── automated-checks.ja.md
    ├── interactive-checks.md       # インタラクションベースのチェック
    ├── interactive-checks.ja.md
    ├── manual-checks.md            # 人間の判断が必要
    ├── manual-checks.ja.md
    ├── content-checks.md           # コンテンツ品質チェック
    ├── content-checks.ja.md
    ├── output-format.md            # レポートテンプレート
    ├── output-format.ja.md
    ├── coverage-matrix.md          # 全A/AAカバレッジマトリクス
    └── coverage-matrix.ja.md
```

## 使用例

```
https://example.com のWCAG準拠を監査して
https://mysite.com のWCAG 2.2 AAコンプライアンスをチェック
```

## 参考資料

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [WCAG 2.2 日本語訳](https://waic.jp/translations/WCAG22/)
- [WCAG クイックリファレンス](https://www.w3.org/WAI/WCAG22/quickref/)

# auditing-wcag

[日本語版 (Japanese)](./README.ja.md)

A skill for systematically auditing WCAG 2.2 AA conformance with Pass/Fail/NT/NA judgments per success criterion.

## Architecture

This skill uses a **hybrid pattern** with test-method-based reference guides:

```
┌─────────────────────────────────────┐
│   auditing-wcag                     │
│   - Accepts input (URL/files)       │
│   - Establishes scope contract      │
│   - Executes checks systematically  │
│   - Generates conformance report    │
└──────────┬──────────────────────────┘
           │
    ┌──────┴────────┬─────────────┬──────────────┐
    │               │             │              │
    ▼               ▼             ▼              ▼
┌──────────┐  ┌───────────┐  ┌────────┐  ┌─────────┐
│Automated │  │Interactive│  │ Manual │  │ Content │
│ Checks   │  │  Checks   │  │ Checks │  │ Checks  │
└──────────┘  └───────────┘  └────────┘  └─────────┘
```

## When to Use This vs reviewing-a11y

| Perspective | reviewing-a11y | auditing-wcag |
|-------------|----------------|---------------|
| **Goal** | Find issues and propose fixes | Systematic conformance verification |
| **Output** | Severity-based issues list | Pass/Fail/NT/NA per criterion |
| **Scope** | Practical issues focus | Full WCAG 2.2 A/AA coverage |
| **Use Case** | Development feedback | Audit, compliance, certification |

### Routing Rules
- **auditing-wcag**: "audit", "compliance", "conformance", formal reporting
- **reviewing-a11y**: "review", "check", "find issues", dev feedback

## Workflow (6 Steps)

1. **Input Acceptance**: URL or file path identification
2. **Scope Contract**: Get agreement on level, pages, and limitations
3. **Automated Checks**: Playwright accessibility tree analysis
4. **Interactive Checks**: Keyboard and focus verification
5. **Manual Check Items**: Present NT items to user
6. **Report Generation**: Pass/Fail/NT/NA per criterion

## Automation Scope and Limits

Playwright provides computed accessibility tree (role/name/state) only:
- ❌ Screen reader verification (NVDA/JAWS/VoiceOver)
- ❌ AT × browser compatibility testing
- ❌ Cognitive accessibility judgment

Items that cannot be automated are marked as **NT (Not Tested)**.

## Report Status Values

| Status | Meaning |
|--------|---------|
| **Pass** | Criterion is satisfied |
| **Fail** | Violation detected |
| **NT** | Not Tested - requires AT/human verification |
| **NA** | Not Applicable - target content doesn't exist |

## File Structure

```
skills/auditing-wcag/
├── SKILL.md                        # Main skill (English)
├── SKILL.ja.md                     # Main skill (Japanese)
├── agents/openai.yaml               # Codex UI metadata
├── README.md                       # This file
├── README.ja.md                    # Japanese README
└── references/
    ├── automated-checks.md         # Auto-testable criteria
    ├── automated-checks.ja.md
    ├── interactive-checks.md       # Interaction-based checks
    ├── interactive-checks.ja.md
    ├── manual-checks.md            # Human judgment required
    ├── manual-checks.ja.md
    ├── content-checks.md           # Content quality checks
    ├── content-checks.ja.md
    ├── output-format.md            # Report template
    ├── output-format.ja.md
    ├── coverage-matrix.md          # Full A/AA coverage matrix
    └── coverage-matrix.ja.md
```

## Usage Examples

```
Audit WCAG conformance for https://example.com
Run WCAG 2.2 AA compliance check on https://mysite.com
```

## References

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [WCAG Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/)

[English](./automated-checks.md)

# 自動チェック (Playwright a11y tree)

Playwrightのアクセシビリティツリーから機械的に判定できる項目のみを扱います。判定は「Fail/Pass/NT/NA」を明示し、証跡はa11y treeスナップショットまたはDOM断片を保存します。

> **CLIチェック:** `axe-audit` チェックはaxe-coreによる包括的な自動チェックを提供し、以下の多くの基準に加えて追加ルールもカバーします。まず実行して広範囲をカバーし、その後手動チェックで補完してください。
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks axe-audit`

## 判定ルールの共通方針
- 取得元: `page.accessibility.snapshot()` / DOM属性
- 証跡: 要素のロール、名前、関連属性、XPath/CSSセレクタ
- Fail条件: ルールに一致しない要素が1件でもある

## 構造・セマンティクス
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.3.1 | 見出し/ランドマーク/リスト/テーブルが適切なロールで表現されている | a11y tree断片 | 意味的に必要な要素が全てプレーンテキスト扱いになる |
| 1.3.2 | a11y treeの順序がDOM順と一致している | a11y tree + DOM順 | 読み上げ順がDOM順と矛盾する構造がある |
| 2.4.1 | 主要ブロックを飛ばす手段の存在（スキップリンク / mainランドマーク / メインコンテンツ内の見出し） | a11y tree（リンク名、ランドマーク、見出し構造） | スキップリンク・mainランドマーク・適切な見出しのいずれもない |
| 2.4.2 | ページタイトルが空でない | `document.title` | タイトル未設定/空文字 |
| 2.4.6 | 見出し/ラベルにアクセシブルネームがある | a11y treeのname | 見出し/ラベルが無名 |

## 代替テキスト
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.1.1 | 画像のアクセシブルネーム有無（`alt`/`aria-label`等） | a11y tree | 情報性のある画像が無名 |
| 3.3.2 | フォーム入力にラベルまたは説明が紐付いている | a11y tree + DOM | 入力要素が無名/説明不足 |

## 時間依存メディア
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.2.1 | 音声/映像のみにテキスト代替がある | DOM + a11y tree | メディア要素の近くにトランスクリプトリンクなし |
| 1.2.2 | 映像にキャプションがある | axe video-caption + DOM | `<video>` に `<track kind="captions">` なし |
| 1.2.3 | 映像に音声解説またはメディア代替がある | DOM | `<video>` に `<track kind="descriptions">` なし、トランスクリプトリンクもなし |
| 1.2.5 | 映像に音声解説がある | DOM | `<video>` に `<track kind="descriptions">` なし |

> **1.2.x チェック:** メディア要素を検出し、代替を確認：
>
> 1. **メディア検出:** `<video>`, `<audio>`, 埋め込みプレーヤー（YouTube/Vimeoの`<iframe>`）を検出
> 2. **トラック確認:**
>    - 1.2.2 用に `<track kind="captions">`
>    - 1.2.3, 1.2.5 用に `<track kind="descriptions">`
> 3. **代替確認:**
>    - 近くに「transcript」「text version」「文字起こし」「代替テキスト」等のリンク
>    - テキスト代替を指す `aria-describedby`
>
> **制限事項:**
> - キャプション/音声解説の品質・正確性は確認不可
> - トランスクリプトが必要な音声のみコンテンツは検出困難
> - 埋め込みプレーヤー（YouTube/Vimeo）は独自のキャプションシステムあり — 手動確認にフラグ
>
> **Pass:** メディアに適切なtrack要素または近くに代替リンクあり
> **Fail:** メディア要素にtrackなし、代替も検出されず

## ARIA
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 4.1.2 | ロール/名前/値が取得可能 | a11y tree | インタラクティブ要素が無名/ロール不明 |
| 4.1.3 | ステータスメッセージが適切なロールで露出 | a11y tree | 状態変化がrole="status"等で表出しない |
| 2.5.3 | 視覚ラベルの文字列がアクセシブルネームに含まれる | DOMテキスト + a11y name | ラベル文字列がnameに含まれない |

## 色・コントラスト
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.4.1 | UI識別に色名を使用しているテキスト | a11y treeのテキスト | 色名がUI要素の識別や情報伝達に使用されている |
| 1.4.3 | テキストコントラスト比がAA基準を満たす | axe color-contrast | 4.5:1未満（通常）または3:1未満（大きい文字） |
| 1.4.11 | 非テキスト要素のコントラストがAA基準を満たす | axe非テキストコントラストルール | 3:1未満 |

> **1.4.1 チェックA - テキスト参照:** アクセシブルなテキスト内の色名参照（赤、青、緑、レッド、ブルー等）を探し、色だけに依存していないか確認：
> - 指示: 「必須項目は赤字」「緑のボタンをクリック」
> - 状態: 「エラーは赤で表示」「空きは緑」
> - データラベル: 「赤=メアリー、青=トム」
>
> **Pass:** 色と形状/シンボルを併用している場合（例: 「赤い丸」「緑の三角アイコン」「青い四角ボタン」）
>
> **Fail:** 色のみで識別し、形状/シンボルの言及がない場合
>
> 「赤字経営」のような慣用表現と、実際の色依存を区別して判断する。
>
> **1.4.1 チェックB - テキスト内リンク (F73):** 文章中のリンクは色だけに依存せず視覚的に区別できる必要がある：
> - **Pass:** リンクに下線がある、または他の非色手段（枠線、アイコン、太字等）がある
> - **Pass:** リンク色と周囲テキストのコントラスト比が3:1以上 かつ hover/focus時に追加の視覚的手がかりがある
> - **Fail:** リンクに下線がなく、周囲テキストとのコントラスト比が3:1未満
>
> axe-coreの`link-in-text-block`ルールでカバーされる。axe結果でこのルールを確認。
>
> **1.4.1 チェックC - 視覚的状態の区別:** スクリーンショットで同じ形状の要素が色のみで区別されている場合、a11y treeで状態がプログラム的に公開されているか確認：
>
> | 視覚パターン | 必要なセマンティクス |
> |-------------|---------------------|
> | 選択中タブ（色が違う） | `aria-selected="true"` |
> | 現在のナビ項目（色が違う） | `aria-current="page"` |
> | カレンダーの今日（色が違う） | `aria-current="date"` |
> | エラーフィールド（赤枠） | `aria-invalid="true"` |
> | 必須フィールド（色が違う） | `aria-required="true"` または `required` |
> | 無効ボタン（グレーアウト） | `aria-disabled="true"` または `disabled` |
>
> **Pass:** a11y treeで状態が公開されている。 **Fail:** 色だけが唯一の区別手段。

> **Note:** axe-coreは複雑な背景画像やグラデーションのコントラストをチェックできません。一部のケースでは手動確認が必要な場合があります。

## 感覚的な特徴
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.3.3 | 感覚的手がかりだけに依存しない指示 | a11y treeテキスト | プログラム的な代替なしの感覚依存指示 |

> **1.3.3 チェック:** アクセシブルテキスト内の感覚的特徴への参照を探し、感覚だけに依存していないか確認：
>
> | 感覚タイプ | 例 |
> |-----------|-----|
> | 位置 | 「右側の」「左のメニュー」「上の」「下の」「隣の」 |
> | 形 | 「丸いボタン」「四角いアイコン」「三角の」 |
> | サイズ | 「大きいボタン」「小さいリンク」 |
> | 音 | 「ビープ音が鳴ったら」「チャイムの後」 |
> | 視覚 | 「画像を見て」「図のように」「ハイライトされた部分」 |
>
> **Pass:** 感覚的手がかりとプログラム的識別子を併用（例: 「右側の送信ボタン」「丸い検索アイコン」）
>
> **Fail:** 感覚的手がかりのみで要素を識別（例: 「右のボタンをクリック」で他の識別子なし）
>
> 注: 1.4.1の色チェックより抽象的。文脈を考慮して判断。

## 入力目的
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 1.3.5 | 入力フィールドに適切なautocomplete属性がある | `autocomplete-audit` **[CLI]** | ユーザーデータフィールドでautocomplete欠落/不正 |

> **CLIチェック:** `autocomplete-audit` チェックはフィールド名/ラベルから期待されるautocompleteトークンと照合し、欠落・不正値を報告。
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks autocomplete-audit`

## 言語
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 3.1.1 | `<html lang>`が有効な言語タグ | DOM属性 | lang未設定/無効 |
| 3.1.2 | 部分の言語が識別されている | DOM + a11y treeテキスト | 外国語テキストにlang属性なし |

> **3.1.2 チェック:** 2段階のチェック：
>
> 1. **axe-core `valid-lang` ルール:** 要素の無効なlang属性値を検出
>
> 2. **外国語テキスト検出:** ページの主言語と異なる言語のコンテンツを探す：
>    - 異なる文字体系のテキストを検出（例: 英語ページ内の日本語、日本語ページ内のラテン文字）
>    - よくある外国語フレーズ/単語を検出
>    - 含まれる要素に適切な`lang`属性があるか確認
>
> **Pass:** 外国語テキストが正しい`lang`属性で囲まれている（例: `<span lang="en">English</span>`）
> **Fail:** 外国語テキストに`lang`属性がない
>
> 注: 短い借用語（例: 「カフェ」「寿司」）はlang属性不要な場合あり。文脈で判断。

## リンク/ボタン
| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 2.4.4 | リンクのアクセシブルネームが空でなく曖昧でない | a11y tree | 空/無名または文脈なしで曖昧なリンク |
| 3.2.1 | フォーカス時に意図しないコンテキスト変更がない（DOM差分で検知） | DOM差分ログ | フォーカスのみでページ遷移や大幅な更新 |
| 3.2.2 | 入力変更時に自動送信/遷移がない（DOM差分で検知） | DOM差分ログ | 入力操作のみで送信/遷移 |

> **2.4.4 チェック:** 2段階の自動チェック：
>
> 1. **空リンク:** axe-coreの`link-name`ルールでアクセシブルネームなしのリンクを検出
>
> 2. **文脈なしの曖昧なリンク:** 汎用的なテキストでonly-child（周囲に文脈なし）のリンクを検出：
>    - 汎用用語: 「こちら」「詳細」「もっと見る」「続きを読む」「click here」「here」「more」「read more」「learn more」「details」「continue」
>    - 親要素内でonly-child（兄弟テキストによる文脈なし）かどうか
>    - `aria-describedby`や`aria-labelledby`による文脈がないかどうか
>
> **Pass:** 説明的なリンクテキスト、または汎用テキストでも周囲に文脈あり
>
> **Fail:** 汎用リンクテキスト かつ only-child かつ プログラム的文脈なし

## ページ横断チェック

全監査対象ページからデータを収集した後に実行するチェック。a11y treeスナップショットとリンクデータを全ページから収集後に判定。

| 基準 | 自動チェック | 証跡 | Fail条件 |
|---|---|---|---|
| 2.4.5 | ページへの到達手段が複数ある | リンクグラフ + 検索/サイトマップ検出 | 単一経路のみで検索/サイトマップなし |
| 3.2.3 | 同一サイト内で主要ナビゲーションの構造が一致 | a11y tree比較 | ナビゲーション構造が大きく異なる |
| 3.2.4 | 同一機能のコンポーネントが同一ロール/名前で表現 | a11y tree比較 | 同一機能の名前/ロールが不一致 |
| 3.2.6 | ヘルプ手段（FAQ/連絡先等）が一貫して提供 | a11y tree比較 | あるページだけヘルプが欠落 |

> **2.4.5 チェック:** 全監査対象ページからリンクを収集後：
>
> 1. リンクグラフ構築: 各ページから全`<a href>`を抽出
> 2. 複数手段の確認:
>    - **検索:** 検索フォームを検出（`role="search"`、`input[type="search"]`、または検索関連ラベルのフォーム）
>    - **サイトマップ:** サイトマップページを検出（テキスト/hrefに「sitemap」を含むリンク）— 監査対象にサイトマップを含めることを推奨
>    - **相互リンク:** 各ページが複数のページからリンクされている
> 3. 到達可能性分析:
>    - 1つのソースからのみリンク かつ 検索なし かつ サイトマップなし → 潜在的問題
>
> **Pass:** サイトに検索あり、またはサイトマップあり、またはページが複数ソースから相互リンク
> **Fail:** 単一ナビゲーション経路のみで代替手段なし

> **3.2.3 チェック:** 繰り返しナビゲーションの構造を比較：
>
> 1. ランドマーク領域を抽出: `banner`（ヘッダー）、`navigation`、`contentinfo`（フッター）
> 2. 各ランドマーク内の子構造をページ間で比較：
>    - ナビ項目の相対順序が同じ（アクセシブルネームで照合）
>    - 対応する項目のロールが同じ
> 3. 以下は許容：
>    - 現在ページ表示の違い（例: 異なる項目に`aria-current="page"`）
>    - 一部ページで項目が省略されていても、残りの項目が**相対的に同じ順序**を維持
>
> **相対的に同じ順序の例外:** ページ1が「A, B, C, D」、ページ2が「A, C, D」（Bが省略）の場合、A→C→Dの順序が維持されているため**Pass**。ただし「A, D, C」は**Fail**。
>
> **Pass:** 共有ナビ項目の相対順序が全ページで一貫
> **Fail:** ナビ項目の相対順序がページ間で異なる

[日本語版 (Japanese)](./automated-checks.ja.md)

# Automated Checks (Playwright a11y tree)

Only machine-verifiable items from the Playwright accessibility tree are covered. Each result must be labeled Pass/Fail/NT/NA and include evidence from the a11y tree or DOM fragment.

> **CLI Check:** The `axe-audit` check provides comprehensive automated checks via axe-core, covering many of the criteria below plus additional rules. Run it first for broad coverage, then supplement with manual checks.
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks axe-audit`

## Common Judgment Rules
- Source: `page.accessibility.snapshot()` / DOM attributes
- Evidence: role, name, relevant attributes, XPath/CSS selector
- Fail rule: any element violating the rule

## Structure/Semantics
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.3.1 | Headings/landmarks/lists/tables expressed with correct roles | a11y tree snippet | Required semantic elements collapse to plain text |
| 1.3.2 | a11y tree order matches DOM order | a11y tree + DOM order | Reading order conflicts with DOM order |
| 2.4.1 | Bypass mechanism present (skip link / main landmark / headings within main content) | a11y tree (link names, landmarks, heading structure) | No skip link, main landmark, or proper headings |
| 2.4.2 | Page title is non-empty | `document.title` | Title missing/empty |
| 2.4.6 | Headings/labels have accessible names | a11y tree name | Heading/label is unnamed |

## Alt Text
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.1.1 | Image has accessible name (`alt`/`aria-label`, etc.) | a11y tree | Informative image is unnamed |
| 3.3.2 | Form inputs have labels or descriptions | a11y tree + DOM | Input is unnamed/undocumented |

## Time-based Media
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.2.1 | Audio/video-only has text alternative | DOM + a11y tree | Media element without transcript link nearby |
| 1.2.2 | Video has captions | axe video-caption + DOM | `<video>` without `<track kind="captions">` |
| 1.2.3 | Video has audio description or media alternative | DOM | `<video>` without `<track kind="descriptions">` and no transcript link |
| 1.2.5 | Video has audio description | DOM | `<video>` without `<track kind="descriptions">` |

> **1.2.x Checks:** Detect media elements and verify alternatives:
>
> 1. **Find media:** Detect `<video>`, `<audio>`, and embedded players (`<iframe>` with YouTube/Vimeo)
> 2. **Check for tracks:**
>    - `<track kind="captions">` for 1.2.2
>    - `<track kind="descriptions">` for 1.2.3, 1.2.5
> 3. **Check for alternatives:**
>    - Nearby links with "transcript", "text version", "代替テキスト", "文字起こし" etc.
>    - `aria-describedby` pointing to text alternative
>
> **Limitations:**
> - Cannot verify caption/description quality or accuracy
> - Cannot detect audio-only content that should have transcript
> - Embedded players (YouTube/Vimeo) may have their own caption system — flag for manual review
>
> **Pass if:** Media has appropriate track elements or nearby alternative links.
> **Fail if:** Media element found with no track and no alternative detected.

## ARIA
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 4.1.2 | Role/name/value are computable | a11y tree | Interactive element is unnamed/role missing |
| 4.1.3 | Status messages exposed via proper role | a11y tree | State changes not exposed via role="status", etc. |
| 2.5.3 | Visible label text included in accessible name | DOM text + a11y name | Label text missing from name |

## Color/Contrast
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.4.1 | Text references to color for UI identification | a11y tree text | Color name used to identify UI elements or convey information |
| 1.4.3 | Text contrast ratio meets AA | axe color-contrast | Ratio below 4.5:1 (normal) or 3:1 (large) |
| 1.4.11 | Non-text contrast meets AA | axe non-text color contrast rules | Ratio below 3:1 |

> **1.4.1 Check A - Text references:** Scan accessible text for color references (red, blue, green, etc. in any language/variation) that indicate reliance on color alone:
> - Instructions: "Required fields are red", "Click the green button"
> - Status: "Errors shown in red", "Available in green"
> - Data labels: "Red = Mary, Blue = Tom"
>
> **Pass if:** Color is used together with shape/symbol (e.g., "red circle", "green triangle icon", "blue square button").
>
> **Fail if:** Color alone identifies the element with no shape/symbol reference.
>
> Use judgment to distinguish actual color-reliance from idioms ("in the red" = financial loss).
>
> **1.4.1 Check B - Links in text (F73):** Links within text blocks must be visually distinguishable without relying on color alone:
> - **Pass if:** Link has underline, or other non-color indicator (border, icon, bold, etc.)
> - **Pass if:** Link color has ≥3:1 contrast ratio against surrounding text AND has additional visual cue on hover/focus
> - **Fail if:** Link has no underline AND contrast ratio against surrounding text is <3:1
>
> axe-core's `link-in-text-block` rule covers this. Check axe results for this specific rule.
>
> **1.4.1 Check C - Visual state differentiation:** When screenshot shows elements of the same shape distinguished only by color, verify the a11y tree exposes the state programmatically:
>
> | Visual pattern | Required semantics |
> |----------------|-------------------|
> | Selected tab (different color) | `aria-selected="true"` |
> | Current nav item (different color) | `aria-current="page"` |
> | Today in calendar (different color) | `aria-current="date"` |
> | Error field (red border) | `aria-invalid="true"` |
> | Required field (different color) | `aria-required="true"` or `required` |
> | Disabled button (grayed out) | `aria-disabled="true"` or `disabled` |
>
> **Pass if:** State is exposed in a11y tree. **Fail if:** Color is the only differentiator.

> **Note:** axe-core cannot check contrast against complex background images or gradients. Manual verification may still be needed in some cases.

## Sensory Characteristics
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.3.3 | Instructions not relying solely on sensory cues | a11y tree text | Sensory-only instructions without programmatic alternative |

> **1.3.3 Check:** Scan accessible text for sensory characteristic references that may indicate reliance on sensory cues alone:
>
> | Sensory type | Example phrases |
> |--------------|-----------------|
> | Position | "right side", "left menu", "above", "below", "next to" |
> | Shape | "round button", "square icon", "triangle" |
> | Size | "large button", "small link", "big icon" |
> | Sound | "when you hear a beep", "after the chime" |
> | Visual | "see the image", "as shown", "the highlighted area" |
>
> **Pass if:** Sensory cue is combined with programmatic identifier (e.g., "the Submit button on the right", "the round Search icon").
>
> **Fail if:** Sensory cue is the only way to identify the element (e.g., "click the button on the right" with no other identifier).
>
> Note: More abstract than 1.4.1 color checks; use judgment for context.

## Input Purpose
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 1.3.5 | Input fields have appropriate autocomplete attribute | `autocomplete-audit` **[CLI]** | autocomplete missing/incorrect for user data fields |

> **CLI Check:** The `autocomplete-audit` check matches field names/labels to expected autocomplete tokens and reports missing or invalid values.
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks autocomplete-audit`

## Language
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 3.1.1 | `<html lang>` is present and valid | DOM attribute | lang missing/invalid |
| 3.1.2 | Language of parts is identified | DOM + a11y tree text | Foreign language text without lang attribute |

> **3.1.2 Check:** Two-part check:
>
> 1. **axe-core `valid-lang` rule:** Detects invalid lang attribute values on elements
>
> 2. **Foreign text detection:** Scan page text for foreign language content (relative to page's primary language):
>    - Detect text in different scripts (e.g., Japanese on English page, Latin on Japanese page)
>    - Detect common foreign phrases/words
>    - Check if containing element has appropriate `lang` attribute
>
> **Pass if:** Foreign language text is wrapped with correct `lang` attribute (e.g., `<span lang="ja">日本語</span>`).
> **Fail if:** Foreign language text has no `lang` attribute on containing element.
>
> Note: Short borrowed words (e.g., "café", "sushi") may not need lang attribute; use judgment.

## Links/Buttons
| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 2.4.4 | Link accessible name is not empty and not ambiguous | a11y tree | Empty/unnamed or ambiguous links without context |
| 3.2.1 | No unexpected context change on focus (DOM diff) | DOM diff log | Focus triggers navigation or major update |
| 3.2.2 | No automatic submit/navigation on input (DOM diff) | DOM diff log | Input alone triggers submit/navigation |

> **2.4.4 Check:** Two-part automated check:
>
> 1. **Empty links:** axe-core `link-name` rule detects links with no accessible name
>
> 2. **Ambiguous links without context:** Detect links with generic text that are the only child (no surrounding context):
>    - Generic terms: "click here", "here", "more", "read more", "learn more", "details", "continue", "こちら", "詳細", "もっと見る", "続きを読む"
>    - Check if link is only-child in its parent (no sibling text providing context)
>    - Check if link has no `aria-describedby` or `aria-labelledby` providing context
>
> **Pass if:** Link has descriptive text, OR generic text but surrounded by contextual text/siblings.
>
> **Fail if:** Generic link text AND only-child AND no programmatic context.

## Cross-Page Checks

These checks require comparing data across all audit target pages. Run after collecting a11y tree snapshots and link data from all pages.

| Criterion | Automated check | Evidence | Fail rule |
|---|---|---|---|
| 2.4.5 | Multiple ways to locate pages | link graph + search/sitemap detection | Pages reachable only by single path with no search/sitemap |
| 3.2.3 | Primary navigation structure consistent across pages | a11y tree comparison | Navigation structure differs materially |
| 3.2.4 | Same function uses same role/name | a11y tree comparison | Name/role mismatch for same function |
| 3.2.6 | Help mechanisms appear consistently | a11y tree comparison | Help present on some pages only |

> **2.4.5 Check:** After collecting links from all audit target pages:
>
> 1. Build link graph: Extract all `<a href>` from each page
> 2. Check for multiple ways:
>    - **Search:** Detect search form (`role="search"`, `input[type="search"]`, or form with search-related labels)
>    - **Sitemap:** Detect sitemap page (link with "sitemap" in text/href) — recommend including sitemap in audit target pages
>    - **Cross-linking:** Each page should be linked from multiple other pages
> 3. Analyze reachability:
>    - Pages linked from only one source AND no search AND no sitemap → potential issue
>
> **Pass if:** Site has search OR sitemap OR pages are cross-linked from multiple sources.
> **Fail if:** Pages reachable only via single navigation path with no alternative way.

> **3.2.3 Check:** Compare the structure of repeated navigation components:
>
> 1. Extract landmark regions: `banner` (header), `navigation`, `contentinfo` (footer)
> 2. Compare child structure within each landmark across pages:
>    - Same relative order of nav items (by accessible name)
>    - Same roles for corresponding items
> 3. Allow for:
>    - Current page indicator differences (e.g., `aria-current="page"` on different items)
>    - Items omitted on some pages, as long as remaining items keep **same relative order**
>
> **Same relative order exception:** If Page 1 has "A, B, C, D" and Page 2 has "A, C, D" (B omitted), this is **Pass** because A→C→D order is preserved. But "A, D, C" would be **Fail**.
>
> **Pass if:** Relative order of shared navigation items is consistent across all pages.
> **Fail if:** Navigation items appear in different relative order across pages.

[English](./content-checks.md)

# コンテンツチェック

コンテンツ品質・提供形態に関する確認。テキスト/字幕/代替の有無と品質を人間が確認する。

## 非テキストコンテンツ
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.1.1 | 画像の代替テキストの品質 | 画像一覧 + 代替テキスト | 情報を伝える画像に代替テキストがない/空/説明不足 |

> **Note:** 自動チェックでは代替テキストの存在を確認します。コンテンツチェックでは、代替テキストが画像の内容と目的を適切に説明しているかを評価します。自動検出については [automated-checks.ja.md](./automated-checks.ja.md) を参照。

## マルチメディア
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.2.1 | 音声のみ/映像のみの代替 | 代替リンク | 代替がない |
| 1.2.2 | 収録済み動画の字幕 | スクショ | 字幕なし |
| 1.2.3 | 収録済み動画の代替（音声解説/テキスト） | 代替リンク | 代替なし |
| 1.2.4 | ライブ字幕の提供 | 画面キャプチャ | ライブ字幕なし |
| 1.2.5 | 音声解説の提供 | 画面キャプチャ | 音声解説なし |

## 感覚的特徴
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.3.3 | 「右側の赤いボタン」など感覚依存の指示 | 文面抜粋 | 感覚依存で代替なし |

## 音声
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.4.2 | 自動再生音声の停止/調整 | 操作ログ | 停止/調整不可 |

> **Tip:** `auto-play-detection` チェックでスクリーンショット比較による自動再生コンテンツの検出が可能です。音声の自動再生は聴覚確認が必要です。詳細は [interactive-checks.ja.md](./interactive-checks.ja.md#自動再生検出) を参照。
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks auto-play-detection`

## ナビゲーション
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.4.5 | 複数の到達手段（検索/サイトマップ等） | 画面キャプチャ | 単一手段のみ |

[日本語版 (Japanese)](./content-checks.ja.md)

# Content Checks

Checks that depend on content quality and availability. Validate presence and adequacy of alternatives such as captions and transcripts.

## Non-text Content
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.1.1 | Alt text quality for images | image list + alt text | Alt text missing, empty for informative images, or insufficient description |

> **Note:** Automated checks verify presence of alt text. Content review evaluates whether the alt text adequately describes the image content and purpose. See [automated-checks.md](./automated-checks.md) for automated alt text detection.

## Multimedia
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.2.1 | Alternatives for audio-only/video-only | links/notes | No alternative provided |
| 1.2.2 | Captions for prerecorded video | screenshot | No captions |
| 1.2.3 | Media alternative (audio description or text) | links/notes | No alternative |
| 1.2.4 | Live captions provided | capture | No live captions |
| 1.2.5 | Audio description provided | capture | No audio description |

## Sensory Characteristics
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.3.3 | Instructions not relying on sensory cues | excerpts | Sensory-only instructions without alternative |

## Audio
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.4.2 | Auto-play audio can be stopped/controlled | logs | No stop/controls |

> **Tip:** Use the `auto-play-detection` check to detect auto-playing visual content via screenshot comparison. Audio auto-play requires manual listening. See [interactive-checks.md](./interactive-checks.md#auto-play-detection) for details.
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks auto-play-detection`

## Navigation
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 2.4.5 | Multiple ways to reach content (search/site map) | capture | Only one way provided |

[English](./coverage-matrix.md)

# WCAG 2.2 A/AA カバレッジマトリクス

判定方法は「自動/インタラクティブ/手動/コンテンツ」を組み合わせて記載する。

> **Note:** **[CLI]** マークの基準は `a11y-audit` CLI で自動チェック可能です（チェック名は SKILL.ja.md の表を参照）。

## 1. 知覚可能
| 基準 | テスト方法 | 証跡 | 判定ルール |
|---|---|---|---|
| 1.1.1 | 自動+コンテンツ | a11y tree/画像一覧 | 情報画像が無名または代替不十分でFail |
| 1.2.1 | 自動+コンテンツ | DOMメディア検出 + トランスクリプトリンク | 代替がない場合Fail |
| 1.2.2 | 自動+コンテンツ | axe video-caption + track要素 | 字幕がない場合Fail |
| 1.2.3 | 自動+コンテンツ | track要素 + トランスクリプトリンク | 代替なしでFail |
| 1.2.4 | コンテンツ | 画面キャプチャ | ライブ字幕なしでFail |
| 1.2.5 | 自動+コンテンツ | track要素 | 音声解説なしでFail |
| 1.3.1 | 自動 | a11y tree断片 | セマンティクス欠落でFail |
| 1.3.2 | 自動 | a11y tree + DOM順 | 意味順序が崩れるとFail |
| 1.3.3 | 自動+コンテンツ | a11y treeテキスト + 文面抜粋 | 感覚依存のみでFail |
| 1.3.4 | 自動+手動 | `orientation-check` **[CLI]** + 画面キャプチャ | 特定方向で機能不可ならFail |
| 1.3.5 | 自動 | `autocomplete-audit` **[CLI]** | autocomplete不備でFail |
| 1.4.1 | 自動+手動 | a11y treeテキスト + スクショ | 色のみで識別ならFail |
| 1.4.2 | 手動 | 操作ログ | 停止/調整不可でFail |
| 1.4.3 | 自動 | axe color-contrast | AA未満でFail |
| 1.4.4 | 自動+手動 | `zoom-200-check` **[CLI]** + スクショ | 200%で欠落/重なりならFail |
| 1.4.5 | 手動+コンテンツ | スクショ | テキストが画像化ならFail |
| 1.4.10 | 自動+手動 | `reflow-check` **[CLI]** + スクショ | 横スクロール必須でFail |
| 1.4.11 | 自動 | axe非テキストコントラストルール | 非テキストコントラスト不足でFail |
| 1.4.12 | 自動+手動 | `text-spacing-check` **[CLI]** + スクショ | 文字欠落/重なりでFail |
| 1.4.13 | インタラクティブ | 動画/ログ | 解除/保持不可でFail |

## 2. 操作可能
| 基準 | テスト方法 | 証跡 | 判定ルール |
|---|---|---|---|
| 2.1.1 | インタラクティブ | 操作ログ | キーボード不可でFail |
| 2.1.2 | インタラクティブ | 操作ログ | トラップでFail |
| 2.1.4 | インタラクティブ | 操作ログ | 単一キー回避不可でFail |
| 2.2.1 | 自動+手動 | `time-limit-detector` **[CLI]** + 操作ログ | 延長/解除不可でFail |
| 2.2.2 | 自動+インタラクティブ | `auto-play-detection` **[CLI]** + 操作ログ | 停止/一時停止不可でFail |
| 2.3.1 | 手動 | 動画 | 点滅閾値超でFail |
| 2.4.1 | 自動 | a11y tree | 回避手段なしでFail |
| 2.4.2 | 自動 | `document.title` | タイトル空でFail |
| 2.4.3 | インタラクティブ | フォーカス順ログ | 視覚順と不一致でFail |
| 2.4.4 | 自動+コンテンツ | a11y tree + 文面抜粋 | 文脈内で不明瞭ならFail |
| 2.4.5 | 自動+コンテンツ | リンクグラフ + 検索/サイトマップ検出 | 複数手段なしでFail |
| 2.4.6 | 自動+コンテンツ | a11y tree/文面 | 見出し/ラベルが不明瞭でFail |
| 2.4.7 | インタラクティブ | スクショ | フォーカス不可視でFail |
| 2.4.11 | インタラクティブ | スクショ/計測 | 最低要件未満でFail |
| 2.4.12 | インタラクティブ | スクショ | フォーカスが隠れるとFail |
| 2.5.1 | インタラクティブ | 操作ログ | 複雑ジェスチャ必須でFail |
| 2.5.2 | インタラクティブ | 操作ログ | 誤作動/キャンセル不可でFail |
| 2.5.3 | 自動 | a11y name比較 | ラベル文字列不一致でFail |
| 2.5.4 | インタラクティブ | 操作ログ | 動作検知のみでFail |
| 2.5.7 | インタラクティブ | 操作ログ | ドラッグ必須でFail |
| 2.5.8 | 自動 | `target-size-check` **[CLI]** | 最低サイズ未満でFail |

## 3. 理解可能
| 基準 | テスト方法 | 証跡 | 判定ルール |
|---|---|---|---|
| 3.1.1 | 自動 | DOM属性 | lang未設定でFail |
| 3.1.2 | 自動+コンテンツ | axe valid-lang + テキスト分析 | 部分言語未指定でFail |
| 3.2.1 | 自動+インタラクティブ | `focus-indicator-check` **[CLI]** + DOM差分 | フォーカスで遷移/大更新でFail |
| 3.2.2 | インタラクティブ | DOM差分 | 入力のみで送信/遷移でFail |
| 3.2.3 | 自動 | 全ページa11y tree比較 | 一貫性欠如でFail |
| 3.2.4 | 自動 | 全ページa11y tree比較 | 同一機能の識別が不一致でFail |
| 3.2.6 | 自動 | 全ページa11y tree比較 | ヘルプ手段が不一致でFail |
| 3.3.1 | インタラクティブ | スクショ | エラー識別なしでFail |
| 3.3.2 | 自動+コンテンツ | a11y tree/文面 | ラベル/説明不足でFail |
| 3.3.3 | インタラクティブ | スクショ | 修正提案なしでFail |
| 3.3.4 | インタラクティブ | 操作ログ | 取消/確認不可でFail |
| 3.3.7 | 手動 | 操作ログ | 冗長入力要求でFail |
| 3.3.8 | インタラクティブ | 画面キャプチャ | 認知テストのみでFail |

## 4. 堅牢
| 基準 | テスト方法 | 証跡 | 判定ルール |
|---|---|---|---|
| 4.1.1 | 自動 | HTML検証ログ | 構文エラーが支援技術を阻害する場合Fail |
| 4.1.2 | 自動 | a11y tree | 名前/ロール/値が取得不可でFail |
| 4.1.3 | 自動+インタラクティブ | a11y tree/ログ | 状態メッセージが露出しない場合Fail |

## 利用可能なCLIチェック

以下の基準は `a11y-audit` CLI で自動チェック可能です（使用方法は SKILL.ja.md を参照）:

| 基準 | チェック名 | 出力 |
|---|---|---|
| 複数 | `axe-audit` | `axe-result.json` |
| 1.3.4 | `orientation-check` | `orientation-result.json` |
| 1.3.5 | `autocomplete-audit` | `autocomplete-result.json` |
| 1.4.2, 2.2.2 | `auto-play-detection` | `auto-play-screenshots/` |
| 1.4.4 | `zoom-200-check` | `zoom-200-result.json` |
| 1.4.10 | `reflow-check` | `reflow-result.json` |
| 1.4.12 | `text-spacing-check` | `text-spacing-result.json` |
| 2.2.1 | `time-limit-detector` | `time-limit-result.json` |
| 2.4.7, 2.4.12, 3.2.1 | `focus-indicator-check` | `focus-indicator-result.json`, `focus-indicators.png` |
| 2.5.5, 2.5.8 | `target-size-check` | `target-size-result.json`, `target-size-screenshot.png` |

[日本語版 (Japanese)](./coverage-matrix.ja.md)

# WCAG 2.2 A/AA Coverage Matrix

Methods are labeled as Automated/Interactive/Manual/Content and can be combined.

> **Note:** Criteria marked with **[CLI]** can be automatically checked via the `a11y-audit` CLI. See the check names in SKILL.md for reference.

## 1. Perceivable
| Criterion | Test Method | Evidence | Judgment Rule |
|---|---|---|---|
| 1.1.1 | Automated + Content | a11y tree/image list | Fail if informative images are unnamed or insufficient |
| 1.2.1 | Automated + Content | DOM media detection + transcript links | Fail if no alternative |
| 1.2.2 | Automated + Content | axe video-caption + track elements | Fail if captions missing |
| 1.2.3 | Automated + Content | track elements + transcript links | Fail if no media alternative |
| 1.2.4 | Content | capture | Fail if live captions missing |
| 1.2.5 | Automated + Content | track elements | Fail if audio description missing |
| 1.3.1 | Automated | a11y tree snippet | Fail on missing semantics |
| 1.3.2 | Automated | a11y tree + DOM order | Fail if meaningful order breaks |
| 1.3.3 | Automated + Content | a11y tree text + excerpts | Fail on sensory-only instructions |
| 1.3.4 | Automated + Manual | `orientation-check` **[CLI]** + captures | Fail if one orientation blocks function |
| 1.3.5 | Automated | `autocomplete-audit` **[CLI]** | Fail on incorrect/missing autocomplete |
| 1.4.1 | Automated + Manual | a11y tree text + screenshots | Fail if color-only cue |
| 1.4.2 | Manual | logs | Fail if audio cannot be paused/stopped |
| 1.4.3 | Automated | axe color-contrast | Fail below AA |
| 1.4.4 | Automated + Manual | `zoom-200-check` **[CLI]** + screenshots | Fail if loss/overlap at 200% |
| 1.4.5 | Manual + Content | screenshots | Fail if text is image-based |
| 1.4.10 | Automated + Manual | `reflow-check` **[CLI]** + screenshots | Fail if horizontal scroll required |
| 1.4.11 | Automated | axe non-text contrast rules | Fail if non-text contrast insufficient |
| 1.4.12 | Automated + Manual | `text-spacing-check` **[CLI]** + screenshots | Fail on text clipping/overlap |
| 1.4.13 | Interactive | video/logs | Fail if hover/focus content cannot be dismissed/retained |

## 2. Operable
| Criterion | Test Method | Evidence | Judgment Rule |
|---|---|---|---|
| 2.1.1 | Interactive | logs | Fail if keyboard-only not possible |
| 2.1.2 | Interactive | logs | Fail on keyboard trap |
| 2.1.4 | Interactive | logs | Fail if single-key shortcuts cannot be mitigated |
| 2.2.1 | Automated + Manual | `time-limit-detector` **[CLI]** + logs | Fail if time limits cannot be extended/disabled |
| 2.2.2 | Automated + Interactive | `auto-play-detection` **[CLI]** + logs | Fail if moving content cannot be paused/stopped |
| 2.3.1 | Manual | video | Fail if flashing exceeds threshold |
| 2.4.1 | Automated | a11y tree | Fail if no bypass mechanism |
| 2.4.2 | Automated | `document.title` | Fail if title empty |
| 2.4.3 | Interactive | focus order log | Fail if order deviates from visual |
| 2.4.4 | Automated + Content | a11y tree + excerpts | Fail if link purpose unclear in context |
| 2.4.5 | Automated + Content | link graph + search/sitemap detection | Fail if only one way provided |
| 2.4.6 | Automated + Content | a11y tree/excerpts | Fail if headings/labels are unclear |
| 2.4.7 | Interactive | screenshots | Fail if focus not visible |
| 2.4.11 | Interactive | screenshots/measurement | Fail if focus appearance below minimum |
| 2.4.12 | Interactive | screenshots | Fail if focus is obscured |
| 2.5.1 | Interactive | logs | Fail if complex gestures required |
| 2.5.2 | Interactive | logs | Fail if cancellation unavailable |
| 2.5.3 | Automated | a11y name diff | Fail if label text not in accessible name |
| 2.5.4 | Interactive | logs | Fail if motion-only activation |
| 2.5.7 | Interactive | logs | Fail if dragging required |
| 2.5.8 | Automated | `target-size-check` **[CLI]** | Fail below minimum target size |

## 3. Understandable
| Criterion | Test Method | Evidence | Judgment Rule |
|---|---|---|---|
| 3.1.1 | Automated | DOM attribute | Fail if lang missing |
| 3.1.2 | Automated + Content | axe valid-lang + text analysis | Fail if language of parts not identified |
| 3.2.1 | Automated + Interactive | `focus-indicator-check` **[CLI]** + DOM diff | Fail if focus triggers navigation/major update |
| 3.2.2 | Interactive | DOM diff | Fail if input triggers submit/navigation |
| 3.2.3 | Automated | a11y tree comparison across pages | Fail if navigation inconsistent |
| 3.2.4 | Automated | a11y tree comparison across pages | Fail if same function identified differently |
| 3.2.6 | Automated | a11y tree comparison across pages | Fail if help mechanism inconsistent |
| 3.3.1 | Interactive | screenshots | Fail if errors not identified |
| 3.3.2 | Automated + Content | a11y tree/excerpts | Fail if labels/instructions missing |
| 3.3.3 | Interactive | screenshots | Fail if no correction suggestions |
| 3.3.4 | Interactive | logs | Fail if no confirm/reversal for critical actions |
| 3.3.7 | Manual | logs | Fail if redundant entry required |
| 3.3.8 | Interactive | captures | Fail if authentication relies on cognitive test only |

## 4. Robust
| Criterion | Test Method | Evidence | Judgment Rule |
|---|---|---|---|
| 4.1.1 | Automated | HTML validation logs | Fail if parsing errors block AT |
| 4.1.2 | Automated | a11y tree | Fail if name/role/value not exposed |
| 4.1.3 | Automated + Interactive | a11y tree/logs | Fail if status messages not exposed |

## Available CLI Checks

The following criteria can be automatically checked via the `a11y-audit` CLI (see SKILL.md for usage):

| Criterion | Check name | Output |
|---|---|---|
| Multiple | `axe-audit` | `axe-result.json` |
| 1.3.4 | `orientation-check` | `orientation-result.json` |
| 1.3.5 | `autocomplete-audit` | `autocomplete-result.json` |
| 1.4.2, 2.2.2 | `auto-play-detection` | `auto-play-screenshots/` |
| 1.4.4 | `zoom-200-check` | `zoom-200-result.json` |
| 1.4.10 | `reflow-check` | `reflow-result.json` |
| 1.4.12 | `text-spacing-check` | `text-spacing-result.json` |
| 2.2.1 | `time-limit-detector` | `time-limit-result.json` |
| 2.4.7, 2.4.12, 3.2.1 | `focus-indicator-check` | `focus-indicator-result.json`, `focus-indicators.png` |
| 2.5.5, 2.5.8 | `target-size-check` | `target-size-result.json`, `target-size-screenshot.png` |

[English](./interactive-checks.md)

# インタラクティブチェック

ユーザー操作をPlaywrightで再現して判定する項目。キーボード/ポインター/エラー処理など、状態遷移が絡む基準を扱います。

## 共通手順
- 主要フローをキーボードで通過（Tab/Shift+Tab/Enter/Space/矢印）
- ポインター操作を模擬（click/drag/hover）
- DOM差分とa11y treeで状態変化を記録

## キーボード
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.1.1 | すべての機能をキーボードのみで実行 | 操作ログ/動画 | クリック専用操作がある |
| 2.1.2 | すべてのフォーカスを抜けられる | 操作ログ | フォーカストラップがある |
| 2.1.4 | 文字キー単独ショートカットの無効化/再割当/フォーカス限定 | 操作ログ | ショートカットが誤発火し回避不可 |

## フォーカス
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.4.3 | フォーカス順序が視覚順と一致 | フォーカス順ログ | 大きく順序が崩れる |
| 2.4.7 | フォーカス可視化を確認 | スクショ/動画 | フォーカスが視認不可 |
| 2.4.11 | フォーカス表示が最低要件を満たす | スクショ/計測 | コントラスト/太さが不足 |
| 2.4.12 | フォーカスが他のコンテンツに隠されない | スクショ | 固定ヘッダー/フッター/モーダルでフォーカスが隠れる |

### `focus-indicator-check` CLIチェック

`focus-indicator-check` チェックを使用して、フォーカスインジケーターの有無、フォーカス遮蔽、フォーカス時のコンテキスト変更を自動検出できます。

**WCAG カバレッジ:**
- **2.4.7 Focus Visible** - フォーカスインジケーターがない要素を検出
- **2.4.12 Focus Not Obscured (Minimum)** - fixed/sticky要素によるフォーカス遮蔽を検出
- **3.2.1 On Focus** - フォーカス時のナビゲーション/コンテキスト変更を検出

**機能:**
- ページ内のフォーカス可能な要素を自動検出
- Tab キーで各要素にフォーカスを移動し、スタイル変化をキャプチャ
- フォーカス時のスタイル変化を検出（outline, box-shadow, background-color, border, transform 等）
- フォーカススタイルがない要素を赤枠と警告ラベルでマーク
- **fixed/sticky要素によるフォーカス遮蔽を検出（2.4.12）** - `elementFromPoint()` とz-indexフォールバックを使用
- **フォーカスによるナビゲーションを検出（3.2.1違反）**
- ナビゲーション発生時は元のページに戻ってスクリーンショットを撮影
- 全ページスクリーンショットで問題箇所を視覚化

**使用方法:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check
```

**出力:**
- `focus-indicator-result.json` - 完全な結果:
  - `issues` - フォーカススタイルがない要素（2.4.7）
  - `focusObscuredIssues` - fixed/sticky要素によるフォーカス遮蔽（2.4.12）
  - `onFocusViolations` - フォーカス時のコンテキスト変更（3.2.1）
  - `interrupted` - ナビゲーションによりテストが中断されたかどうか
  - `allElements` - テストした全要素とフォーカススタイルの差分
- `focus-indicators.png` - 問題のある要素に警告ラベルを付けた全ページスクリーンショット（`--screenshot` フラグで有効化）

**3.2.1 検出:**
要素のフォーカスイベントがナビゲーションを引き起こした場合:
1. 違反が記録される（要素セレクター、遷移元/先URL）
2. テストは元のページに戻る
3. 元のページでスクリーンショットを撮影
4. テストは中断としてマークされる

## ポインター
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.5.7 | ドラッグ以外の操作手段を提供 | 操作ログ | ドラッグ必須で代替なし |
| 2.5.8 | ターゲットサイズを測定 | スクショ/計測 | 最低サイズを満たさない |

### `target-size-check` CLIチェック

`target-size-check` チェックを使用して、WCAG 2.5.8（AA: 24px）および 2.5.5（AAA: 44px）に基づくタップ/クリックターゲットのサイズを自動測定できます。

**機能:**
- すべてのインタラクティブ要素を検出（リンク、ボタン、入力、ARIAウィジェット）
- `getBoundingClientRect()` でバウンディングボックスサイズを測定
- Playwright の `ariaSnapshot()` API でアクセシブル名を取得
- WCAG 2.5.8 例外を判定: inline, redundant, ua-control, spacing
- AA（24px）と AAA（44px）の両レベルで問題を報告
- 色分けハイライト付きの全ページスクリーンショットを生成

**使用方法:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks target-size-check
```

**出力:**
- `target-size-result.json` - すべてのターゲットと問題を含む完全な結果
- `target-size-screenshot.png` - ハイライト付き全ページスクリーンショット:
  - **緑 (PASS)**: 44px以上（AA合格、AAA合格）
  - **オレンジ (AA Pass)**: 24-43px（AA合格、AAA不合格）
  - **赤 (AA Fail)**: 24px未満（AA不合格、AAA不合格）
  - **青 (Exception)**: 例外の可能性あり（手動レビュー必要）

**検出される例外:**
| 例外 | 検出方法 |
|---|---|
| inline | 段落/リスト内のリンクで周囲テキストが10文字以上 |
| redundant | 同じhrefを持つ別のターゲットがサイズ要件を満たしている |
| ua-control | ネイティブフォームコントロール（checkbox, radio, select）でデフォルト外観 |
| spacing | 24px以内に隣接ターゲットがない |
| essential | 自動検出不可（手動レビュー対象としてマーク） |

**制限事項:**
- essential 例外は手動判断が必要
- クリック領域を拡張するCSS疑似要素は完全に検出できない
- CSS transform の効果は測定に含まれる（getBoundingClientRect は変換後のサイズを返す）

**手動確認が必要な項目:**
- essential 例外の確認（例: 地図のピン、ゲームコントロール）
- spacing 例外の実際のインタラクションでの検証
- インタラクション後にのみ表示されるターゲット（ドロップダウン、モーダル）

## ホバー/フォーカス表示
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.4.13 | ホバー/フォーカスで出るコンテンツを閉じ/保持可能 | 操作ログ/動画 | 逃げ場なし、意図せず消える |

## エラー処理
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 3.3.1 | エラー入力時に識別が提示 | スクショ | エラー箇所が不明 |
| 3.3.3 | 修正提案が表示 | スクショ | 具体的な修正提案なし |
| 3.3.4 | 重要操作の再確認/取消が可能 | 操作ログ | 取消/確認がない |

### 3.3.1 エラーの特定チェック

**概要:** 入力エラーが自動的に検出された場合、エラーとなっている項目がテキストで識別され、そのエラーがユーザーに説明される必要がある。

> **Note:** 3.3.1をテストする際、以下も同時に確認:
> - **3.3.2 ラベルまたは説明** — エラーを発生させる前に、フォーム入力にアクセシブル名と説明があるかチェック。3.3.2の詳細は [automated-checks.ja.md](./automated-checks.ja.md) を参照。
> - **3.3.3 エラー修正の提案** — エラーメッセージに修正方法の提案があるかチェック（例:「name@example.com のような有効なメールアドレスを入力してください」）。

**テスト手順:**

1. **ページ内のフォームを検出:**
   - `<form>` 要素を検出
   - 入力フィールド（`input`, `select`, `textarea`）を検出
   - 必須フィールドを確認（`required` 属性、`aria-required="true"`、または視覚的インジケーター）

2. **意図的にエラーを発生させる:**

   | エラータイプ | 方法 |
   |------------|--------|
   | 必須フィールドの空送信 | フィールドを空にしてフォームを送信 |
   | 無効なメールアドレス | メールフィールドに "invalid-email" を入力 |
   | 無効な日付 | 日付フィールドに "not-a-date" を入力 |
   | 無効な電話番号 | 電話番号フィールドに "abc" を入力 |
   | 範囲外の値 | min/max 制限外の値を入力 |
   | パターン不一致 | `pattern` 属性に合わない値を入力 |

3. **エラーの識別を確認:**

   | チェック項目 | Pass条件 | Fail条件 |
   |-------|---------------|----------------|
   | エラーメッセージの存在 | エラーを説明するテキストメッセージがある | メッセージがない、または視覚的表現のみ（色/アイコン） |
   | エラー箇所の明示 | どのフィールドがエラーかテキストから明確 | 色や位置のみに依存 |
   | プログラム的関連付け | `aria-describedby`, `aria-errormessage`, `aria-invalid` がある | エラーとフィールド間のプログラム的なリンクがない |

4. **a11y tree での確認:**
   - エラーフィールドに `aria-invalid="true"` があるか確認
   - `aria-describedby` または `aria-errormessage` がエラーテキストを指しているか確認
   - エラーメッセージがa11y treeに公開されているか確認（ATから隠されていない）

**Playwright テストフローの例:**
```typescript
// 1. フォームと必須入力を検出
const form = page.locator('form').first();
const requiredInput = form.locator('input[required], input[aria-required="true"]').first();

// 2. 入力をクリアして送信しエラーを発生
await requiredInput.fill('');
await form.locator('button[type="submit"], input[type="submit"]').click();

// 3. エラー表示を確認
const a11ySnapshot = await page.accessibility.snapshot();
// スナップショットでaria-invalid, aria-describedbyを確認
// エラーメッセージテキストが公開されているか確認
```

**Passの条件:**
- エラーメッセージがテキストで表示される
- エラーメッセージがどのフィールドにエラーがあるか識別している
- エラーがフィールドとプログラム的に関連付けられている（推奨）

**Failの条件:**
- エラーメッセージが表示されない
- エラーが色のみで示される（テキスト説明なしの赤い枠/文字）
- エラーメッセージがどのフィールドのエラーか示していない
- エラーメッセージがATで認識できない（例: 視覚的アイコンのみ）

## 認証
| 基準 | 操作 | 証跡 | Fail条件 |
|---|---|---|---|
| 3.3.8 | 認証で認知負荷のみを要求しない | 画面キャプチャ | 認知テストのみで代替なし |

## 自動再生検出

対象基準:
- **1.4.2** (音声の制御): 自動再生音声を停止/制御できる
- **2.2.2** (一時停止、停止、非表示): 自動更新コンテンツを一時停止/停止できる

### `auto-play-detection` CLIチェック

`auto-play-detection` チェックを使用して、ピクセルレベルのスクリーンショット比較による自動再生コンテンツを検出できます。

**機能:**
- 2秒間隔でスクリーンショットを撮影（0秒, 2秒, 4秒, 6秒）
- ピクセルレベルの差分検出（pixelmatch）で正確な比較
- 5秒以上コンテンツが継続するかを検出（WCAG 2.2.2 の閾値）
- ページ内の一時停止/停止コントロールを自動検出
- 一時停止コントロールをクリックして実際に機能するか検証
- 変化箇所をハイライトした差分画像を生成
- アクセシビリティ推奨事項を含むレポートを出力

**使用方法:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks auto-play-detection
```

**出力:**
- `auto-play-screenshots/` - 以下を含むディレクトリ:
  - `screenshot-0s.png` ～ `screenshot-6s.png` - 比較用スクリーンショット
  - `diff-*-vs-*.png` - 変化したピクセルを示す差分画像
  - `detection-result.json` - 完全な検出結果:
    - 各間隔の変化率
    - 5秒以内に停止するか
    - 検出された一時停止コントロール（アクセシビリティ情報付き）
    - 一時停止コントロールの検証結果

**一時停止コントロール検出:**
スクリプトは以下の方法で一時停止/停止コントロールを自動検索します:
- 一時停止関連キーワードを含むアクセシブル名（英語/日本語対応）
- クラス名パターン（pause, play, stop, toggle, switch, control）
- コンテキスト認識（カルーセル要素近くのコントロールを優先）

**一時停止コントロール検証:**
自動再生が検出され、5秒以上継続する場合:
1. 一時停止コントロールが見つかった → クリック実行
2. クリック前後でスクリーンショットを撮影
3. 比較してアニメーションが実際に停止したか確認
4. コントロールが機能するかどうかをレポート

**制限事項:**
- 視覚的変化のみ検出（カルーセル、アニメーション、動画再生）
- 音声の自動再生は手動確認が必要（聴覚確認）
- 0.1%未満の小さなアニメーションは検出されない場合あり

**手動確認が必要な項目:**
- 一時停止/停止コントロールがキーボードでアクセス可能か確認
- 音声の自動再生を聴覚で確認（スクリーンショットでは検出不可）
- 一時停止コントロール検証が失敗した場合、手動でコントロール機能を確認

[日本語版 (Japanese)](./interactive-checks.ja.md)

# Interactive Checks

Items verified by simulating user interaction with Playwright. Focus on stateful criteria like keyboard, pointer, and error handling.

## Common Procedure
- Traverse primary flows with keyboard only (Tab/Shift+Tab/Enter/Space/Arrows)
- Simulate pointer actions (click/drag/hover)
- Capture DOM diffs and a11y tree changes

## Keyboard
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 2.1.1 | Complete all functions with keyboard only | logs/video | Any click-only function exists |
| 2.1.2 | Escape all focus areas | logs | Keyboard trap exists |
| 2.1.4 | Single-key shortcuts can be disabled/remapped or are focus-limited | logs | Shortcut triggers unexpectedly with no escape |

## Focus
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 2.4.3 | Focus order matches visual order | focus order log | Order deviates materially |
| 2.4.7 | Focus indicator visible | screenshots/video | Focus not visible |
| 2.4.11 | Focus appearance meets minimum requirements | screenshots/measurement | Contrast or thickness insufficient |
| 2.4.12 | Focus not obscured by other content | screenshots | Focus indicator hidden by sticky headers/footers/modals |

### `focus-indicator-check` CLI Check

Use the `focus-indicator-check` check to automatically detect focus indicator presence, focus obscured issues, and focus-triggered context changes.

**WCAG Coverage:**
- **2.4.7 Focus Visible** - Detects elements without visible focus indicators
- **2.4.12 Focus Not Obscured (Minimum)** - Detects focus indicators hidden by fixed/sticky elements
- **3.2.1 On Focus** - Detects navigation/context changes triggered by focus

**Features:**
- Detects all focusable elements on the page
- Tabs through each element and captures style changes on focus
- Checks for outline, box-shadow, background-color changes
- Reports elements without visible focus indicators with warning labels
- **Detects focus obscured by fixed/sticky elements (2.4.12)** using `elementFromPoint()` with z-index fallback
- **Detects navigation caused by focus (3.2.1 violation)**
- If navigation occurs, goes back and takes screenshot on original page
- Takes a full-page screenshot highlighting problematic elements

**Usage:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check
```

**Output:**
- `focus-indicator-result.json` - Full results including:
  - `issues` - Elements without focus styles (2.4.7)
  - `focusObscuredIssues` - Focus obscured by fixed/sticky elements (2.4.12)
  - `onFocusViolations` - Focus-triggered context changes (3.2.1)
  - `interrupted` - Whether test was interrupted by navigation
  - `allElements` - All tested elements with their focus style diffs
- `focus-indicators.png` - Full-page screenshot with warning labels on problematic elements (use `--screenshot` flag)

**3.2.1 Detection:**
When an element's focus event triggers navigation:
1. Violation is recorded with element selector, from/to URLs
2. Test navigates back to original page
3. Screenshot is taken on the original page
4. Test is marked as interrupted

## Pointer
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 2.5.7 | Provide alternative to dragging | logs | Dragging is required with no alternative |
| 2.5.8 | Measure target size | screenshots/measurement | Minimum target size not met |

### `target-size-check` CLI Check

Use the `target-size-check` check to automatically measure tap/click target sizes per WCAG 2.5.8 (AA: 24px) and 2.5.5 (AAA: 44px).

**Features:**
- Detects all interactive elements (links, buttons, inputs, ARIA widgets)
- Measures bounding box dimensions via `getBoundingClientRect()`
- Retrieves accessible names via Playwright's `ariaSnapshot()` API
- Checks WCAG 2.5.8 exceptions: inline, redundant, ua-control, spacing
- Reports issues at both AA (24px) and AAA (44px) levels
- Takes full-page screenshot with color-coded highlights

**Usage:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks target-size-check
```

**Output:**
- `target-size-result.json` - Full results with all targets and issues
- `target-size-screenshot.png` - Full-page screenshot with highlights:
  - **Green (PASS)**: >= 44px (AA Pass, AAA Pass)
  - **Orange (AA Pass)**: 24-43px (AA Pass, AAA Fail)
  - **Red (AA Fail)**: < 24px (AA Fail, AAA Fail)
  - **Blue (Exception)**: Possible exception (manual review needed)

**Exceptions Detected:**
| Exception | Detection Method |
|---|---|
| inline | Link within paragraph/list with surrounding text >= 10 chars |
| redundant | Same href exists with another target meeting size requirement |
| ua-control | Native form control (checkbox, radio, select) with default appearance |
| spacing | No adjacent targets within 24px |
| essential | Cannot auto-detect (marked for manual review) |

**Limitations:**
- Essential exception requires manual judgment
- CSS pseudo-elements expanding click area not fully detectable
- CSS transform effects are included in measurements (getBoundingClientRect returns transformed size)

**Manual Verification Required:**
- Confirm essential exceptions (e.g., map pins, game controls)
- Verify spacing exception with actual interaction testing
- Check targets appearing only after interaction (dropdowns, modals)

## Hover/Focus Content
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 1.4.13 | Hover/focus content can be dismissed/hovered/persistent | logs/video | Cannot dismiss or content disappears unexpectedly |

## Error Handling
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 3.3.1 | Trigger error and confirm identification | screenshot | Error location not indicated |
| 3.3.3 | Provide correction suggestions | screenshot | No specific suggestions |
| 3.3.4 | Allow confirm/reverse for critical actions | logs | No confirm/reversal mechanism |

### 3.3.1 Error Identification Check

**Overview:** When input errors are automatically detected, the item that is in error must be identified in text and described to the user.

> **Note:** When testing 3.3.1, also verify:
> - **3.3.2 Labels or Instructions** — check that form inputs have accessible names and instructions before triggering errors. See [automated-checks.md](./automated-checks.md) for 3.3.2 details.
> - **3.3.3 Error Suggestion** — check that error messages include suggestions for correcting the error (e.g., "Enter a valid email address like name@example.com").

**Test Procedure:**

1. **Find forms on the page:**
   - Detect `<form>` elements
   - Detect input fields (`input`, `select`, `textarea`)
   - Note required fields (`required` attribute, `aria-required="true"`, or visual indicators)

2. **Trigger errors intentionally:**

   | Error Type | Method |
   |------------|--------|
   | Empty required field | Clear field value and submit form |
   | Invalid email | Enter "invalid-email" in email field |
   | Invalid date | Enter "not-a-date" in date field |
   | Invalid phone | Enter "abc" in phone field |
   | Out of range | Enter value outside min/max limits |
   | Pattern mismatch | Enter value not matching `pattern` attribute |

3. **Check error identification:**

   | Check | Pass Condition | Fail Condition |
   |-------|---------------|----------------|
   | Error message exists | Text message describes the error | No message or message is only visual (color/icon) |
   | Error location indicated | Which field has error is clear from text | Only relies on color or position |
   | Programmatic association | `aria-describedby`, `aria-errormessage`, or `aria-invalid` present | No programmatic link between error and field |

4. **a11y tree verification:**
   - Check `aria-invalid="true"` on error fields
   - Check `aria-describedby` or `aria-errormessage` pointing to error text
   - Verify error message is exposed in a11y tree (not hidden from AT)

**Example Playwright test flow:**
```typescript
// 1. Find form and required input
const form = page.locator('form').first();
const requiredInput = form.locator('input[required], input[aria-required="true"]').first();

// 2. Clear input and submit to trigger error
await requiredInput.fill('');
await form.locator('button[type="submit"], input[type="submit"]').click();

// 3. Check for error indication
const a11ySnapshot = await page.accessibility.snapshot();
// Look for aria-invalid, aria-describedby in snapshot
// Check if error message text is exposed
```

**Pass if:**
- Error message is displayed in text
- Error message identifies which field has the error
- Error is programmatically associated with the field (preferred)

**Fail if:**
- No error message appears
- Error is indicated only by color (red border/text without text explanation)
- Error message doesn't indicate which field is in error
- Error message is not perceivable by AT (e.g., only visual icon)

## Authentication
| Criterion | Action | Evidence | Fail rule |
|---|---|---|---|
| 3.3.8 | Authentication does not rely on cognitive tests alone | captures | Cognitive-only requirement with no alternative |

## Auto-play Detection

Supports criteria:
- **1.4.2** (Audio Control): Auto-play audio can be stopped/controlled
- **2.2.2** (Pause, Stop, Hide): Auto-updating content can be paused/stopped

### `auto-play-detection` CLI Check

Use the `auto-play-detection` check to detect auto-playing content via pixel-level screenshot comparison.

**Features:**
- Takes screenshots at 2-second intervals (0s, 2s, 4s, 6s)
- Uses pixel-level diff detection (pixelmatch) for accurate comparison
- Detects if content continues beyond 5 seconds (WCAG 2.2.2 threshold)
- Automatically detects pause/stop controls on the page
- Verifies if pause controls actually work by clicking and re-comparing
- Generates visual diff images highlighting changed areas
- Reports findings with accessibility recommendations

**Usage:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks auto-play-detection
```

**Output:**
- `auto-play-screenshots/` - Directory containing:
  - `screenshot-0s.png` through `screenshot-6s.png` - Comparison screenshots
  - `diff-*-vs-*.png` - Visual diff images showing changed pixels
  - `detection-result.json` - Full detection results including:
    - Change percentages between intervals
    - Whether content stops within 5 seconds
    - Detected pause controls with accessibility info
    - Pause control verification results

**Pause Control Detection:**
The script automatically searches for pause/stop controls by:
- Accessible names containing pause-related keywords (EN/JP)
- Class name patterns (pause, play, stop, toggle, switch, control)
- Context awareness (prioritizes controls near carousel elements)

**Pause Control Verification:**
When auto-play is detected and continues beyond 5 seconds:
1. If pause control found → clicks the control
2. Takes screenshots before and after clicking
3. Compares to verify animation actually stopped
4. Reports whether the control works

**Limitations:**
- Detects visual changes only (carousels, animations, video playback)
- Audio auto-play requires manual verification (listening)
- Small animations below 0.1% threshold may not be detected

**Manual Verification Required:**
- Verify pause/stop controls are keyboard accessible
- Check for audio auto-play (requires listening)
- If pause control verification fails, manually check control functionality

[English](./manual-checks.md)

# 手動チェック

人間の判断が必要な項目。視覚評価や文脈理解を含むため、証跡はスクリーンショット/動画/注記を必ず残す。

## 色・コントラスト

> **Note:** 1.4.1（色の使用）、1.4.3（テキストコントラスト）、1.4.11（非テキストコントラスト）は [automated-checks.ja.md](./automated-checks.ja.md) でカバーされます。1.4.1はエージェントがアクセシブルテキスト内の色名参照を分析します。グラフや図表が色のみで区別されている場合は、目視確認が必要です。

## テキスト/レイアウト
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.4.4 | 200%拡大で情報欠落なし | スクショ | コンテンツ欠落/重なり |
| 1.4.5 | 画像内文字の回避 | スクショ | テキストが画像化されている |
| 1.4.10 | リフロー時の横スクロール不要 | スクショ | 320px相当で横スクロール必須 |
| 1.4.12 | テキスト間隔変更で崩れない | スクショ | 文字が欠落/重なり |

> **CLIチェック:**
> - `zoom-200-check` - 200%ズーム時のコンテンツ欠落/クリッピングを検出（1.4.4）
> - `reflow-check` - 320pxビューポートでの水平スクロールを検出（1.4.10）
> - `text-spacing-check` - WCAGテキストスペーシング変更後のクリッピングを検出（1.4.12）
>
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks zoom-200-check,reflow-check,text-spacing-check`

## タイミング
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.2.1 | 時間制限の延長/解除 | 操作ログ | 延長/解除が不可 |
| 2.2.2 | 自動更新/アニメの停止 | 操作ログ | 停止/一時停止不可 |

> **CLIチェック:**
> - `time-limit-detector` - meta refresh、setTimeout/setInterval、カウントダウン表示を検出（2.2.1）
> - `auto-play-detection` - スクリーンショット比較による自動再生コンテンツの検出（2.2.2）。詳細は [interactive-checks.ja.md](./interactive-checks.ja.md#自動再生検出) を参照。
>
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks time-limit-detector,auto-play-detection`

## フラッシュ
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 2.3.1 | 3回/秒超の点滅なし | 動画 | 閾値超の点滅 |

## 画面方向
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 1.3.4 | 縦横どちらでも利用可能 | スクショ | 特定方向で機能不可 |

> **CLIチェック:** `orientation-check` - 画面の向き制限メッセージと縦横でのコンテンツ表示差異を検出。
>
> 実行: `npx -y @a11y-skills/audit --url "<url>" --checks orientation-check`

## 冗長入力
| 基準 | 確認内容 | 証跡 | Fail条件 |
|---|---|---|---|
| 3.3.7 | 既出情報の再入力を要求しない | 操作ログ | 同一情報の再入力を要求 |

[日本語版 (Japanese)](./manual-checks.ja.md)

# Manual Checks

Items requiring human judgment. Use screenshots/video/notes as evidence for visual or contextual decisions.

## Color/Contrast

> **Note:** 1.4.1 (Use of Color), 1.4.3 (Text Contrast), and 1.4.11 (Non-text Contrast) are covered in [automated-checks.md](./automated-checks.md). For 1.4.1, the agent analyzes accessible text for color references. For charts/graphs relying solely on color differentiation, manual visual inspection is still needed.

## Text/Layout
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.4.4 | No loss at 200% zoom | screenshot | Loss/overlap |
| 1.4.5 | Avoid text in images | screenshot | Text rendered as image |
| 1.4.10 | Reflow without horizontal scroll | screenshot | Horizontal scroll at 320px equivalent |
| 1.4.12 | Text spacing changes do not break layout | screenshot | Text clipping/overlap |

> **CLI Checks:**
> - `zoom-200-check` - Detects content loss/clipping at 200% zoom (1.4.4)
> - `reflow-check` - Detects horizontal scroll at 320px viewport (1.4.10)
> - `text-spacing-check` - Detects clipping after WCAG text spacing overrides (1.4.12)
>
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks zoom-200-check,reflow-check,text-spacing-check`

## Timing
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 2.2.1 | Time limits can be extended/disabled | logs | No extension/disable |
| 2.2.2 | Auto-updating content can be paused/stopped | logs | No pause/stop |

> **CLI Checks:**
> - `time-limit-detector` - Detects meta refresh, setTimeout/setInterval, countdown indicators (2.2.1)
> - `auto-play-detection` - Detects auto-playing content via screenshot comparison (2.2.2). See [interactive-checks.md](./interactive-checks.md#auto-play-detection) for details.
>
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks time-limit-detector,auto-play-detection`

## Flashing
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 2.3.1 | No flashes above threshold | video | Flashing exceeds threshold |

## Orientation
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 1.3.4 | Works in both portrait/landscape | screenshots | Functionality blocked in one orientation |

> **CLI Check:** `orientation-check` - Detects orientation lock messages and content visibility differences between portrait/landscape.
>
> Run via: `npx -y @a11y-skills/audit --url "<url>" --checks orientation-check`

## Redundant Entry
| Criterion | Check | Evidence | Fail rule |
|---|---|---|---|
| 3.3.7 | No required re-entry of known information | logs | Re-entry required without valid reason |

[English](./output-format.md)

# 出力フォーマット

監査レポートは以下のテンプレートに従う。内容は簡潔に、証跡と判断理由を必ず添える。

## 出力手順

### 1. 保存先の確認
レポート生成前に、ユーザーに保存先を確認する:
```
監査レポートの保存先を指定してください。
デフォルト: ./[ドメイン名]-[YYYY-MM-DD]/
```

### 2. 出力ディレクトリ作成
`[ドメイン名]-[YYYY-MM-DD]/` 形式でディレクトリを作成する。

例: `a11yc.com-2026-01-24/`

### 3. ファイル生成
出力ディレクトリに以下のファイルを保存する:

| ファイル | 説明 |
|----------|------|
| `report.md` | メイン監査レポート（Markdown） |
| `axe-result.json` | axe-core結果（共通envelope形式） |
| `*-result.json` | その他スクリプト結果（同じ共通envelope形式） |
| `screenshots/` | 証跡スクリーンショット |

### 4. スクリプト出力のコピー
生成されたJSONファイルとスクリーンショットを出力ディレクトリに移動する。

## 結果JSONの形式（@a11y-skills/audit 0.3.0+）

すべてのスクリプト結果は axe 風の共通 envelope で保存される:

- `source` / `url` / `timestamp` — 検査の識別情報
- `violations[]` — **確定した違反**（検出に死角がなく例外が適用され得ないもののみ）
- `incomplete[]` — **要手動確認**。ヒューリスティック検出や例外判断が必要な検出は
  すべてここに入る。**ノイズではなく手動確認キューとして必ずレビューする**
- `passes[]` / `inapplicable[]` — 問題なし / 検査対象なしのルール
- `summary` — ルール単位の件数（`violationCount` / `incompleteCount` / `passCount` /
  `checkedNodes`）
- `details` — 検査固有の証跡（測定値・スクリーンショットパス・全要素記録など）

各ルールは axe と同じ形（`id` / `impact` / `tags` / `helpUrl` / `nodes[]`）。
独自ルールの id は `a11y-skills/` 名前空間付き（例: `a11y-skills/focus-visible`）、
`tags` の `wcag247` 形式タグから該当 SC を機械的に判別できる。
`nodes[].target` はCSSセレクタ（ページ単位の検出は `['html']`）、`nodes[].html` は
outerHTML 証跡、`nodes[].failureSummary` は判断理由の説明。

レポート作成時は `violations` を Fail 候補、`incomplete` を手動確認項目として
基準ごとの判定に反映する。

## レポートテンプレート

```markdown
# アクセシビリティ監査レポート

## スコープ
- 対象URL/画面:
- 対象フロー:
- 対象デバイス/ブラウザ:
- 監査日/担当:
- 除外事項:

## サマリー
| レベル | Pass | Fail | NT | NA |
|---|---:|---:|---:|---:|
| A |  |  |  |  |
| AA |  |  |  |  |

## 詳細結果（基準ごと）
| 基準 | レベル | 判定 | 証跡 | 判断理由 |
|---|---|---|---|---|
|  |  |  |  |  |

## 指摘一覧（Issue Summary）
| 重要度 | 影響 | 該当基準 | 場所 | 概要 | 推奨対応 |
|---|---|---|---|---|---|
|  |  |  |  |  |  |

## スクリーンショット / 証跡

### フォーカスインジケータチェック（2.4.7 / 2.4.11）

フォーカススタイルがない要素には赤枠と「⚠ No Focus Style」ラベルが表示されます。

![フォーカスインジケータチェック結果](./focus-indicators.png)

**検出された問題:**
- フォーカス可能な要素数: X
- フォーカススタイルなしの要素: Y
- 問題のある要素:
  - `<button>` 要素名...
  - ...

### 自動再生検出（1.4.2 / 2.2.2）

自動再生コンテンツを検出するため、一定間隔でスクリーンショットを撮影して比較。

![自動再生検出 - 0秒](./auto-play-screenshots/screenshot-0.png)
![自動再生検出 - 3秒](./auto-play-screenshots/screenshot-3.png)

**検出結果:**
- 自動再生コンテンツ検出: あり/なし
- 比較したスクリーンショット: 4枚（0秒、1秒、2秒、3秒）
- サイズ変化率: X%
- 手動確認:
  - [ ] 一時停止/停止コントロールが提供されている
  - [ ] 5秒以内にコンテンツが停止する
  - [ ] 音声の自動再生がない（またはコントロールが提供されている）

### その他の証跡
<!-- 必要に応じてスクリーンショットを追加 -->

## 手動確認チェックリスト
- [ ] 色・コントラスト
- [ ] テキスト/レイアウト
- [ ] タイミング
- [ ] フラッシュ
- [ ] 画面方向
- [ ] 入力目的
- [ ] 冗長入力
- [ ] マルチメディア
- [ ] 感覚的特徴
- [ ] 音声
- [ ] ナビゲーション

## 制限事項
- 自動チェックはa11y treeに基づくため、視覚的品質は別途確認が必要
- 認証後ページや外部サービスは未検証
- サンプルデータに依存する機能は実運用で再検証が必要
```

## 判定ラベル
- Pass: 基準を満たす
- Fail: 基準未達
- NT: 未検証（検証対象外/時間不足）
- NA: 該当なし

[日本語版 (Japanese)](./output-format.ja.md)

# Output Format

Reports must follow this template. Keep entries concise and always attach evidence and rationale.

## Output Procedure

### 1. Ask for Save Location
Before generating the report, ask the user where to save the output:
```
Where should I save the audit report?
Default: ./[domain]-[YYYY-MM-DD]/
```

### 2. Create Output Directory
Create a directory with the format: `[domain]-[YYYY-MM-DD]/`

Example: `a11yc.com-2026-01-24/`

### 3. Generate Files
Save the following files in the output directory:

| File | Description |
|------|-------------|
| `report.md` | Main audit report (Markdown) |
| `axe-result.json` | axe-core results (common envelope format) |
| `*-result.json` | Other script results (same common envelope format) |
| `screenshots/` | Evidence screenshots |

### 4. Copy Script Outputs
Move generated JSON files and screenshots to the output directory.

## Result JSON Format (@a11y-skills/audit 0.3.0+)

Every script result is saved as the same axe-style envelope:

- `source` / `url` / `timestamp` — identification of the check run
- `violations[]` — **confirmed violations** (only findings whose detection has
  no blind spot and where no WCAG exception can apply)
- `incomplete[]` — **needs manual review**. All heuristic detections and
  findings with possible exceptions land here. **Treat this bucket as the
  manual-review queue, never as noise**
- `passes[]` / `inapplicable[]` — rules with no findings / nothing to examine
- `summary` — rule-level counts (`violationCount` / `incompleteCount` /
  `passCount` / `checkedNodes`)
- `details` — check-specific evidence (measurements, screenshot paths, raw
  element records)

Each rule is axe-shaped (`id` / `impact` / `tags` / `helpUrl` / `nodes[]`).
Custom rule ids are namespaced with `a11y-skills/` (e.g.
`a11y-skills/focus-visible`), and the `wcag247`-style tags identify the
success criterion mechanically. `nodes[].target` holds CSS selectors
(page-level findings use `['html']`), `nodes[].html` carries outerHTML
evidence, and `nodes[].failureSummary` explains the finding.

When writing the report, treat `violations` as Fail candidates and
`incomplete` as manual-verification items for the per-criterion verdicts.

## Report Template

```markdown
# Accessibility Audit Report

## Scope
- Target URLs/screens:
- Target flows:
- Devices/browsers:
- Date/owner:
- Exclusions:

## Summary
| Level | Pass | Fail | NT | NA |
|---|---:|---:|---:|---:|
| A |  |  |  |  |
| AA |  |  |  |  |

## Detailed Results (per criterion)
| Criterion | Level | Result | Evidence | Rationale |
|---|---|---|---|---|
|  |  |  |  |  |

## Issues Summary
| Severity | Impact | Criterion | Location | Summary | Recommendation |
|---|---|---|---|---|---|
|  |  |  |  |  |  |

## Screenshots / Evidence

### Focus Indicator Check (2.4.7 / 2.4.11)

Elements without focus styles are highlighted with a red outline and "⚠ No Focus Style" label.

![Focus Indicator Check Result](./focus-indicators.png)

**Detected Issues:**
- Total focusable elements: X
- Elements without focus style: Y
- Problematic elements:
  - `<button>` element name...
  - ...

### Auto-play Detection (1.4.2 / 2.2.2)

Screenshots taken at intervals to detect auto-playing content.

![Auto-play Detection - 0s](./auto-play-screenshots/screenshot-0.png)
![Auto-play Detection - 3s](./auto-play-screenshots/screenshot-3.png)

**Detection Results:**
- Auto-play content detected: Yes/No
- Screenshots compared: 4 (0s, 1s, 2s, 3s)
- Size change percentage: X%
- Manual verification:
  - [ ] Pause/stop controls provided
  - [ ] Content stops within 5 seconds
  - [ ] No audio auto-play (or controls provided)

### Other Evidence
<!-- Add screenshots as needed -->

## Manual Verification Checklist
- [ ] Color/contrast
- [ ] Text/layout
- [ ] Timing
- [ ] Flashing
- [ ] Orientation
- [ ] Input purpose
- [ ] Redundant entry
- [ ] Multimedia
- [ ] Sensory characteristics
- [ ] Audio
- [ ] Navigation

## Limitations
- Automated checks rely on the a11y tree; visual quality requires separate verification
- Authenticated pages or third-party services not covered
- Features dependent on sample data require production re-check
```

## Result Labels
- Pass: Meets criterion
- Fail: Does not meet
- NT: Not tested (out of scope/time)
- NA: Not applicable

---
name: auditing-wcag
description: WCAG 2.2 A/AAの正式な準拠監査を行い、全達成基準をPass/Fail/NT/NAで証跡付き判定する。問題発見と改善提案を中心とするレビューには reviewing-a11y を使用する。
argument-hint: URL or file path to audit
allowed-tools: Read Grep Glob WebFetch Task mcp__playwright__browser_snapshot mcp__playwright__browser_navigate mcp__playwright__browser_click mcp__playwright__browser_type mcp__playwright__browser_press_key
---

[English](./SKILL.md)

# WCAG準拠監査

あなたはWCAG 2.2 AA準拠監査の実行担当です。達成基準ごとにPass/Fail/NT/NAを判定し、証跡付きで報告します。

## 使い分け（reviewing-a11yとの違い）

| 観点 | reviewing-a11y | auditing-wcag |
| --- | --- | --- |
| 目的 | 問題発見・改善提案 | 準拠状況の体系的確認 |
| 出力 | 重大度別の問題リスト | 達成基準ごとのPass/Fail/NT/NA |
| スコープ | 実用的な問題に集中 | WCAG 2.2 A/AAを網羅 |

### ルーティング基準
- **auditing-wcag**: 「準拠確認」「監査」「コンプライアンス」「適合レポート」などの要件。
- **reviewing-a11y**: 「レビュー」「問題を見つけて」「改善案が欲しい」などの要件。
- 迷う場合は、目的（準拠確認か改善レビューか）を質問する。

## ワークフロー（6ステップ）

### 1. 入力受付
- URLまたはローカルファイルパスを受け取る。
- 複数ページの場合は対象一覧を確認する。
- ローカルファイルは利用可能なファイル読取手段で取得する（実行時挙動は評価できない）。

### 2. スコープ契約
以下を明示し、合意を得る。
- 対象レベル（A/AA、既定はWCAG 2.2 AA）
- 対象ページ範囲（全ページ/代表ページ/指定URL）
- 制限事項（AT確認は範囲外、動的挙動はPlaywright依存）
- 出力形式（達成基準ごとのPass/Fail/NT/NA）

### 3. 自動チェック
- Playwrightでページに遷移し、アクセシビリティツリーを取得する。
- `references/automated-checks.ja.md`を基準に判定する。
- ブラウザ操作が使えない場合は、`a11y-audit` CLI でチェックを実行する（下記「自動チェックCLI」参照）。
- CLIも実行できない場合は、利用可能なWeb取得手段でHTMLを取得し、判定可能な範囲のみ実施する。
- `references/coverage-matrix.ja.md`でカバレッジを確認する。

### 4. インタラクティブチェック
- キーボード操作・フォーカス確認を実施する。
- `references/interactive-checks.ja.md`に従う。
- 実行不能・環境制約がある場合は該当項目をNTにする。

### 5. 手動確認項目提示
- `references/manual-checks.ja.md`と`references/content-checks.ja.md`の項目を提示する。
- 判定に必要な情報が得られない場合はNTとして明示する。
- ユーザーが提供した証拠があれば反映する。

### 6. レポート生成
- `references/output-format.ja.md`に従い、達成基準ごとの判定を列挙する。
- すべてのA/AA達成基準にステータスを付与する（Pass/Fail/NT/NA）。
- スコープ・制限事項・使用ツール・未確認項目をまとめる。

## 自動化の範囲と制限

- Playwrightで取得できるのはアクセシビリティツリー（computed role/name/state）まで。
- 自動テストの結果だけでは監査結果は保証されない。
- スクリーンリーダーの実機確認、AT×ブラウザの組み合わせ検証は対象外。
- 判断できない項目は推測せずNTにする。

## 参照ガイド

- `references/automated-checks.ja.md`
- `references/interactive-checks.ja.md`
- `references/manual-checks.ja.md`
- `references/content-checks.ja.md`
- `references/output-format.ja.md`
- `references/coverage-matrix.ja.md`

## 自動チェックCLI

自動チェックは npm パッケージ [`@a11y-skills/audit`](https://www.npmjs.com/package/@a11y-skills/audit) に含まれる `a11y-audit` CLI で実行します（Node 18+ が必要。ピア依存関係は npm 7+ が自動取得）。

**セットアップ（初回のみ）:**
```bash
npx playwright install chromium
```

**全チェックを実行:**
```bash
npx -y @a11y-skills/audit --url "https://example.com"
```

**特定のチェックのみ実行:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks axe-audit,focus-indicator-check
```

**アノテーション付きスクリーンショット（focus-indicator）:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check --screenshot
```

**結果JSONの出力先を指定（デフォルト: `./a11y-audit-results`）:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --output-dir ./results
```

**終了コード:** `0` = violations なし / `1` = violations あり / `2` = 実行時エラー

| チェック名 | 達成基準 | 説明 |
|---|---|---|
| `axe-audit` | 複数 | axe-coreによる包括的チェック |
| `reflow-check` | 1.4.10 | 320pxでの水平スクロール検出 |
| `text-spacing-check` | 1.4.12 | テキストスペーシング変更後のクリッピング |
| `zoom-200-check` | 1.4.4 | 200%ズーム時のコンテンツ損失 |
| `orientation-check` | 1.3.4 | 画面の向き制限の検出 |
| `autocomplete-audit` | 1.3.5 | autocomplete属性の欠落・不正値 |
| `time-limit-detector` | 2.2.1 | タイマー・meta refresh検出 |
| `auto-play-detection` | 1.4.2, 2.2.2 | 自動再生コンテンツの検出 |
| `focus-indicator-check` | 2.4.7 | フォーカスインジケーターの視認性 |
| `target-size-check` | 2.5.5, 2.5.8 | ターゲットサイズの測定 |
| `keyboard-trap-check` | 2.1.2 | キーボードトラップ検出 |

詳細は [`@a11y-skills/audit` README](https://www.npmjs.com/package/@a11y-skills/audit) を参照してください。

---
name: auditing-wcag
description: Perform formal WCAG 2.2 A/AA conformance audits and assign Pass/Fail/NT/NA to every success criterion with evidence. Use reviewing-a11y instead for issue discovery and improvement feedback.
argument-hint: URL or file path to audit
allowed-tools: Read Grep Glob WebFetch Task mcp__playwright__browser_snapshot mcp__playwright__browser_navigate mcp__playwright__browser_click mcp__playwright__browser_type mcp__playwright__browser_press_key
---

[日本語版 (Japanese)](./SKILL.ja.md)

# WCAG Conformance Audit

You perform WCAG 2.2 AA conformance audits. Report Pass/Fail/NT/NA per success criterion with evidence.

## When to Use This Skill

| Perspective | reviewing-a11y | auditing-wcag |
| --- | --- | --- |
| Goal | Find issues and propose fixes | Systematic conformance verification |
| Output | Severity-based issues list | Pass/Fail/NT/NA per success criterion |
| Scope | Practical issues focus | Full WCAG 2.2 A/AA coverage |

### Routing Rules
- **auditing-wcag**: Requests for "audit", "compliance", "conformance", or formal reporting.
- **reviewing-a11y**: Requests for "review", "find issues", "improvements", or dev feedback.
- If unclear, ask which goal they want: compliance report or issue review.

## Workflow (6 Steps)

### 1. Input Acceptance
- Accept a URL or local file path.
- For multiple pages, confirm the list and entry points.
- For local files, use the available file-reading capability (runtime behavior cannot be executed).

### 2. Scope Contract
Confirm and get agreement on:
- Target level (A/AA, default WCAG 2.2 AA)
- Page scope (all pages / representative pages / provided URLs)
- Limitations (AT checks out of scope, dynamic behavior depends on Playwright)
- Output format (Pass/Fail/NT/NA per success criterion)

### 3. Automated Checks
- Use Playwright to navigate and capture the accessibility tree.
- Apply `references/automated-checks.md`.
- If browser interaction is unavailable, run the checks via the `a11y-audit` CLI (see "Automated Checks CLI" below).
- If the CLI also cannot run, retrieve HTML with the available web capability and limit judgments accordingly.
- Use `references/coverage-matrix.md` to ensure A/AA coverage.

### 4. Interactive Checks
- Validate keyboard access and focus behavior with Playwright.
- Follow `references/interactive-checks.md`.
- If execution is blocked, mark affected criteria as NT.

### 5. Manual Check Items
- Present items from `references/manual-checks.md` and `references/content-checks.md`.
- If evidence is not available, keep them as NT and list them explicitly.
- Incorporate any evidence the user provides.

### 6. Report Generation
- Follow `references/output-format.md`.
- Assign a status to every A/AA success criterion (Pass/Fail/NT/NA).
- Summarize scope, limitations, tools, and unresolved items.

## Automation Scope and Limits

- Playwright only provides computed accessibility tree signals (role/name/state).
- Automated test results alone do not guarantee audit outcomes.
- Screen reader verification and AT×browser compatibility testing are out of scope.
- Do not guess; use NT when evidence is missing.

## Reference Guides

- `references/automated-checks.md`
- `references/interactive-checks.md`
- `references/manual-checks.md`
- `references/content-checks.md`
- `references/output-format.md`
- `references/coverage-matrix.md`

## Automated Checks CLI

Automated checks are run via the `a11y-audit` CLI included in the npm package [`@a11y-skills/audit`](https://www.npmjs.com/package/@a11y-skills/audit) (requires Node 18+; peer dependencies are fetched automatically by npm 7+).

**Setup (first time only):**
```bash
npx playwright install chromium
```

**Run all checks:**
```bash
npx -y @a11y-skills/audit --url "https://example.com"
```

**Run specific checks:**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks axe-audit,focus-indicator-check
```

**With annotated screenshots (focus-indicator):**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --checks focus-indicator-check --screenshot
```

**Custom output directory (default: `./a11y-audit-results`):**
```bash
npx -y @a11y-skills/audit --url "https://example.com" --output-dir ./results
```

**Exit codes:** `0` = no violations / `1` = violations found / `2` = runtime error

| Check name | Criterion | Description |
|---|---|---|
| `axe-audit` | Multiple | axe-core comprehensive check |
| `reflow-check` | 1.4.10 | Horizontal scroll at 320px |
| `text-spacing-check` | 1.4.12 | Text spacing override clipping |
| `zoom-200-check` | 1.4.4 | 200% zoom content loss |
| `orientation-check` | 1.3.4 | Orientation lock detection |
| `autocomplete-audit` | 1.3.5 | Missing/invalid autocomplete |
| `time-limit-detector` | 2.2.1 | Timer/meta refresh detection |
| `auto-play-detection` | 1.4.2, 2.2.2 | Auto-play content detection |
| `focus-indicator-check` | 2.4.7 | Focus indicator visibility |
| `target-size-check` | 2.5.5, 2.5.8 | Target size measurement |
| `keyboard-trap-check` | 2.1.2 | Keyboard trap detection |

See the [`@a11y-skills/audit` README](https://www.npmjs.com/package/@a11y-skills/audit) for detailed documentation.