accessibility

アクセシビリティ — スキルエントリー

このスキルは、HVE Core におけるアクセシビリティの正式な参照契約です。エージェントと指示はこのスキルを名前で呼び出し、フレームワーク参照の解決、フェーズガイダンスの解決、スキャナー CLI のエントリーポイントをこのスキルに委ねます。

フレームワーク参照

• WCAG 2.2
• ARIA オーサリングプラクティスガイド
• 認知アクセシビリティガイダンス
• Section 508
• EN 301 549
• グラフィックス ARIA と SVG-AAM

評価の参照資料（複数領域にまたがるもので、適合性フレームワークではありません）：

• 支援技術のアナウンスモデル — アナウンスクラスの基準（WCAG 1.3.1、4.1.2、4.1.3）を決定する際に参照してください。スクリーンリーダーのユーザーに何が聞こえるべきか、また、アクセシビリティツリーのアサーションまたは手動の支援技術テストによってどう判断するかを説明しています。

アクセシビリティプランナーのワークフロー

アクセシビリティプランナーは、状態 ID をキーとする次の6つのフェーズを実行します。

1. フェーズ 1 — 発見（discovery）
2. フェーズ 2 — フレームワークの選定（framework-selection）
3. フェーズ 3 — 規格へのマッピング（standards-mapping）
4. フェーズ 4 — 計画のリスク評価（plan-risk-assessment）
5. フェーズ 5 — 影響とエビデンス（impact-evidence）
6. フェーズ 6 — バックログへの引き継ぎ（backlog-handoff）

フェーズ参照インデックス

• フェーズ 1 — 発見：capture-coaching.md — 探索を優先する情報収集の質問を行う際に参照してください。
• フェーズ 2 — フレームワークの選定：framework-selection.md — 適用するフレームワークと適合レベルを選ぶ際に参照してください。
• フェーズ 3 — 規格へのマッピング：フレームワーク参照の集約表をたどってcontrolMappingsを出力します。これはフェーズ 5 で使用されます。専用ファイルはありません。マッピングはフレームワークの集約表に基づいて行われます。
• フェーズ 4 — 計画のリスク評価：スコープの見直しを促すエスカレーションのトリガーが発生した際の質問の進め方は、capture-coaching.mdに従います。リスク階層の基準はアクセシビリティプランナーのアイデンティティ指示に従って適用し、riskClassification.tierに記録します。アクセシビリティのリスク範囲は狭く、インラインで扱えるため、専用ファイルはありません。
• フェーズ 5 — 影響とエビデンス：impact-assessment.md — エビデンス登録簿、トレードオフログ、シード作業項目を作成する際に参照してください。
• フェーズ 6 — バックログへの引き継ぎ：backlog-handoff.md — 作業項目を出力し、引き継ぎゲートを検証する際に参照してください。

手法の適切性（判定と情報提供）

手法の適切性とは、検証手法が成功基準を実際に判定できる場合に限り、その基準を満たすものとして記録できるという原則です。関連する兆候を観察できても、ユーザーにとっての結果を確認できない手法は、その基準について情報を提供するにとどまります。疑いを強めたり弱めたりはしますが、適合を確定することはありません。このセクションは正式な定義であり、プランナーのエビデンス登録簿、レビュアーの判定ロジック、ランタイムプローブハーネスはすべて、ここに基づいて適切性を判断します。

機械可読な適切性の情報源はこちらです。各プローブのエントリーには、そのプローブがdecidesする基準と、informsするにとどまる基準が記載されています。ある結果が適切とみなされるのは、その基準と状態について、最終的に採用された手法がdecidesリストに含まれている場合に限ります。

不適合の分類と適切な評価方法

アクセシビリティの不備は、5つの分類に整理できます。静的解析（axe、eslint-plugin-jsx-a11y、スナップショット構造のカウント）で判定できるのは最初の分類のみです。残る4つは、単に判断材料を得るだけでなく、判定するためにインタラクション状態の検証、または支援技術（AT）による確認が必要です。

分類	代表的な WCAG 達成基準 SC	静的解析でできること	判定に適した方法
静的に判定可能な構造	1.1.1、1.4.3、4.1.2（名前の存在）、2.4.2、3.1.1	判定できる	axe／静的スキャン
インタラクション動作	2.1.1、2.1.2、2.4.3、2.4.7、2.4.11	判断材料のみ	focus／open 状態をまたいでキー操作を行うキーボード／インタラクション検証、または手動のキーボード確認
通知の正確性	1.3.1、4.1.2（計算された名前／ロール）、4.1.3	判断材料のみ	計算された名前／ロール／ライブ領域のアクセシビリティツリー検証、または手動の AT 確認（Windows NVDA または人間が操作する JAWS）
適応型レンダリング	1.4.4、1.4.10、1.4.12、2.4.11	判断材料のみ	200% ズーム、320px でのリフロー、テキスト間隔の各状態でレンダリングを検証
見せかけのセマンティクス	1.3.1（見せかけの見出し）、2.4.3（見せかけのコントロール）	検出できない	ヒューリスティックによるソース確認とアクセシビリティツリー検証の併用。ルールエンジンがフラグを立てる対象となる要素が存在しません

通知の分類については、支援技術の通知モデルで、基準ごとにユーザーが聞くべき内容と判定方法を定めています。インタラクションと見せかけのセマンティクスの分類については、フォーカス管理のアンチパターンカタログで、静的スキャンを通過してもキーボードやスクリーンリーダーのユーザーに支障をきたす不備を列挙しています。

