accessibility · microsoft — Claude Code skill: what it does, how to install
A reference hub for WCAG 2.2, ARIA APG, Section 508 and EN 301 549 that also drives a six-phase Accessibility Planner from discovery to backlog handoff.
MIT ★ 1,627 updated 2026-10-25
npx skills add microsoft/hve-core --skill accessibility -a claude-codeWhat accessibility does
Agents call this skill by name and get back the right framework reference: WCAG 2.2, the ARIA Authoring Practices Guide, cognitive accessibility guidance, Section 508, EN 301 549, or the Graphics ARIA and SVG-AAM notes. A separate reference covers the assistive-technology announcement model for criteria such as WCAG 1.3.1 and 4.1.2.
The core piece is the Accessibility Planner, split into six phases keyed to state ids: discovery, framework selection, standards mapping, plan risk assessment, impact and evidence, and backlog handoff. A method-adequacy doctrine sits underneath all of this: it decides whether a static scanner result (axe, eslint-plugin-jsx-a11y) actually settles a criterion or merely flags it for a keyboard pass or an assistive-technology check.
The scanner component needs Python 3.11+ with uv, plus Node.js and network access to pull a pinned axe-core CLI build from the public npm registry.
What it helps with
- centralize WCAG 2.2, ARIA APG, Section 508 and EN 301 549 references in one place
- walk a feature through the six-phase Accessibility Planner
- tell which WCAG criteria a static scan can decide versus only inform
- build an evidence register and hand off work items with backlog gate checks
- catch faux semantics like fake headings or fake controls that scanners miss
Example prompts for the agent
- Run the Accessibility Planner on this feature and start the discovery phase
- Check which WCAG criteria the static scan actually decides versus just flags for an AT pass
- Build the evidence register and prepare work items for backlog handoff
How to install accessibility
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill accessibility -a claude-code2Manually: put the files in place
~/.claude/skills/accessibility/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/accessibility/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill accessibility -a codex2Manually: put the files in place
.agents/skills/accessibility/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill accessibility -a cursor2Manually: put the files in place
.cursor/skills/accessibility/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/hve-core .github/skills/accessibility/accessibility2Manually: put the files in place
.github/skills/accessibility/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill accessibility -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/hve-core --path .github/skills/accessibility/accessibilityManually: put the files in place
.devin/skills/accessibility/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about accessibility
How do I install accessibility in Claude Code?
Run npx skills add microsoft/hve-core --skill accessibility -a claude-code; the skill lands at ~/.claude/skills/accessibility/SKILL.md.
What does accessibility do?
It centralizes references to WCAG 2.2, ARIA APG, Section 508, EN 301 549 and related frameworks, and runs a six-phase Accessibility Planner from discovery through backlog handoff.
What does the built-in scanner need to run?
It needs Python 3.11+ with uv, plus Node.js and network access to fetch a pinned axe-core CLI build from npm.
Source text
SKILL.md · MIT
---
name: accessibility
description: "Consolidated accessibility skill entrypoint for WCAG 2.2, ARIA Authoring Practices, cognitive accessibility, Section 508, EN 301 549, design intent verification, and the Accessibility Planner workflow."
license: MIT
compatibility: "Requires Python 3.11+ and uv; the scanner additionally needs Node.js and network access to fetch the pinned axe-core CLI from the public npm registry."
user-invocable: false
metadata:
authors: "microsoft/hve-core"
spec_version: "1.0"
last_updated: "2026-10-02"
---
# Accessibility — Skill Entry
This skill is the canonical accessibility reference contract for HVE Core. Agents and instructions invoke this skill by name and rely on it to own framework reference resolution, phase guidance resolution, and the scanner CLI entrypoint.
## Framework references
* [WCAG 2.2](references/frameworks/wcag-22.md)
* [ARIA Authoring Practices Guide](references/frameworks/aria-apg.md)
* [Cognitive Accessibility Guidance](references/frameworks/coga.md)
* [Section 508](references/frameworks/section-508.md)
* [EN 301 549](references/frameworks/en-301-549.md)
* [Graphics ARIA and SVG-AAM](references/frameworks/graphics-aria-svg-aam.md)
Assessment reference (cross-cutting, not a conformance framework):
* [Assistive-technology announcement model](references/frameworks/at-announcement-model.md) — read this when deciding the announcement-class criteria (WCAG 1.3.1, 4.1.2, 4.1.3): what a screen-reader user should hear, and how to decide it with an accessibility-tree assertion or a manual AT pass.
## Accessibility Planner workflow
The Accessibility Planner runs six phases, each keyed to a state id:
1. Phase 1 — Discovery (`discovery`)
2. Phase 2 — Framework Selection (`framework-selection`)
3. Phase 3 — Standards Mapping (`standards-mapping`)
4. Phase 4 — Plan Risk Assessment (`plan-risk-assessment`)
5. Phase 5 — Impact and Evidence (`impact-evidence`)
6. Phase 6 — Backlog Handoff (`backlog-handoff`)
## Phase reference index
* Phase 1 — Discovery: [capture-coaching.md](references/phases/capture-coaching.md) — read this when running exploration-first capture questioning.
* Phase 2 — Framework Selection: [framework-selection.md](references/phases/framework-selection.md) — read this when choosing which frameworks and conformance level apply.
* Phase 3 — Standards Mapping: walk the [framework references](#framework-references) roll-up tables to emit `controlMappings`; consumed by Phase 5. No dedicated file — mapping is driven by the framework roll-ups.
* Phase 4 — Plan Risk Assessment: [capture-coaching.md](references/phases/capture-coaching.md) governs the questioning posture when escalation triggers reopen scoping; tier criteria are applied per the Accessibility Planner identity instructions and recorded as `riskClassification.tier`. No dedicated file — the accessibility risk surface is narrow enough to stay inline.
* Phase 5 — Impact and Evidence: [impact-assessment.md](references/phases/impact-assessment.md) — read this when building the evidence register, tradeoff log, and seed work-items.
* Phase 6 — Backlog Handoff: [backlog-handoff.md](references/phases/backlog-handoff.md) — read this when rendering work items and validating handoff gates.
## Method adequacy (decide vs inform)
Method adequacy is the doctrine that a verification method may only be recorded as satisfying a success criterion when that method can actually *decide* the criterion. A method that can observe a related signal but cannot confirm the user-facing outcome only *informs* the criterion; it raises or lowers suspicion but never closes it. This section is the canonical definition; the planner evidence register, the reviewer verdict logic, and the runtime probe harness all resolve adequacy through it.
The machine-readable adequacy source is [scripts/runtime_a11y/probe-criteria-map.json](scripts/runtime_a11y/probe-criteria-map.json). Each probe entry lists the criteria it `decides` and the criteria it only `informs`. A result counts as adequate only when the winning method appears in the `decides` list for that criterion and state.
### Failure classes and adequate methods
Accessibility defects generalize into five classes. Static analysis (axe, `eslint-plugin-jsx-a11y`, snapshot structure counts) can decide only the first class; the remaining four require an interaction-state probe or an assistive-technology (AT) pass to be decided rather than merely informed.
| Class | Representative WCAG SC | What static analysis can do | Adequate method to decide |
|--------------------------------|--------------------------------------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------|
| **Static-decidable structure** | 1.1.1, 1.4.3, 4.1.2 (name present), 2.4.2, 3.1.1 | Decide | axe / static scan |
| **Interaction behavior** | 2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11 | Inform only | Keyboard/interaction probe driving keys across `focus`/`open` states, or manual keyboard pass |
| **Announcement correctness** | 1.3.1, 4.1.2 (computed name/role), 4.1.3 | Inform only | Accessibility-tree assertion of computed name/role/live, or manual AT pass (Windows NVDA or human-led JAWS) |
| **Adaptive rendering** | 1.4.4, 1.4.10, 1.4.12, 2.4.11 | Inform only | Rendered probe at 200% zoom, 320px reflow, and text-spacing states |
| **Faux semantics** | 1.3.1 (faux headings), 2.4.3 (faux controls) | Cannot see | Heuristic source pass plus accessibility-tree assertion; no element exists for a rule engine to flag |
For the announcement class, the [assistive-technology announcement model](references/frameworks/at-announcement-model.md) specifies what the user should hear per criterion and how to decide it. For the interaction and faux-semantics classes, the [focus-management anti-pattern catalog](references/frameworks/aria-apg.md#focus-management-anti-patterns) enumerates the defects that pass a static scan yet break keyboard and screen-reader users.
### Adequacy rule
* A control in the interaction, announcement, adaptive-rendering, or faux-semantics classes cannot be recorded as fully satisfied on static evidence alone. Static evidence caps such a control at a partial state until an adequate method is attached.
* A criterion whose winning method only `informs` it is never a conformance verdict; it is a lead that routes to an adequate method or a manual pass.
* Preserve the adequacy determination alongside the status so downstream planners and reviewers do not re-promote an inadequately verified control.
This doctrine and its class taxonomy are repository-original content licensed under CC BY 4.0; the underlying success-criterion definitions remain with WCAG 2.2 as cited in [wcag-22.md](references/frameworks/wcag-22.md).
### Calibration is evidence quality, not a conformance verdict
Calibration establishes that the assistive-technology stack behaves as expected before its output is trusted. Its checkpoints record driver identity, profile fingerprint, and artifact hashes for a journey that passed.
A checkpoint is deliberately not a matrix input. Nothing in the coverage or outcome pipeline reads one, and that separation is intended rather than unfinished. A passing calibration says the harness was working; it does not say the surface satisfies a success criterion. Wiring checkpoints into coverage would turn a statement about the tool into a statement about the product.
If calibration evidence should ever influence coverage, that is new design work requiring its own review: it needs an explicit mapping from a journey to a criterion, surface, and state, and it must respect the same method-adequacy rules as any other evidence.
### Gate strictness by assessment tier
The enforcement posture for the interaction, announcement, adaptive-rendering, and faux-semantics classes graduates with the assessment depth tier recorded in `riskClassification.tier`, so the gate inherits the rigor a project opted into rather than applying one global switch:
* `basic` — the adequate-method probes (keyboard, widget-keyboard, live-region, aria-tree, virtual-sr) report **advisory** (warn-only); the always-decidable core probes still block.
* `standard` (default) — **ratchet**: the adequate-method probes block on new or changed surfaces and stay advisory over the existing backlog, so no new defect in these classes ships while legacy content is surfaced without freezing the project.
* `comprehensive` — the adequate-method probes **block** on every in-scope surface.
The always-decidable core probes (axe, DOM hygiene, broken links, console errors, target size, contrast, reflow/resize) block at every tier. The CI workflow template implements this dial through the `A11Y_TIER` and `A11Y_RATCHET_SURFACES` inputs; the Accessibility Reviewer applies the same graduation to its FAIL and PARTIAL verdicts.
## Tooling
The scanner CLI ([scripts/scan.py](scripts/scan.py)) wraps the Node-based axe-core scanner and normalizes its findings into a stable JSON shape.
### Prerequisites
* Python 3.11+ with [uv](https://docs.astral.sh/uv/) available on PATH.
* Node.js with `npx` available on PATH.
* Network access on first run so `npx` can fetch `@axe-core/cli`.
### Quick Start
```bash
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
```
Loopback HTTP(S) targets need no additional option. Every other remote host
requires either a matching, repeatable `--allow-host HOST` value or the broader
`--allow-external` confirmation. Local paths and local `file:` URIs must resolve
to existing regular files. Network shares, remote file authorities, directories,
missing files, credentials, leading-dash targets, and non-HTTP(S) remote schemes
are rejected before the axe CLI starts.
### Parameters Reference
| Parameter | Required | Default | Description |
|--------------------|----------|---------|----------------------------------------------------------------|
| `target` | Yes | — | Authorized HTTP(S) URL or existing regular local file to scan. |
| `--output` | No | stdout | Path to write the normalized JSON results. |
| `--allow-host` | No | none | Authorize one non-loopback HTTP(S) host; repeat as needed. |
| `--allow-external` | No | false | Confirm access to any non-loopback HTTP(S) host. |
Remote authorization applies to the initial scanner target only. It does not
constrain browser redirects, DNS address changes, subresources, WebSockets,
Service Workers, downloads, or other browser-derived requests. Run the scanner
only from a workstation whose network reach matches the target's trust level.
### Script Reference
* Entrypoint: [scripts/scan.py](scripts/scan.py)
* Output shape:
```json
{
"target": "<scanned target>",
"summary": {
"violations": 0,
"passes": 0,
"incomplete": 0,
"inapplicable": 0
},
"violations": [
{ "id": "", "impact": "", "description": "", "nodes": 0 }
]
}
```
* Exit codes:
* `0` — scan completed successfully.
* `1` — scan failed or returned invalid output.
* `2` — scanner unavailable (Node.js or `@axe-core/cli` missing).
### Troubleshooting
| Symptom | Likely cause | Action | Exit code |
|------------------------------------------|--------------------------------------------|------------------------------------------------------------------|-----------|
| `scanner unavailable` error | Node.js or `npx` not on PATH | Install Node.js so `npx` resolves, then re-run. | `2` |
| Long pause or download on first run | `npx` is fetching `@axe-core/cli` | Allow network access on the first run; later runs use the cache. | — |
| `Refusing to probe non-loopback host` | Remote host was not explicitly authorized | Add `--allow-host HOST` or confirm with `--allow-external`. | `2` |
| `Local scan target does not exist` | Local path or file URI cannot be resolved | Supply an existing regular local file, not a directory or share. | `2` |
| `scan failed or returned invalid output` | axe-core CLI errored or emitted non-JSON | Confirm the target URL or file is reachable and well-formed. | `1` |
| Empty `violations` but issues expected | Page rendered after the scan, or rules N/A | Confirm the target fully loads; check `summary.inapplicable`. | `0` |
### Mapping findings to frameworks
Each violation's `impact` is one of `minor`, `moderate`, `serious`, or `critical`. axe rule tags decode to WCAG success criteria by stripping the `wcag` prefix and inserting decimals:
| axe tag | WCAG success criterion |
|-----------|--------------------------|
| `wcag111` | 1.1.1 Non-text Content |
| `wcag143` | 1.4.3 Contrast (Minimum) |
WCAG success criteria are normative; the axe techniques that surface them are informative. Treat scanner output as evidence pointing at a criterion, not a conformance verdict.
### Runtime probe harness
The runtime probe harness ([scripts/runtime_a11y](scripts/runtime_a11y)) runs Playwright-based accessibility probes against a project-specific surface inventory and aggregates the results into a coverage matrix. For workflow orchestration, ask the user to run the manual-only `accessibility-coverage-matrix` skill (`/accessibility-coverage-matrix`); it is not model-invocable. Use the `Accessibility Surface Inventory` subagent as the canonical producer of the runtime config. Activate it by name; when it does not resolve, warn the user that the capability is unavailable and stop the dependent step.
#### Harness prerequisites
Complete these once before any runtime-harness command. They are separate from the `scan.py` prerequisites above.
* Python 3.11+ with [uv](https://docs.astral.sh/uv/) available on PATH.
* Node.js available on PATH, plus system Google Chrome, because the probes target `channel: 'chrome'`.
* Skill-local Node dependencies installed under [scripts/runtime_a11y](scripts/runtime_a11y). The CLI fails fast with an install hint when they are missing.
* Automated Windows NVDA runs additionally require the manifest-selected Guidepup NVDA asset. Machine setup and asset installation are separate actions from `npm ci`.
Install the harness dependencies from the `scripts/runtime_a11y` directory:
```bash
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci
```
```powershell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = '1'; npm ci
```
`PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` avoids downloading bundled browsers that the harness never uses.
For automated NVDA runs, prepare the Windows machine once, then install the asset selected by the skill-local Guidepup package. Run the asset command again after updating Guidepup:
```powershell
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
```
The commands configure the machine and write versioned assets to the Guidepup user cache. They are not part of ordinary dependency installation. Run the prerequisite-only probe before a calibration session:
```bash
uv run scripts/runtime_a11y/__main__.py run-calibration --config <path-to>/a11y-runtime.config.json --prerequisite-only
```
The preflight reports the skill-local library, manifest-selected NVDA asset, and any conflicting NVDA process independently. Do not start a personal NVDA instance before an automated run; the harness starts an isolated session and rejects an existing process.
Product-neutral screen-reader cases live in `scripts/runtime_a11y/screen-reader-cases.json`. A downstream binding supplies named routes, targets, states, and explicit execution recipes. Catalog digest drift, missing target closure, duplicate identities, unsupported commands, secret-bearing binding keys, and inferred actions fail before browser startup.
Use repeatable `run-calibration --journey <id>` arguments for an authorized live subset. Run the downstream integrity recipe before product cases and keep real NVDA advisory/manual. For deterministic evidence, use `run-all --probe <probe-id>` with surface/state filters or a reviewed `probeScoping` configuration; ordinary `run-all` must not be treated as permission to start a real screen reader.
#### Invocation
Run the harness through its script entrypoint. Invoke it from the skill root, which is the directory holding `pyproject.toml`, so uv resolves the skill's own environment. This matches the invocation convention used by `scan.py` and the other Python skills, and it needs no `PYTHONPATH`.
```bash
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
```
To run from any other working directory, pin the skill as the uv project and use the same script path:
```bash
uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py run-all --config a11y-runtime.config.json --out results.json
```
* `--config` resolves relative to the current working directory.
* `--out` writes the aggregated JSON document to disk.
* `--base-url` overrides the configured base URL. It must remain a loopback origin unless the host is allowlisted or `--allow-external` is supplied.
* `--trace` captures Playwright traces and screenshots.
* `--allow-external` confirms intentional probing of a non-loopback host.
* `render-artifacts` turns a rendered matrix JSON document into the complete coverage evidence bundle.
#### Evidence bundle composition
`compose-evidence` combines downstream-owned catalogs, cadence scope, run context, normalized source envelopes, state proofs, and optional qualified-reviewer supplements into one deterministic evidence bundle. It is separate from `render-artifacts`: rendering creates coverage, EARL, and manual-plan views from a matrix, while composition creates a revision-bound trust envelope across evidence producers.
The command requires explicit input paths and never infers product scope, Git state, time, retention, branch policy, or a release verdict. A consuming project owns those decisions. The composer validates artifact bytes beneath `--artifact-root`, preserves conflicts and quarantined results, and always emits non-attestation metadata. Automation, reviewer evidence, and release evidence have separate completeness states.
For pull requests, a valid initial bundle may report reviewer evidence as pending. A qualified reviewer can later provide a privacy-minimized, digest-bound supplement and registry snapshot for deterministic recomposition against the prior bundle. Recomposition supplies both `--prior-bundle` and its independently retained `--prior-bundle-digest`; omission or mutation of prior history fails closed. Missing required reviewer evidence blocks release completeness, not ordinary bundle production. Raw screen-reader phrases and restricted transcript paths are forbidden in ordinary bundles; only approved counts, redacted metadata, and digests cross this boundary.
Use `--require-completeness automated`, `reviewer`, or `release` only when the downstream workflow intends that dimension to gate. Valid incomplete bundles are still written for diagnosis. The additional exits are:
| Exit code | Meaning |
|-----------|------------------------------------------|
| `5` | Automated evidence is incomplete. |
| `6` | Reviewer evidence is pending or invalid. |
| `7` | Release evidence is incomplete. |
Existing exits `0` through `4` retain their meanings. The JSON contracts live beside the runtime at `evidence-bundle.schema.json`, `evidence-source.schema.json`, `evidence-scope.schema.json`, `screen-reader-method-cell.schema.json`, and `qualified-human-result.schema.json`.
For a complete adopter path from an inactive template to a first retained bundle and deterministic recomposition, including schema-valid examples for every authored input, read [references/evidence-composition-adoption.md](references/evidence-composition-adoption.md).
#### Visual review capture
`capture-visual-review` records deterministic screenshot evidence for the configured surfaces and states. It requires `visualReview.enabled` to be `true` in the runtime config.
```bash
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` selects the evidence directory. It resolves relative to the repository root and must land on a child path inside `.copilot-tracking/accessibility/local-runs`. Paths outside that root, and traversal segments, are rejected.
* Omitting `--run-root` allocates a timestamped run directory beneath that same root.
* `--visual-surface` and `--visual-state` narrow the capture to specific configured ids.
* The server the command targets follows `serveMode`. See [Server modes](#server-modes).
#### Server modes
`serveMode` in the runtime config decides whether the harness manages a server for `capture-visual-review`.
| `serveMode` | Behavior |
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `auto` | Reuses a healthy server at the configured loopback origin, otherwise builds and starts one it owns and stops afterward. |
| `served` | Requires a server already answering the configured loopback origin, and fails with the expected origin and start command when none responds. |
| `external` | Never probes or starts a server. The configured target must already be reachable. |
| `off` | Never probes or starts a server. |
`auto` and `served` accept only loopback origins, because the harness will not manage or health-probe a remote server. A non-loopback target still requires the allowlist or `--allow-external`, and is only valid with `external` or `off`.
Under `auto`, starting an owned server builds the site first, so a capture that has to start its own server takes several minutes before the first screenshot. Leave a server running at the configured origin to skip that cost, which is the reuse path.
The Docusaurus site in this repository is configured for `auto` at `http://127.0.0.1:3001`, which is the same production-build origin the Playwright end-to-end suite uses. Capturing against the production build keeps visual evidence consistent with what continuous integration verifies.
#### Config summary
The harness loads [scripts/runtime_a11y/config-schema.json](scripts/runtime_a11y/config-schema.json) and expects a runtime config with fields such as `baseUrl`, `serveMode`, `allowlist`, `routes`, `surfaces`, and `probeScoping`. The config defines the surfaces and interaction states the probes execute. A runtime guard blocks non-loopback targets unless the host is allowlisted or the caller supplies `--allow-external`. `serveMode` controls server ownership for visual review capture, described under [Server modes](#server-modes).
Real-NVDA journeys support three capture modes:
* `single` reads the cumulative speech log after commands and the configured settle interval.
* `clear-and-capture` clears earlier speech before the settle interval, then reads the cumulative log.
* `action` wraps an existing post-start declarative trigger with Guidepup action capture. Assertions can select `actionSpeech` or `actionNormalizedSpeech` to evaluate only output attributed to that trigger.
Action capture waits for Guidepup's one-second speech quiet window. It is appropriate for immediate interaction-driven announcements but does not extend to arbitrary delayed updates and cannot create speech that NVDA does not emit. Keep `single`, `clear-and-capture`, accessibility-tree evidence, and manual AT evidence available for those cases. Action mode fails closed when the journey lacks `triggerAfterDriverStart`, a declarative trigger, a real Guidepup driver, or action-capture support.
#### Probe inventory and adequacy map
The harness currently includes these probes under [scripts/runtime_a11y/runner](scripts/runtime_a11y/runner):
WCAG and ARIA APG probes:
* `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, informs 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, informs 1.4.10)
* `probe-virtual-sr` (4.1.2 name/role announcement captured from a virtual screen reader's spoken-phrase log; informs 1.3.1)
* `probe-real-sr` (real Windows NVDA announcement assertions through a Guidepup adapter; only decides when configured expectations are present and the AT stack is available)
Non-WCAG defect-scan probes (framework `defect-scan`):
* `probe-console-errors` (console/page errors)
* `probe-broken-links` (same-origin 404s)
* `probe-dom-hygiene` (duplicate ids, positive tabindex, missing/duplicate landmarks)
* `probe-title-lang` (empty title, invalid `lang`)
Method adequacy is encoded in [scripts/runtime_a11y/probe-criteria-map.json](scripts/runtime_a11y/probe-criteria-map.json). Each entry records which criteria a probe can decide and which criteria it can only inform. A result only counts as adequate when the winning method is allowed by that mapping.
#### Coverage engine outputs
The matrix engine in [scripts/runtime_a11y/matrix](scripts/runtime_a11y/matrix) expands the criterion x surface x state grid, merges updates deterministically, and preserves human-confirmed findings over lower-priority automation. It computes adequate-coverage percentages by framework and overall. The `render-artifacts` command emits a deterministic bundle containing `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`, and `accessibility-artifacts-{repo-slug}.json`.
The EARL (Evaluation and Report Language) JSON-LD export is the normalized results contract for interoperability with the ACT Rules ecosystem and downstream VPAT or EAA review. Each evaluated cell becomes one stable `earl:Assertion` that records subject, criterion, state, method, method adequacy, result date, and evidence. A result whose winning method only informs its criterion is `earl:cantTell`, never a false `earl:passed`. Inapplicable cells are `earl:inapplicable`; unevaluated cells are omitted. The paired manual plans contain cells that still require a human-deciding method and provide blank result fields for evidence writeback.
#### Public ARIA-AT and execution contract
The catalog in [scripts/runtime_a11y/aria-at-catalog.json](scripts/runtime_a11y/aria-at-catalog.json) is the repository's documented source of truth for generated AT-oriented cases. Its provenance fields are strict and immutable: each mapping records a local catalog version, a canonical upstream URL, a commit-pinned upstream URL, and the upstream commit SHA used for the reviewed refresh. The repository does not copy upstream assertion tables or prose; it paraphrases official W3C and ARIA-AT intent and cites the source in the generated artifacts.
The current public posture is intentionally conservative. The five starter defaults (modal dialog, checkbox, select-only combobox, menu button, and tabs) are citation-bearing manual-only mappings because the richer AT-mode and quick-navigation semantics that these patterns can require are not faithfully modeled by the current structured command boundary. Runtime overrides may create explicit synthetic contract tests, but those are always non-pass candidate evidence and never accessibility conformance evidence. The resolver uses the documented fallback order of state -> surface -> catalog; commands and assertions are stored as atomic arrays, and an explicit empty array intentionally disables execution for a given case.
Unknown patterns remain generic manual drafts or project-refinement markers rather than a fake automation pass. E...
© microsoft · MIT · microsoft/hve-core
Similar skills
All skills for Frontend and UI →accessibility by other authors comes first.