web-accessibility

Web Accessibility（ウェブアクセシビリティ）

このスキルは、問題のあるアクセシビリティ領域を特定し、適切なレイヤーで修正し、簡潔な修正・検証パケットを残すことが目的の場合に使用します。

目的は、一般的な WCAG の説明を大量に並べたり、生のスキャナー出力を貼り付けたり、隣接するあらゆるフロントエンドの懸念を取り込んだりすることではありません。

このスキルでは、次のことを行います。

1. 問題のあるアクセシビリティ領域を分類する
2. 自動検出された問題と、手動または支援技術による追加確認を切り分ける
3. 信頼性のある最小限の修正パケットを選ぶ
4. ルーティングされたアプリのフィードバックとフォーカスの挙動を明確にする
5. より広範なデザイン、レイアウト、コンポーネントガバナンスに関する作業を適切な担当先に振り分ける

まず、以下の補足ドキュメントを読んでください。

• references/intake-packets-and-route-outs.md
• references/audit-remediation-checklist.md
• references/handoff-boundaries.md

このスキルを使用する場面

• チームから「アクセシビリティを改善してほしい」と依頼されたものの、問題のあるアクセシビリティ領域がまだ明確でない
• axe、Lighthouse、Accessibility Insights、Pa11y、QA メモ、ユーザーからの報告を、生の検出結果の羅列ではなく、1 つの修正計画にまとめる必要がある
• 主な問題が、セマンティクス、キーボード操作／フォーカス、ラベル／通知、リフロー／コントラスト／モーション、メディアの代替手段、ルーティングされたアプリのナビゲーションフィードバックのいずれなのかを判断する必要がある
• モーダル、フォーム、ナビゲーション、メニュー、テーブル、ダッシュボード、ルーティングされたフローについて、リリース前に手動検証と自動検証の指針が必要である
• スクリーンリーダー、キーボードのみの操作、またはズーム／リフローの問題が疑われるものの、担当者と次の確認項目が不明確である

このスキルを使用しない場面

• 主な作業が、再利用可能なプリミティブ／スロット／バリアント API の設計、またはコンポーネントファミリーの所有権である → design-system
• 主な作業が、ビューポートへの適応、ブレークポイント戦略、コンテナークエリの計画、レイアウトのはみ出し制御である → responsive-design
• 主な作業が、トークンガバナンス、コントリビューションルール、またはフロントエンド全体の標準である → design-system
• タスクがツールを 1 つ実行して生の結果を貼り付けるだけである：ツールを直接実行してから、ここに戻って修正と手動での追加確認に優先順位を付ける

手順

ステップ 1：修正方法を決める前に、アクセシビリティの課題を整理する

まず最小限のパケットを記録してください。

accessibility_intake:
  surface: page | routed-flow | modal | form | nav | menu | table | dashboard | component-family | mixed | unknown
  workflow_type: audit-review | remediation-pass | release-readiness | regression-follow-up | user-reported-bug | design-system-follow-up
  signal_source: axe | lighthouse | accessibility-insights | pa11y | manual-qa | screen-reader-report | user-feedback | mixed | unknown
  primary_surface: semantics | keyboard-focus | labels-announcements | visual-perception-reflow | media-alternatives | routed-navigation-feedback | mixed | unknown
  severity: blocker | major | medium | low | unknown
  ownership: app-team | frontend-platform | design-system | qa-accessibility | shared | unknown

ルール：「ARIA を追加する」「axe をもう一度実行する」「WCAG 2.1 を引用する」ことから始めてはいけません。 まず、問題のあるアクセシビリティ領域を特定します。

ステップ 2：主要な修正パケットを 1 つだけ選ぶ

references/intake-packets-and-route-outs.md のルーターを使用してください。

主要なパケット：

1. semantics-structure
2. keyboard-focus
3. labels-announcements
4. visual-perception-reflow
5. media-alternatives
6. routed-navigation-feedback

ユーザーに最も大きなリスクをもたらす問題を、主要な問題として選びます。 それ以外は、対等な共同担当としてではなく、追加対応として列挙してください。

ステップ 3：不変の原則を明示する

次のルールは、どの回答でも変わりません。

• 自動ツールは問題の発見を効率化しますが、アクセシビリティが完全であることを証明するものではありません
• ネイティブ HTML のセマンティクスで問題を解決できる場合は、ARIA による後付けよりも優先します
• インタラクティブなフローにおけるキーボード操作／フォーカスの問題は、通常、見た目だけの調整より優先されます
• ルーティングされたアプリでは、ブラウザーのナビゲーションの手がかりが失われるため、フォーカスと通知の方法を明確に決める必要があります
• ラベル、説明、エラー、非同期処理の状態テキストは、装飾ではなくタスク完了の一部です
• すべての修正提案に、対応する手動検証手順が必要です

ステップ 4：アクセシビリティ修正パケットを作成する

次の構成で返してください。

# Accessibility Remediation Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Tool or report source:
- What is already known:
- What still needs direct verification:

## Highest-risk gaps
1. ...
2. ...
3. ...

## Recommended first slice
1. ...
2. ...
3. ...

## Verification plan
- Automated re-check:
- Manual keyboard / focus:
- Manual screen-reader / AT:
- Visual / zoom / motion / reflow:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

Step 5: 巨大なチェックリストではなく、パケットを使う

references/intake-packets-and-route-outs.md からパケットを取得します。

パケットのルール：