適切性のルール

• インタラクション、通知、適応型レンダリング、または見せかけのセマンティクスの分類に属するコントロールは、静的な根拠だけで完全に適合していると記録できません。適切な方法が追加されるまでは、静的な根拠によるそのようなコントロールの状態は部分的なものが上限となります。
• 採用された方法が単に対象を informs するだけの基準は、適合性の判定にはなりません。適切な方法、または手動確認につなげるための手掛かりです。
• 適切性の判定はステータスと併せて保持し、後続の計画担当者やレビュー担当者が、適切に検証されていないコントロールを再び適合扱いしないようにしてください。

この方針と分類体系は、リポジトリ独自のコンテンツであり、CC BY 4.0 ライセンスの下で提供されています。基礎となる達成基準の定義は、wcag-22.mdで引用されているとおり、引き続き WCAG 2.2 に帰属します。

キャリブレーションは適合性の判定ではなく、エビデンスの品質を示します

キャリブレーションでは、その出力を信頼する前に、支援技術スタックが期待どおりに動作することを確認します。チェックポイントには、合格したジャーニーのドライバー ID、プロファイルのフィンガープリント、アーティファクトのハッシュが記録されます。

チェックポイントは意図的にマトリックスの入力として扱いません。カバレッジや結果を処理するパイプラインからチェックポイントが読み取られることはありません。この分離は未完成だからではなく、意図的なものです。キャリブレーションに合格したことは、ハーネスが機能していたことを示しますが、対象の画面が成功基準を満たしていることを示すものではありません。チェックポイントをカバレッジに組み込むと、ツールに関する記述がプロダクトに関する記述へと変わってしまいます。

キャリブレーションのエビデンスをカバレッジに反映させる場合は、新たな設計作業として、別途レビューが必要です。ジャーニーを基準、画面、状態に明示的に対応付け、ほかのエビデンスと同じ手法の妥当性に関するルールを守る必要があります。

評価ティアに応じたゲートの厳格さ

インタラクション、アナウンス、アダプティブレンダリング、擬似セマンティクスのクラスに対する適用方針は、riskClassification.tier に記録された評価の深度ティアに応じて段階的に厳しくなります。これにより、単一のグローバルスイッチを適用するのではなく、プロジェクトが選択した厳格さをゲートに反映できます。

• basic — 妥当な手法によるプローブ（keyboard、widget-keyboard、live-region、aria-tree、virtual-sr）はアドバイザリー（警告のみ）として報告されます。常に判定可能なコアプローブは引き続きブロックします。
• standard（デフォルト） — 段階的適用：妥当な手法によるプローブは、新規または変更された画面ではブロックし、既存のバックログではアドバイザリーのままとなります。これにより、既存コンテンツを可視化しつつ、プロジェクトを凍結することなく、これらのクラスに新たな不具合が含まれた状態でリリースされるのを防ぎます。
• comprehensive — 妥当な手法によるプローブは、対象となるすべての画面でブロックします。

常に判定可能なコアプローブ（axe、DOM の衛生状態、リンク切れ、コンソールエラー、ターゲットサイズ、コントラスト、リフロー／リサイズ）は、すべてのティアでブロックします。CI ワークフローテンプレートでは、A11Y_TIER と A11Y_RATCHET_SURFACES の入力を使ってこの調整を行います。Accessibility Reviewer も、FAIL と PARTIAL の判定に同じ段階的適用を行います。

ツール

スキャナー CLI（scripts/scan.py）は、Node ベースの axe-core スキャナーをラップし、その検出結果を安定した JSON 形式に正規化します。

前提条件

• PATH から利用できる uv と Python 3.11 以降。
• PATH から npx を利用できる Node.js。
• 初回実行時に npx が @axe-core/cli を取得するためのネットワークアクセス。

クイックスタート

uv run scripts/scan.py https://example.com --allow-host example.com
uv run scripts/scan.py ./page.html --output results.json
uv run scripts/scan.py file:///path/to/page.html

ループバックの HTTP(S) ターゲットには、追加オプションは不要です。それ以外のリモートホストには、一致する --allow-host HOST の値を必要な回数指定するか、より広範な確認オプションである --allow-external が必要です。ローカルパスとローカルの file: URI は、既存の通常ファイルを参照している必要があります。ネットワーク共有、リモートのファイルオーソリティ、ディレクトリ、存在しないファイル、認証情報、先頭がハイフンのターゲット、HTTP(S) 以外のリモートスキームは、axe CLI の起動前に拒否されます。

パラメーターリファレンス

パラメーター	必須	デフォルト	説明
target	はい	—	スキャンする、許可済みの HTTP(S) URL または既存の通常のローカルファイル。
--output	いいえ	stdout	正規化された JSON の結果を書き込むパス。
--allow-host	いいえ	なし	ループバック以外の HTTP(S) ホストを 1 つ許可します。必要に応じて繰り返し指定します。
--allow-external	いいえ	false	ループバック以外のすべての HTTP(S) ホストへのアクセスを確認します。

リモートアクセスの許可は、最初のスキャナーターゲットにのみ適用されます。ブラウザーのリダイレクト、DNS アドレスの変更、サブリソース、WebSocket、Service Worker、ダウンロード、その他のブラウザー由来のリクエストは制限されません。ターゲットと同等の信頼レベルを持つネットワークに接続されたワークステーションからのみ、スキャナーを実行してください。

