review-a11y

review-a11y — 変更されたコードのアクセシビリティレビュー

ultra11y スキルに対応するレビュー用スキルです。ultra11y が包括的な監査とコンプライアンス関連の成果物を作成するのに対し、このスキルは変更対象のコードだけ（diff、ブランチ、PR）をレビューし、コードレビューのように報告します。作業分担は同じです。このスキルに同梱された、インストール不要の決定論的エンジンが機械的な作業（成功基準ごとに紐付けられ、file:line が記載された、機械で確認可能な WCAG 2.2 AA の不適合）を行い、AI エージェントが判断を下します。誤検出を退け、コードから静的に alt の関連性、リンクの目的、フォーカスのロジックを判断し、レンダリング済み DOM が必要な項目は scan に回します。人間による確認は任意です。

エンジンの解決方法： 以下の各コマンドは node scripts/ultra11y.mjs … です。scripts/ultra11y.mjs はこの SKILL.md と同じ場所にあります（エンジンはスキル内に同梱されており、インストールもキーも不要です）。レビュー対象のプロジェクトを作業ディレクトリとして実行してください。ultra11y リポジトリ自体では、リポジトリルートにある scripts/ultra11y.mjs が同じファイルです。Claude Code ではパスは ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs です。Codex と OpenCode では、プラグインがインストールしたスキルディレクトリを使います。どちらでも解決できない場合（スキルシステムのないハーネス）は、npx -y ultra11y <command> で同じエンジンを実行できます。ハーネスごとの差異については、ultra11y スキルの references/harnesses.md を参照してください。

基本ルール（ultra11y と共通）：

1. 不適合を捏造しない：エンジンが検出したもの、またはレビュー対象のコードで確認して根拠を示せるものだけを報告してください。
2. 世界ではなく変更をレビューする：レビュー対象外の指摘事項は、最大でも「既存の問題、スコープ外」のように一行で記載し、判定に混ぜないでください。
3. 残存リスクを明示し、暗黙に適合としない：レンダリングに関する基準（コントラスト、フォーカスの可視性、ズーム／リフロー、ホバー時のコンテンツ）は、変更されたコンポーネントの残存リスクとして明記してください。ソースコードだけで適合を断定せず、レンダリング済みページで解決してください（scan）。判断を要する基準（alt の関連性、リンクの目的、読み上げ順序）は、AI エージェントがコード自体から判断し、その理由を記録してください。正当な根拠なしに判定を付けてはいけません。
4. 言語：レビューは会話で使われている言語で記述してください。ただし、フランス語の文章でも技術トークンは英語のままにします。aria-live は aria-live のままにしてください（« région live » とはしないでください）。tabindex、alt、role="alert"、ランドマークのロール名も同様です。

1. スコープ — 変更点をレビューする

該当するもののうち、最初の項目を選んでください（本当に判断が難しい場合に限り、質問してください）。

node scripts/ultra11y.mjs audit <files the user named> --jsx --json     # explicit files
node scripts/ultra11y.mjs audit --staged --graph --json                 # staged snapshot (pre-commit review)
node scripts/ultra11y.mjs audit --changed --graph --json                # working diff
node scripts/ultra11y.mjs audit --since origin/main --graph --json     # the whole branch (PR review) — use the repo's default branch

• JSX／TSX では必ず --graph を渡してください（実際の AST とファイルをまたぐルールに対応します。例：名前のないアイコン専用コンポーネントの使用、別ファイルで定義されたアンカーのターゲットなど）。また、単一ファイルにおける特定の誤検出も抑制されます。
• --lang には会話に合わせた言語を指定してください。エンジンのメッセージと修正案の文言がレビューの言語になります（未指定の場合、CLI が自動検出しますが、これは代替手段であり、指定の代わりにはなりません）。
• リポジトリ全体のレビューはレビューではなく監査です。その場合は、代わりに ultra11y スキルを案内してください。
• テスト／ストーリーのマークアップ（*.test.*、*.stories.*、__tests__/）はデフォルトで除外されます。対象に含めるにはそのファイル名を明示するか、--no-default-excludes を渡してください。

2. 判定 — エンジンの検出結果は候補であり、最終判断ではありません

各検出結果（--json には criteria、severity、file:line、message、 remediation が含まれます）について：