• semantics-structure → ランドマーク、見出し、リスト、表、ボタン／リンク、フォームのマークアップ、ネイティブ機能を優先した修正
• keyboard-focus → タブ順序、視覚的なフォーカス表示、トラップ／エスケープの動作、初期フォーカス、フォーカスの戻り、複合ウィジェットの動作
• labels-announcements → アクセシブルネーム、ヘルパー／エラーとの関連付け、ライブリージョン、ステータス／エラーメッセージ、必須状態の明確さ
• visual-perception-reflow → コントラスト、モーションの低減、ズーム、リフロー、ターゲットの視認性、状態の視認性
• media-alternatives → 代替テキスト、装飾用画像と情報を伝える画像の区別、キャプション、トランスクリプト、フォールバックの説明
• routed-navigation-feedback → ページタイトル／見出しの読み上げ、ルート変更時のフォーカス戦略、SPA／アプリルーターの手がかり、非同期読み込み状態の読み上げ

Step 6: 自動検出の指摘と手動での検証を分ける

本格的な回答では、毎回次の区分を使います：

• 自動検出に適した項目 — ラベルの欠落、IDの重複、無効なARIA、単純なコントラスト違反、ランドマーク／見出しの不足
• キーボード／フォーカスの手動検証 — タブ順序、視覚的なフォーカス表示、トラップの動作、初期フォーカス、フォーカスの戻り、メニュー／リストボックス／ダイアログの操作
• 支援技術／コンテンツ品質の手動検証 — 読み上げの有用性、代替テキストの品質、ラベルの明確さ、ルート変更の理解しやすさ、非同期フィードバックの品質

依頼がスキャナーの結果から始まる場合は、スキャナーは入力成果物であり、完成した回答ではないことを明示してください。

Step 7: 隣接する作業は明示的に振り分ける

問題が次の領域にまたがる場合は、以下の振り分け先を使います：

実際の作業が...の場合	振り分け先...
UI／デザイン全般のレビュー、階層、洗練度、ガイドラインへの準拠	広範なレビューのモードで、ここが担当
再利用可能なコンポーネントのAPI／プリミティブの担当範囲／スロット・バリアントの設計	design-system
ビューポート／コンテナーのレイアウト戦略やブレークポイントの計画	responsive-design
トークンのガバナンスやシステム全体のフロントエンド標準	design-system
React／Next のパフォーマンスやハイドレーションの動作	react-best-practices

出力への期待

このスキルによる優れた回答は、次の点を満たす必要があります：

1. 主に問題があるアクセシビリティの対象領域を特定する。
2. 範囲を絞った修正パケットを1つ提案する。
3. 引き続き必要な手動検証を明示する。
4. スキャナーの検査を通過したことを、対応完了と同一視しない。
5. より広範なフロントエンドの担当範囲に関する質問は抱え込まず、適切な先へ振り分ける。

例

例1：axe実行後のモーダル監査

入力

このチェックアウト用モーダルのアクセシビリティ上の問題を監査し、axe実行後に手動で何をテストすべきか教えてください。

回答の方向性

• keyboard-focus または labels-announcements を選ぶ
• axeはワークフロー全体ではなく、入力成果物として扱う
• 初期フォーカス、トラップの動作、フォーカスの戻り、読み上げの品質を検証する
• アクセシビリティに実質的な影響がない限り、広範なビジュアルの洗練度に関する批評は避ける

例2：ルーティングされたアプリのナビゲーションに関する混乱

入力

Reactアプリでルートが変わっても新しいページが読み上げられず、フォーカスが古いナビゲーションリンクに残ったままだと、スクリーンリーダーのユーザーから指摘されています。

回答の方向性

• routed-navigation-feedback を選ぶ
• タイトル／見出しの読み上げとフォーカスリセット戦略を分類する
• 修正後に支援技術を使った手動検証を含める
• タスクを一般的なルーティングアーキテクチャの作業に広げない

例3：コンポーネントの担当範囲に関する混乱

入力

ボタンプリミティブのAPIが複雑で、一部のバリアントにアクセシビリティの問題があります。これはweb-accessibilityとdesign-systemのどちらの担当ですか？

回答の方向性

• アクセシブルネーム、フォーカス状態、無効／読み込み中の状態の読み上げに関する修正は web-accessibility の担当とする
• プリミティブのAPI／バリアントの担当範囲は design-system に振り分ける
• 1つのスキルにすべてを押し込まず、計画を分ける

例 4：Lighthouse の後に手動で確認する項目

入力

Lighthouse ではコントラストに問題はないと表示されます。ほかに手動でテストすべき項目は何ですか？

出力の方向性

• スコアを評価するのではなく、検証計画として扱います
• 必要に応じて、キーボード操作の順序、フォーカスの視認性、画面遷移の手がかり、スクリーンリーダーでのアナウンスの品質を確認します
• インターフェースがそれらに依存する場合は、ズームやリフロー、モーションの低減も確認します

ベストプラクティス

1. ルール番号ではなく、ユーザーのタスクと問題が発生している箇所から始めます。
2. 自動化ツールは効率化の手段として扱い、アクセシビリティが完全であることの証明とはみなしません。
3. ARIA に過度に依存した修正より、ネイティブ HTML のセマンティクスを優先します。
4. オーバーレイ、ルート変更、非同期の検証におけるフォーカスの動作を意図的に設計します。
5. 修正用の作業項目と、より広範なデザインレビューやコンポーネントアーキテクチャの作業を分けます。
6. 判断に迷う場合は、スキャンだけで十分だと装わず、引き続き必要な手動検証を明示します。

参考資料

• W3C：ウェブアクセシビリティ評価の概要
• W3C：簡易チェック ― ウェブアクセシビリティの初回レビュー
• web.dev：アクセシビリティの手動テスト
• MDN：キーボードで操作可能にする
• React Router：アクセシビリティ
• Next.js：アクセシビリティ