スクリプトリファレンス

• エントリーポイント：scripts/scan.py

• 出力形式：

  {
    "target": "<scanned target>",
    "summary": {
      "violations": 0,
      "passes": 0,
      "incomplete": 0,
      "inapplicable": 0
    },
    "violations": [
      { "id": "", "impact": "", "description": "", "nodes": 0 }
    ]
  }
  

• 終了コード：

  • 0 — スキャンが正常に完了しました。
  • 1 — スキャンに失敗したか、無効な出力が返されました。
  • 2 — スキャナーを利用できません（Node.js または @axe-core/cli が見つかりません）。

トラブルシューティング

症状	考えられる原因	対処法	終了コード
scanner unavailable エラー	Node.js または npx が PATH にありません	npx が解決されるように Node.js をインストールしてから、再実行してください。	2
初回実行時に長い待ち時間やダウンロードが発生する	npx が @axe-core/cli を取得しています	初回実行時はネットワークアクセスを許可してください。以降の実行ではキャッシュが使用されます。	—
Refusing to probe non-loopback host	リモートホストが明示的に許可されていません	--allow-host HOST を追加するか、--allow-external で確認してください。	2
Local scan target does not exist	ローカルパスまたはファイル URI を解決できません	ディレクトリや共有フォルダーではなく、既存の通常のローカルファイルを指定してください。	2
scan failed or returned invalid output	axe-core CLI でエラーが発生したか、JSON 以外が出力されました	対象の URL またはファイルにアクセスでき、形式が正しいことを確認してください。	1
violations が空なのに問題があるはずの場合	スキャン後にページが描画されたか、ルールが該当しません	対象が完全に読み込まれることを確認し、summary.inapplicable を確認してください。	0

検出結果をフレームワークに対応付ける

各違反の impact は minor、moderate、serious、critical のいずれかです。axe のルールタグは、wcag 接頭辞を取り除き、小数点を挿入することで WCAG 達成基準に対応付けられます。

axe タグ	WCAG 達成基準
wcag111	1.1.1 非テキストコンテンツ
wcag143	1.4.3 コントラスト（最低限）

WCAG 達成基準は規範的なものですが、それを検出する axe の手法は参考情報です。スキャナーの出力は、適合性の判定ではなく、達成基準を示す証拠として扱ってください。

ランタイムプローブハーネス

ランタイムプローブハーネス（scripts/runtime_a11y）は、プロジェクト固有の対象一覧に対して Playwright ベースのアクセシビリティプローブを実行し、結果を集約してカバレッジマトリックスを作成します。ワークフローのオーケストレーションでは、手動専用の accessibility-coverage-matrix スキル（/accessibility-coverage-matrix）を実行するようユーザーに依頼してください。このスキルはモデルから呼び出すことはできません。ランタイム設定の標準的な生成元として、Accessibility Surface Inventory サブエージェントを使用してください。名前を指定して起動します。解決できない場合は、この機能を利用できないことをユーザーに伝え、依存するステップを中止してください。

ハーネスの前提条件

ランタイムハーネスのコマンドを実行する前に、以下を一度だけ完了してください。これらは、上記の scan.py の前提条件とは別です。

• PATH 上で利用できる uv を備えた Python 3.11 以降。
• PATH 上で利用できる Node.js と、システムの Google Chrome。プローブは channel: 'chrome' を対象とするためです。
• scripts/runtime_a11y 以下にインストールされた、スキル内の Node 依存関係。不足している場合、CLI はインストール方法を示してすぐに終了します。
• 自動化された Windows NVDA 実行には、マニフェストで選択された Guidepup NVDA アセットも必要です。マシンのセットアップとアセットのインストールは、npm ci とは別の作業です。

scripts/runtime_a11y ディレクトリからハーネスの依存関係をインストールします。

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = '1'; npm ci

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 を指定すると、ハーネスで使用しないバンドルブラウザーのダウンロードを回避できます。

自動化された NVDA 実行では、まず Windows マシンを一度セットアップし、次にスキル内の Guidepup パッケージによって選択されたアセットをインストールします。Guidepup を更新した後は、アセットのコマンドを再度実行してください。

Set-Location <skill-root>/scripts/runtime_a11y
npx --yes --registry=https://registry.npmjs.org/ @guidepup/[email protected] setup
npx --yes --registry=https://registry.npmjs.org/ @guidepup/[email protected] install nvda

これらのコマンドはマシンを設定し、バージョン管理されたアセットを Guidepup のユーザーキャッシュに書き込みます。通常の依存関係のインストールには含まれません。キャリブレーションセッションの前に、前提条件のみを確認するプローブを実行してください。

uv run scripts/runtime_a11y/__main__.py run-calibration --config <path-to>/a11y-runtime.config.json --prerequisite-only

事前チェックでは、スキル内のライブラリ、マニフェストで選択された NVDA アセット、競合する NVDA プロセスの有無をそれぞれ個別に報告します。自動実行の前に個人用の NVDA インスタンスを起動しないでください。ハーネスは分離されたセッションを起動し、既存のプロセスがある場合は実行を拒否します。

製品に依存しないスクリーンリーダーのケースは scripts/runtime_a11y/screen-reader-cases.json にあります。下流のバインディングで、名前付きルート、ターゲット、状態、明示的な実行手順を指定します。カタログダイジェストの不一致、ターゲットの不足、重複する ID、未サポートのコマンド、秘密情報を含むバインディングキー、推測されたアクションがある場合、ブラウザーの起動前に失敗します。