• 該当箇所を確認する：指摘された行を開き、レビュー対象の変更に問題の要素が実際に存在することを確認します。
• preliminary: true の検出結果（.vue／.svelte／.astro のソース、ライブラリコンポーネント）について：テンプレートパーサーはスロット、条件分岐、provide/inject の配線を認識できません。キャプチャがある場合（ultra11y スキルの render --setup ハーベスターが生成する .ultra11y/captures）はレンダリング済み DOM と照合して確認し、ない場合はその注意点を添えて暫定として報告するか、コードの根拠を示して反証します。
• **ライブラリがレンダリングする JSX（DSFR、MUI など）**について：ソースのレビューで問題が見つからなくても、壊れた HTML が出力される可能性があります（偽陰性）。変更がこの種のコンポーネントに関わる場合は、その点を明記し、レンダリング済み DOM の確認（scan または ultra11y のキャプチャパイプライン）を推奨します。
• 判定基準は AI エージェントが判断します：代替テキストの関連性、文脈におけるリンクの目的、表示ラベルとアクセシブルネームの一致、変更対象コンポーネントのキーボード／フォーカスのロジック（指摘された行だけでなく、コンポーネントのソース全体を読む）、各判断の理由の記録。
• 検出結果を反証するには、根拠の提示（反証となるコード）が必要です。検出結果を黙って削除することは禁止されています。

3. 報告 — コンプライアンス文書ではなく、レビューとして

会話の言語で出力し（コアルール 4）、重大度ごとにまとめます：

## Accessibility review — <scope, e.g. branch feat/x vs main, 12 files>

### 🔴 Blocking
- `src/components/Form.tsx:42` — **3.3.2 Labels or Instructions** — input has no
  label and placeholder is its only hint → associate a real <label for>, keep the
  placeholder as an example only.

### 🟠 Major / 🟡 Minor
- …same shape…

### Residual risks (rendering-dependent — resolve in the rendered page via scan)
- contrast of the new button variants (1.4.3), focus visibility on the custom menu (2.4.7)

### Verdict
1 blocking, 2 major to fix before merge; 2 provisional SFC findings to confirm on the
rendered DOM; residual risks listed above.

• 各修正のベースには、エンジンの remediation テキストを使用します。これはすでにローカライズされ、判定基準に基づいています。
• ついでに見つけた既存の問題は、判定とは分けて最後の1行にまとめます。

サブエージェントとして実行する場合。 このスキルは手入力ではなく、呼び出されて実行されることがよくあります。保留中の git commit／git push／gh pr create に対するプラグインフックから、または監査で修正を生成した後に ultra11y スキルから呼び出されます。その場合、上記の報告そのものが戻り値となり、人間へのメッセージではなく呼び出し元へのツール結果になります。したがって、報告全体だけを返し、それ以外は何も付け加えないでください。前置きや「エンジンを実行したところ、次の問題が見つかりました……」といった説明、修正の申し出は不要です。要約を受け取った呼び出し元は検出結果を推測しなければならなくなりますが、それを防ぐことこそ、このスキルの目的です。§4 の内容はすべてオプトインであり、あなたではなく呼び出し元が判断します。

4. レビュー後（オプトイン）

• 安全な機械的修正：fix --staged --write --safe（安全な codemod をステージ済みファイルに自動適用し、再ステージします）または node scripts/ultra11y.mjs fix <files> --write を実行します。--write を付けずにドライランできます。
• 正式な成果物（日付入りレポート、監査者適合ブロック、PRD バックログ、GitHub issue、RGAA／国別規格の用語）：それは ultra11y スキルの担当です。同じエンジン、同じ検出結果を使用します（report、prd、check／verify ゲート）。
• 自動化する：Claude Code プラグインとしてインストールすると、PreToolUse フックが、検出結果を含む保留中の git commit／git push／gh pr create を停止し、その結果を引き渡します。これにより、誰かが依頼しなくてもこのスキルが呼び出されます。同じ検出結果に対して二度実行されることはないため、再試行は成功します。エージェントを必要としないゲートには、ultra11y スキルの init --hook を使うと、このステージ済み監査と同じ機械的な pre-commit 実行をインストールできます。

禁止事項

• エンジンが検出しておらず、根拠も示せない不適合をでっち上げないでください。
• ソースだけを根拠にコントラスト／フォーカス／ズームについて断定しないでください。レンダリングして確認するまでは残存リスクです（scan で解消します）。
• リポジトリに既存の問題を、変更に対する判定に混ぜないでください。
• フランス語の文章中にある技術トークンを翻訳しないでください（aria-live はそのままにし、「région live」とはしません）。