承認済みのライブサブセットには、繰り返し実行可能な run-calibration --journey <id> 引数を使用してください。製品ケースの前に下流の整合性レシピを実行し、実際の NVDA はアドバイザリー／手動にとどめてください。決定論的な証跡を得るには、サーフェス／状態フィルター、またはレビュー済みの probeScoping 設定とともに run-all --probe <probe-id> を使用してください。通常の run-all を、実際のスクリーンリーダーを起動する許可として扱ってはいけません。

実行方法

ハーネスはスクリプトのエントリーポイントから実行してください。pyproject.toml があるディレクトリであるスキルのルートから呼び出すと、uv はスキル独自の環境を解決します。これは scan.py や他の Python スキルで使われている呼び出し規約と一致し、PYTHONPATH も不要です。

uv run scripts/runtime_a11y/__main__.py run-all --config a11y-runtime.config.json --out results.json
uv run scripts/runtime_a11y/__main__.py probe <probeId> --config a11y-runtime.config.json
uv run scripts/runtime_a11y/__main__.py render-artifacts --matrix coverage-matrix-repo.json --output-dir .copilot-tracking/accessibility/coverage --repo-slug repo
uv run scripts/runtime_a11y/__main__.py compose-evidence --help

それ以外の作業ディレクトリから実行するには、スキルを uv のプロジェクトとして指定し、同じスクリプトパスを使用します。

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py run-all --config a11y-runtime.config.json --out results.json

• --config は、現在の作業ディレクトリを基準に解決されます。
• --out は、集約された JSON ドキュメントをディスクに書き込みます。
• --base-url は、設定済みのベース URL を上書きします。ホストが許可リストに登録されているか、--allow-external が指定されていない限り、ループバックのオリジンである必要があります。
• --trace は、Playwright のトレースとスクリーンショットをキャプチャします。
• --allow-external は、ループバック以外のホストを意図的にプローブすることを確認します。
• render-artifacts は、レンダリング済みのマトリクス JSON ドキュメントを、完全なカバレッジ証跡バンドルに変換します。

エビデンスバンドルの構成

compose-evidence は、下流プロジェクトが所有するカタログ、ケイデンスの対象範囲、実行コンテキスト、正規化されたソースエンベロープ、状態証明、および任意の適格なレビュアーによる補足情報を組み合わせて、決定論的なエビデンスバンドルを作成します。これは render-artifacts とは別の機能です。レンダリングではマトリクスからカバレッジ、EARL、および手動計画のビューを作成し、構成ではエビデンスの生成元全体にわたる、リビジョンに紐づく信頼エンベロープを作成します。

このコマンドでは入力パスを明示的に指定する必要があり、製品の対象範囲、Git の状態、時刻、保持期間、ブランチポリシー、リリース判定を推測することはありません。これらの判断は、利用するプロジェクトが行います。コンポーザーは --artifact-root 配下のアーティファクトのバイト列を検証し、競合と隔離された結果を保持して、常に非アテステーションメタデータを出力します。自動化、レビュアーエビデンス、リリースエビデンスは、それぞれ個別の完全性状態を持ちます。

プルリクエストの場合、有効な初期バンドルでは、レビュアーエビデンスが保留中と報告されることがあります。適格なレビュアーは、プライバシーを最小限にしたダイジェスト紐づけ済みの補足情報とレジストリスナップショットを後から提供し、前回のバンドルを基に決定論的に再構成できます。再構成では --prior-bundle と、それとは独立して保持された --prior-bundle-digest の両方を指定します。前回の履歴が省略または改変された場合は、フェイルクローズします。必須のレビュアーエビデンスが不足している場合、リリースの完全性はブロックされますが、通常のバンドル生成はブロックされません。生のスクリーンリーダーの読み上げ文言と、制限対象のトランスクリプトパスは通常のバンドルでは禁止されています。この境界を越えるのは、承認済みの件数、編集済みメタデータ、ダイジェストのみです。

下流のワークフローで該当する項目をゲートとして扱う場合に限り、--require-completeness automated、reviewer、または release を使用してください。有効でも不完全なバンドルは、診断用に引き続き出力されます。追加の終了コードは次のとおりです。

終了コード	意味
5	自動化エビデンスが不完全です。
6	レビュアーエビデンスが保留中、または無効です。
7	リリースエビデンスが不完全です。

既存の終了コード 0 から 4 の意味は変わりません。JSON コントラクトは、ランタイムと同じ場所にある evidence-bundle.schema.json、evidence-source.schema.json、evidence-scope.schema.json、screen-reader-method-cell.schema.json、および qualified-human-result.schema.json にあります。

無効なテンプレートから最初の保持済みバンドルを作成し、決定論的に再構成するまでの、利用者向けの手順については、作成するすべての入力のスキーマ準拠例を含むreferences/evidence-composition-adoption.mdをお読みください。

ビジュアルレビューのキャプチャ

capture-visual-review は、設定されたサーフェスと状態について、決定論的なスクリーンショットエビデンスを記録します。ランタイム設定で visualReview.enabled を true にする必要があります。

uv run scripts/runtime_a11y/__main__.py capture-visual-review \
  --config <path-to>/a11y-runtime.config.json \
  --run-root .copilot-tracking/accessibility/local-runs/<run-name>

• --run-root はエビデンスディレクトリを選択します。リポジトリルートを基準に解決され、.copilot-tracking/accessibility/local-runs 配下の子パスである必要があります。このルートの外側にあるパスと、ディレクトリを遡るセグメントは拒否されます。
• --run-root を省略すると、同じルート配下にタイムスタンプ付きの実行ディレクトリが割り当てられます。
• --visual-surface と --visual-state は、キャプチャ対象を特定の設定済み ID に絞り込みます。
• コマンドの対象となるサーバーは serveMode に従います。サーバーモードを参照してください。

サーバーモード

ランタイム設定の serveMode は、ハーネスが capture-visual-review 用のサーバーを管理するかどうかを決定します。

serveMode	動作
auto	設定されたループバックオリジンで正常なサーバーを再利用し、そうでなければ自身が所有するサーバーをビルドして起動し、その後停止します。
served	設定されたループバックオリジンで既に応答しているサーバーを必須とし、応答がない場合は期待されるオリジンと起動コマンドを示して失敗します。
external	サーバーのプローブも起動も行いません。設定されたターゲットに既に到達可能である必要があります。
off	サーバーのプローブも起動も行いません。

auto と served はループバックオリジンのみを受け付けます。ハーネスはリモートサーバーを管理したりヘルスプローブしたりしないためです。非ループバックのターゲットには依然として許可リストまたは --allow-external が必要で、external または off の場合にのみ有効です。

auto の場合、所有するサーバーを起動するとまずサイトがビルドされるため、自身でサーバーを起動しなければならないキャプチャは最初のスクリーンショットまでに数分かかります。設定されたオリジンでサーバーを起動したままにしておくと、そのコストを省略できます。これが再利用のパスです。

このリポジトリの Docusaurus サイトは http://127.0.0.1:3001 で auto に設定されており、これは Playwright のエンドツーエンドスイートが使用するのと同じ本番ビルドのオリジンです。本番ビルドに対してキャプチャすることで、視覚的な証拠を継続的インテグレーションが検証する内容と一致させ続けられます。

設定の概要

ハーネスは scripts/runtime_a11y/config-schema.json を読み込み、baseUrl、serveMode、allowlist、routes、surfaces、probeScoping などのフィールドを持つランタイム設定を想定しています。この設定は、プローブが実行するサーフェスとインタラクション状態を定義します。ランタイムガードは、ホストが許可リストに含まれているか、呼び出し元が --allow-external を指定しない限り、非ループバックのターゲットをブロックします。serveMode はビジュアルレビューキャプチャのサーバー所有権を制御します。詳細はサーバーモードで説明しています。

Real-NVDA ジャーニーは 3 つのキャプチャモードをサポートしています。

• single は、コマンドおよび設定されたセトル間隔の後に累積音声ログを読み取ります。
• clear-and-capture は、セトル間隔の前にそれ以前の音声をクリアしてから、累積ログを読み取ります。
• action は、既存の開始後の宣言型トリガーを Guidepup のアクションキャプチャでラップします。アサーションは actionSpeech または actionNormalizedSpeech を選択して、そのトリガーに帰属する出力のみを評価できます。

アクションキャプチャは Guidepup の 1 秒間の音声静止ウィンドウを待ちます。これは即時のインタラクション駆動型アナウンスには適していますが、任意の遅延更新には及ばず、NVDA が発しない音声を作り出すことはできません。それらのケースには single、clear-and-capture、アクセシビリティツリーの証拠、手動の AT 証拠を利用可能なままにしておいてください。アクションモードは、ジャーニーに triggerAfterDriverStart、宣言型トリガー、実際の Guidepup ドライバー、またはアクションキャプチャのサポートがない場合、フェイルクローズします。

プローブの一覧と妥当性マップ

現在、ハーネスには scripts/runtime_a11y/runner 配下の以下のプローブが含まれています。

WCAG および ARIA APG プローブ:

• probe-axe
• probe-keyboard-traversal
• probe-focus-visible
• probe-focus-obscured
• probe-live-region
• probe-aria-tree
• probe-widget-keyboard
• probe-reflow-resize
• probe-target-size
• probe-contrast
• probe-forced-colors
• probe-reduced-motion
• probe-structure-crawl
• probe-name-in-label
• probe-use-of-color (1.4.1)
• probe-text-spacing (1.4.12)
• probe-hover-focus (1.4.13)
• probe-link-purpose (2.4.4)
• probe-input-purpose (1.3.5)
• probe-forms (3.3.2、3.3.1/3.3.3 に情報提供)
• probe-context-change (3.2.1、3.2.2)
• probe-orientation (1.3.4)
• probe-audio-control (1.4.2)
• probe-timing (2.2.1)
• probe-zoom-blocker (1.4.4、1.4.10 に情報提供)
• probe-virtual-sr (仮想スクリーンリーダーの発話フレーズログから取得した 4.1.2 の名前/役割のアナウンス。1.3.1 に情報提供)
• probe-real-sr (Guidepup アダプターを介した実際の Windows NVDA アナウンスのアサーション。設定された期待値が存在し、AT スタックが利用可能な場合にのみ判定します)

非 WCAG の欠陥スキャンプローブ (フレームワーク defect-scan):

• probe-console-errors (コンソール/ページエラー)
• probe-broken-links (同一オリジンの 404)
• probe-dom-hygiene (重複 ID、正の tabindex、ランドマークの欠落/重複)
• probe-title-lang (空の title、無効な lang)

手法の妥当性は scripts/runtime_a11y/probe-criteria-map.json にエンコードされています。各エントリには、プローブが判定できる達成基準と、情報提供のみ可能な達成基準が記録されています。結果が妥当と見なされるのは、採用された手法がそのマッピングで許可されている場合のみです。

カバレッジエンジンの出力

scripts/runtime_a11y/matrix のマトリクスエンジンは、達成基準 x サーフェス x 状態のグリッドを展開し、更新を決定論的にマージし、人間が確認した検出事項を優先度の低い自動化よりも優先して保持します。フレームワーク別および全体の妥当なカバレッジ率を計算します。render-artifacts コマンドは、coverage-matrix-{repo-slug}.json、coverage-matrix-{repo-slug}.md、accessibility-results-{repo-slug}.earl.jsonld、manual-at-testplan-{repo-slug}.md、manual-at-testplan-{repo-slug}.yaml、accessibility-artifacts-{repo-slug}.json を含む決定論的なバンドルを出力します。

EARL (Evaluation and Report Language) JSON-LD エクスポートは、ACT Rules エコシステムや下流の VPAT または EAA レビューとの相互運用性のための正規化された結果コントラクトです。評価された各セルは、対象、達成基準、状態、手法、手法の妥当性、結果日、証拠を記録する 1 つの安定した earl:Assertion になります。採用された手法がその達成基準に情報提供するのみの結果は earl:cantTell となり、誤った earl:passed になることはありません。適用外のセルは earl:inapplicable となり、未評価のセルは省略されます。対になる手動プランには、人間が判定する手法を依然として必要とするセルが含まれ、証拠の書き戻し用に空の結果フィールドが提供されます。

公開 ARIA-AT と実行コントラクト

scripts/runtime_a11y/aria-at-catalog.json のカタログは、AT 向けケースを生成するための、リポジトリで文書化された信頼できる唯一の情報源です。出所を示すフィールドは厳格かつ不変です。各マッピングには、ローカルカタログのバージョン、正規の上流 URL、コミットに固定された上流 URL、およびレビュー済みの更新に使用した上流コミット SHA が記録されています。リポジトリは上流のアサーション表や文章をコピーせず、W3C と ARIA-AT の公式な意図を言い換え、生成された成果物で出典を引用しています。

現在の公開方針は意図的に保守的です。最初の 5 つのデフォルト（モーダルダイアログ、チェックボックス、選択のみ可能なコンボボックス、メニューボタン、タブ）は、これらのパターンで必要になることがある、より豊かな AT モードやクイックナビゲーションの意味を、現在の構造化されたコマンド境界では忠実にモデル化できないため、出典を伴う手動のみのマッピングです。実行時のオーバーライドで明示的な合成コントラクトテストを作成できますが、これらは常に合格判定に用いない候補エビデンスであり、アクセシビリティ適合性のエビデンスにはなりません。リゾルバーは、文書化された状態 -> サーフェス -> カタログのフォールバック順序を使用します。コマンドとアサーションはアトミックな配列として保存され、明示的な空配列を指定すると、そのケースの実行が意図的に無効になります。

不明なパターンは、偽の自動化合格判定にせず、汎用の手動ドラフトまたはプロジェクトでの詳細化を促すマーカーとして扱われます。同じ詳細度の候補が複数あり曖昧な場合は、レンダリングやドライバーの起動前に設定エラーとして扱われます。公開 CLI では、render-artifacts を任意のマッピング設定手順として公開し、生成された AT ケースの一覧表示、選択、実行、報告には run-at-plan をサポート対象の手順として公開しています。実ドライバー境界では、Guidepup を利用した Windows NVDA の自動化に加えて、手動のみの JAWS やその他のオペレーター主導のフローを現在サポートしています。合成実行は別のエビデンス経路であり、合格を主張することはありません。生成された手動プランは、共有の実スクリーンリーダーテスト手順書にリンクされたままです。一方、ケース固有のコマンドは生成されたプラン出力内にとどまり、マトリックスやカバレッジ成果物には書き戻されません。

生成された手動ケース、合成または実行によるエビデンス、ACT 形式の結果に関する推論、EARL の結果、および後続の有資格者によるレビューは、それぞれ異なるレイヤーです。公開ワークフローでは、文書化された CLI を使用して代表的なフィクスチャをレンダリングし、生成された 6 つの成果物を検査しますが、検査バンドルのゴールデン出力はコミットしません。

終了コード

• 0 は、プローブで検出事項が報告された場合も含め、ハーネスが正常に完了したことを示します。
• ゼロ以外の終了コードは、無効な設定、プローブの失敗、Node.js がない、ハーネスの依存関係がインストールされていない、ブラウザーのサポートがない、または対象がブロックされているなど、ハーネスのエラーを示します。

verify-intent は、利用側プロジェクトの CI が区別できるように、設計意図に関する 2 つのコードを追加します。

終了コード	意味	一般的な対応
3	ブロック対象の期待値が failed と判定された	意図のずれとして扱います。サーフェスが後退しています
4	ブロック対象の期待値が一度も評価されなかった	カバレッジのずれとして扱います。チェックが実行されていません

失敗したチェックと実行されなかったチェックでは必要な対応が異なるため、この 2 つは別々です。コードを 1 つにまとめると、カバレッジの不足がリグレッションとして扱われたり、何も報告されずに通過したりするおそれがあります。

ランタイム依存関係

ハーネスは、scripts/runtime_a11y 配下のスキル専用パッケージ（package.json とコミット済みの package-lock.json）から Node の依存関係を解決し、[email protected]、@axe-core/[email protected]、@guidepup/[email protected] を固定しています。また、@guidepup/[email protected] による実際の AT との統合は任意です。ハーネスの前提条件に記載のとおり、Node の依存関係と、別途管理される NVDA アセットをインストールしてください。プローブはその後、ローカルの node_modules から依存関係を解決します。CLI は node_modules がない場合、プローブの実行やサーバーの起動より前に、インストール方法を示して即座に終了します。

テスト

ハーネスのテストは 2 段階で構成されています。ブラウザーを使わない判定テストと純粋なヘルパーの単体テストは、node --test（リポジトリーのスクリプト test:node）で実行され、runner/_core.mjs の判定ロジック（たとえば virtualSrNameRoleStatus や liveRegionStatus）を検証します。tests/runtime_a11y/runner/probe-smoke/ のブラウザースモークテストでは、システムの Chrome を起動し、インラインフィクスチャに対して実際のキャプチャーパスを実行して、DOM から判定に至るまでのパイプラインを検証します。これには、名前のないコントロール、ライブリージョンの発火、強制カラーの計算済みスタイル、CDP のアクセシビリティノード構造が含まれます。これらは *.smoke.mjs という名前のため、デフォルトのブラウザーなし実行ではスキップされます。PR 検証では、CI が管理する npm run ci:test:a11y:smoke エントリーポイントを通じて実行されます。ローカルで再現するには、システムの Chrome とスキル専用の node_modules が必要です。

CI 回帰ゲート

対象プロジェクト向けのドキュメント優先の統合ポイントとして、コピーしてすぐ使えるワークフローテンプレート references/ci/accessibility-coverage.workflow-template.yml を使用します。対象プロジェクトで a11y-runtime.config.json をコミットし、テンプレートから呼び出せるビルド／サーブの手順を用意してから、対象リポジトリの GitHub Actions ワークフローディレクトリにコピーしてください。作成済みの *.intent.yaml レコードがある場合、設定ファイルまたは今回の実行結果がないと、テンプレートはフェイルクローズします。

このテンプレートは、システム Chrome のプロビジョニング、Node 24 と Python および uv のセットアップ、対象のビルド、設定可能なベース URL でのサーブ、そしてベンダー提供のスキルルートに固定した uv run --project を使ったハーネススクリプトのエントリーポイント実行により、Docusaurus のワークフローレシピを再現します。信頼性の高い中核プローブは常にブロック対象です。probe-axe、probe-dom-hygiene、probe-broken-links、probe-console-errors、probe-target-size、probe-contrast、probe-reflow-resize が該当します。静的解析だけでは情報を得るにとどまるクラスには、インタラクション状態とアナウンスのプローブ（probe-keyboard-traversal、probe-widget-keyboard、probe-live-region、probe-aria-tree、probe-virtual-sr、probe-real-sr）が適切な手法です。これらのブロック方針は、評価ティアごとのゲートの厳格さ で定義される A11Y_TIER の設定に従います。basic では参考情報として報告し、standard では段階的に厳格化し（A11Y_RATCHET_SURFACES に記載されたサーフェスでブロック）、comprehensive ではすべてのサーフェスでブロックします。use-of-color、hover-focus、link-purpose、name-in-label、focus-* など、残りのヒューリスティックプローブは情報提供用の結果として表示されます。これにより、導入当初はブロックせずに、その後の作業の指針として活用できます。プロジェクトが設定済みの期待アサーションと、サポートされている OS／AT スタックを通じて有効にしない限り、実スクリーンリーダーのプローブはデフォルトで参考情報として扱われます。プラットフォームまたは AT を利用できない場合は、合格や不合格を装わず candidate を返します。適応型レンダリングのクラスを決定的にカバーするには、対象プロジェクトで zoom-200、reflow-320、テキスト間隔の状態を a11y-runtime.config.json にコミットする必要があります。

references/ci/probe-spec-parity.md の対応関係リファレンスでは、各ランタイムプローブを既存の Docusaurus e2e spec のうち最も近いものに対応付け、同等の spec が現時点で存在しない箇所を示しています。

references/ci/act-rule-format.md のリファレンスでは、ハーネスのプローブ、生成されたテストケース、EARL の結果が W3C ACT Rules Format（適用可能性、期待値、合格／不合格／適用外）とどのように対応するかを説明しています。これにより、ACT Rules エコシステムや適合性レポートとの相互運用が可能になります。

デザインインテントの検証

利用するプロジェクトは、サーフェスで伝えるべき内容を宣言し、リリースされた内容が引き続きその宣言と一致するかを CI でチェックできます。この宣言は Design Intent Record であり、プロジェクト内の design-intent/<surface-id>.intent.yaml に人が作成してコミットします。各インテントには、サーフェスが何を、なぜ、誰に伝えるべきかが記され、すべての主張が名前付きのチェックにひも付けられます。

レコードの作成時やレビュー時には、references/design-intent/record-contract.md にある作成済みレコードのフィールド仕様を参照してください。このセクションでは検証について説明します。

このスキルでは、プローブ実行の結果をその宣言に照らして判定する手順を提供します。

呼び出し

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py verify-intent \
  --record design-intent/<surface-id>.intent.yaml \
  --results results.json

• --record は作成済みのレコードを指定します。宣言以外の目的で読み取られることはなく、書き換えられることもありません。
• --results は run-all の結果ドキュメントです。
• --out は出力パスを上書きします。デフォルトでは、レコードと同じ場所にある design-intent/.verification/<surface-id>.earl.json になります。

結果からアウトカムへの解決方法

結果行は、サーフェス、状態、結果を出力したプローブ、基準のすべてがレコードの宣言と一致する場合に、期待事項に一致します。プローブ間で基準の対象範囲が重複するため、結果を出力したプローブも結合条件の一部です。

状況	アウトカム	モード
一致したすべての基準に合格した	passed	automatic
一致したいずれかの基準に失敗した	failed	automatic
証拠は収集されたが、決定的ではない	cantTell	automatic
期待事項に一致する結果行がない	untested	automatic
期待事項が assert: custom を使用する	untested	manual

期待事項は、1つ以上の基準に対する1つの主張であるため、最も悪い基準のアウトカムが適用されます。実行で対象にならなかった期待事項は省略されず、untested として報告されます。これにより、チェックの欠落が暗黙のうちに見えなくなるのではなく、明示されます。

プローブが情報を与えるだけの基準を持つ期待事項は、通常の動作では cantTell に解決されます。これは想定どおりです。プローブは証拠を収集しましたが、主張の結論には至っていません。

custom の期待事項は、レコードに人間による override があるかどうかにかかわらず、untested を報告します。アダプターは、観測されたランタイムのアウトカムのみをアーティファクトに記録します。人間によるオーバーライドはレコード自体で引き続き権威を持ち、生成されたアーティファクトのアウトカムには統合されません。

契約上、解釈は2つの層に分かれており、生成されたアーティファクトは各アサーションについて両方の層を保持するようになりました。

• observedOutcome は、生成されたアーティファクトのフィールド outcome です。オーバーライドによって置き換えられることはありません。
• effectiveOutcome は、フェイルセーフの優先順位を適用した値です。観測結果または人間によるアウトカムが failed の場合は、いずれも failed になります。人間による passed は、untested、cantTell、inapplicable の場合にのみ確定します。それ以外では、観測されたアウトカムがそのまま適用されます。ゲートが適用するのはこの値です。
• overrideConflict は、観測されたアウトカムと作成者が指定したオーバーライドのアウトカムが両方とも passed または failed で、かつ異なる場合にのみ true になります。untested、cantTell、inapplicable の期待事項を確定させるオーバーライドは、文書化された用途であり、競合ではありません。

決定的な競合が発生した場合、フェイルクローズします。verify-intent は競合するアサーションごとに Warning: で始まる行を1行 stderr に書き出し、インテント、期待事項、観測されたアウトカム、オーバーライドのアウトカムを示し、競合する期待事項がブロック対象の場合は設計インテントのドリフトを返します。

同梱されている Python 検証ツールは、YAML の重複キーを拒否し、作成されたスキーマ全体を検証し、アーティファクトを書き込む前に、日付、ファイル名とランタイム設定のバインディング、識別子の重複、メソッドの組み合わせ、プローブの妥当性に関するセマンティックチェックを実施します。このリポジトリの PowerShell バリデーターは、ソースと生成されたアーティファクトの検証について、同じ契約を独立して適用します。

終了コード

• 0 — アーティファクトが書き込まれ、ブロック対象の期待事項に失敗はありません。
• 1 — レコードまたは結果ドキュメントの形式が不正です。何も書き込まれません。
• 2 — レコードまたは結果ドキュメントを読み取れませんでした。
• 3 — アーティファクトが書き込まれ、ブロック対象の期待事項に失敗しました。
• 4 — アーティファクトが書き込まれましたが、ブロック対象の期待事項が一度も評価されませんでした。

終了コード 3 と 4 は強制適用を示します。利用するプロジェクトの CI ステップは、他のコマンドと同様に、どちらかのゼロ以外の終了コードでビルドを失敗させます。実行結果を公開できるよう、アーティファクトは引き続き書き込まれます。どの期待事項をブロック対象にするかは、各期待事項の blocking フラグを通じてレコードが決定します。

グラフィックスと図のセマンティクスには、ランタイムプローブがありません。これらの期待事項は assert: custom を使用し、人間によるレビューを通じて解決されます。自動化で判断できることとできないことの境界については、Graphics ARIA and SVG-AAM reference を参照してください。

レビュー用レコードのレンダリング

レコードには、何を満たす必要があるかと、その確認方法が記されていますが、実装や提供範囲は含まれていません。YAML ではなく文章で確認したいレビュー担当者は、次のようにレンダリングできます。

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py project-intent \
  --record design-intent/<surface-id>.intent.yaml \
  --out handoff.md

出力は決定論的で、レコードにすでに記載されている内容のみをレンダリングします。分析や検証結果が追加されることはありません。説明対象のレコードとの食い違いを防ぐため、コミットせず、必要に応じて生成してください。--out を指定しない場合、Markdown は標準出力に出力されます。

使用上の注意

• 計画およびレビューワークフローでは、このスキルをデフォルトのアクセシビリティ用エントリーポイントとして扱ってください。
• エージェントや指示内で内部参照パスを重複させず、このスキルを通じてフレームワークやフェーズのガイダンスを参照してください。
• アクセシビリティスキャンから正規化された検出結果が必要な場合は、スキャナー CLI を使用してください。