Generated banner for Accessibility
Generated logo for Accessibility

Accessibility

MicrosoftOfficialPublished by Microsoft

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
  • Has scripts

From the author

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.
— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The accessibility skill provides a structured approach to managing accessibility requirements across the development lifecycle. It includes a six-phase Accessibility Planner workflow, a command-line scanner for static analysis, and a runtime probe harness for verifying interaction-based accessibility. The skill enforces a doctrine of method adequacy, ensuring that verification methods are only used to decide criteria they are capable of observing, and supports the generation of evidence bundles for review.

What it does

  • Provides a six-phase workflow for accessibility discovery, planning, and backlog handoff.
  • Wraps the axe-core CLI to perform static accessibility scans on web pages.
  • Executes Playwright-based runtime probes to verify interaction behavior and screen-reader announcements.
  • Enforces method adequacy rules to distinguish between static findings and interaction-based verification.
  • Generates deterministic evidence bundles for accessibility reviews and reporting.
  • Maps findings to WCAG 2.2, ARIA Authoring Practices, and other accessibility standards.

When to use it

  • When planning accessibility requirements for a new project or feature.
  • When performing automated static scans of web content for common accessibility defects.
  • When verifying complex interaction behaviors that static analysis cannot fully evaluate.
  • When building an evidence register to track accessibility conformance across development phases.

Advantages

  • Standardizes accessibility verification across different projects and teams.
  • Prevents over-reliance on static analysis for complex interaction-based criteria.
  • Supports tiered enforcement postures to match project risk and maturity.
  • Integrates with standard CI workflows for automated accessibility testing.

Usage examples

“Scan my local file index.html for accessibility violations.”
The skill runs the axe-core scanner against the file and outputs a normalized JSON report of findings.
“Run the accessibility runtime probes for my project.”
The skill executes the configured Playwright probes and aggregates the results into a coverage matrix.

Install

Documentation by Microsoft

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

Assessment reference (cross-cutting, not a conformance framework):

  • Assistive-technology announcement model — 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 — read this when running exploration-first capture questioning.

  • Phase 2 — Framework Selection: framework-selection.md — read this when choosing which frameworks and conformance level apply.

  • Phase 3 — Standards Mapping: walk the 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 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 — read this when building the evidence register, tradeoff log, and seed work-items.

  • Phase 6 — Backlog Handoff: 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. 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.

ClassRepresentative WCAG SCWhat static analysis can doAdequate method to decide
Static-decidable structure1.1.1, 1.4.3, 4.1.2 (name present), 2.4.2, 3.1.1Decideaxe / static scan
Interaction behavior2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11Inform onlyKeyboard/interaction probe driving keys across focus/open states, or manual keyboard pass
Announcement correctness1.3.1, 4.1.2 (computed name/role), 4.1.3Inform onlyAccessibility-tree assertion of computed name/role/live, or manual AT pass (Windows NVDA or human-led JAWS)
Adaptive rendering1.4.4, 1.4.10, 1.4.12, 2.4.11Inform onlyRendered probe at 200% zoom, 320px reflow, and text-spacing states
Faux semantics1.3.1 (faux headings), 2.4.3 (faux controls)Cannot seeHeuristic source pass plus accessibility-tree assertion; no element exists for a rule engine to flag

For the announcement class, the assistive-technology announcement model 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 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.

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) wraps the Node-based axe-core scanner and normalizes its findings into a stable JSON shape.

Prerequisites
  • Python 3.11+ with 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
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
ParameterRequiredDefaultDescription
targetYes—Authorized HTTP(S) URL or existing regular local file to scan.
--outputNostdoutPath to write the normalized JSON results.
--allow-hostNononeAuthorize one non-loopback HTTP(S) host; repeat as needed.
--allow-externalNofalseConfirm 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

  • Output shape:

    {
      "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
SymptomLikely causeActionExit code
scanner unavailable errorNode.js or npx not on PATHInstall Node.js so npx resolves, then re-run.2
Long pause or download on first runnpx is fetching @axe-core/cliAllow network access on the first run; later runs use the cache.—
Refusing to probe non-loopback hostRemote host was not explicitly authorizedAdd --allow-host HOST or confirm with --allow-external.2
Local scan target does not existLocal path or file URI cannot be resolvedSupply an existing regular local file, not a directory or share.2
scan failed or returned invalid outputaxe-core CLI errored or emitted non-JSONConfirm the target URL or file is reachable and well-formed.1
Empty violations but issues expectedPage rendered after the scan, or rules N/AConfirm 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 tagWCAG success criterion
wcag1111.1.1 Non-text Content
wcag1431.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) 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 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. 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:

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci
$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:

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:

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.

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:

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 codeMeaning
5Automated evidence is incomplete.
6Reviewer evidence is pending or invalid.
7Release 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.

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.

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

serveMode in the runtime config decides whether the harness manages a server for capture-visual-review.

serveModeBehavior
autoReuses a healthy server at the configured loopback origin, otherwise builds and starts one it owns and stops afterward.
servedRequires a server already answering the configured loopback origin, and fails with the expected origin and start command when none responds.
externalNever probes or starts a server. The configured target must already be reachable.
offNever 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 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.

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:

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. 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 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 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. Equally specific ambiguity is treated as a configuration error before rendering or driver startup. The public CLI exposes render-artifacts as an optional mapping configuration step and run-at-plan as the supported path for listing, selecting, executing, and reporting generated AT cases. The real-driver boundary currently supports Guidepup-backed Windows NVDA automation plus manual-only JAWS and other operator-led flows; synthetic execution is a separate evidence channel and never claims a pass. The generated manual plans stay linked to the shared real screen reader testing runbook, while case-specific commands remain inside the generated plan output rather than being written back into the matrix or coverage artifacts.

The generated manual cases, synthetic or real execution evidence, ACT-style result reasoning, EARL outcomes, and later qualified-human review are distinct layers. The public workflow renders representative fixtures through the documented CLI and inspects the six generated artifacts, but it does not commit golden outputs for the inspection bundle.

Exit codes
  • 0 indicates the harness completed successfully, even when probes reported findings.

  • Non-zero exit codes indicate a harness error such as invalid config, a failed probe, missing Node.js, uninstalled harness dependencies, missing browser support, or a blocked target.

verify-intent adds two design-intent codes that a consuming project's CI can distinguish:

Exit codeMeaningTypical response
3A blocking expectation resolved failedTreat as intent drift; the surface regressed
4A blocking expectation was never evaluatedTreat as coverage drift; the check did not run

The two are separate because a failed check and an unrun check call for different responses. Reusing one code would let missing coverage read as a regression, or pass silently.

Runtime dependencies

The harness resolves its Node dependencies from a skill-local package under scripts/runtime_a11y (package.json plus committed package-lock.json), pinning [email protected], @axe-core/[email protected], @guidepup/[email protected], and optional real-AT integration through @guidepup/[email protected]. Install the Node dependencies and the separately managed NVDA asset as described under Harness prerequisites. The probes then resolve their dependencies from the local node_modules; the CLI fails fast with an install hint when node_modules is absent, before it probes or starts any server.

Testing

The harness is tested in two tiers. Browserless verdict and pure-helper unit tests run under node --test (repo script test:node) and cover the decision logic in runner/_core.mjs (for example virtualSrNameRoleStatus and liveRegionStatus). Browser smoke tests under tests/runtime_a11y/runner/probe-smoke/ launch system Chrome and drive the real capture path against inline fixtures to prove the DOM-to-verdict pipeline, including nameless controls, live-region firing, forced-color computed styles, and CDP accessibility-node structure. They are named *.smoke.mjs so the default browserless run skips them. PR Validation runs them through the CI-owned npm run ci:test:a11y:smoke entry point. Local reproduction requires system Chrome and the skill-local node_modules.

CI regression gate

Use the ready-to-copy workflow template at references/ci/accessibility-coverage.workflow-template.yml as the documentation-first integration point for a target project. Copy it into the target repository's GitHub Actions workflow directory only after the target project commits an a11y-runtime.config.json and has a build/serve path that the template can invoke. Once authored *.intent.yaml records exist, the template fails closed if the config or current-run results are missing.

The template mirrors the Docusaurus workflow recipe by provisioning system Chrome, setting up Node 24 plus Python and uv, building the target, serving it under a configurable base URL, and running the harness script entrypoint with uv run --project pinned at the vendored skill root. The core high-confidence probes always block: probe-axe, probe-dom-hygiene, probe-broken-links, probe-console-errors, probe-target-size, probe-contrast, and probe-reflow-resize. The interaction-state and announcement probes (probe-keyboard-traversal, probe-widget-keyboard, probe-live-region, probe-aria-tree, probe-virtual-sr, probe-real-sr) are the adequate method for the classes static analysis only informs, and their blocking posture follows the A11Y_TIER dial defined under Gate strictness by assessment tier: basic reports them advisory, standard ratchets (blocking on the surfaces listed in A11Y_RATCHET_SURFACES), and comprehensive blocks them everywhere. The remaining heuristic probes such as use-of-color, hover-focus, link-purpose, name-in-label, and focus-* are surfaced as informational results so they can guide follow-up work without blocking initial adoption. The real-screen-reader probe stays advisory by default unless a project opts into it through configured expected assertions and a supported OS/AT stack; it returns candidate when the platform or AT is unavailable rather than pretending a pass or failure. Decisive coverage of the adaptive-rendering class depends on the target committing the zoom-200, reflow-320, and text-spacing states in its a11y-runtime.config.json.

The parity reference at references/ci/probe-spec-parity.md maps each runtime probe to the closest existing Docusaurus e2e spec and highlights gaps where no equivalent spec currently exists.

The references/ci/act-rule-format.md reference documents how the harness's probes, generated test cases, and EARL results align to the W3C ACT Rules Format (applicability, expectation, passed/failed/inapplicable) so results interoperate with the ACT Rules ecosystem and conformance reporting.

Design intent verification

A consuming project can declare what a surface must convey and have CI check that what shipped still matches. The declaration is a Design Intent Record, human-authored and committed at design-intent/<surface-id>.intent.yaml in that project. Each intent states what the surface must communicate, why, and for whom, and binds every claim to a named check.

The authored-record field contract is in references/design-intent/record-contract.md. Read it when authoring or reviewing a record. This section covers verification.

This skill supplies the step that turns a probe run into a verdict against that declaration.

Invocation
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 is the authored record. It is never read for anything but its declarations and never rewritten.

  • --results is a results document from run-all.

  • --out overrides the output path, which defaults to design-intent/.verification/<surface-id>.earl.json beside the record.

How results resolve to outcomes

A result row matches an expectation when its surface, state, emitting probe, and criterion all match what the record declares. Because criterion coverage overlaps across probes, the emitting probe is part of the join.

SituationOutcomeMode
Every matched criterion passedpassedautomatic
Any matched criterion failedfailedautomatic
Evidence gathered but not decisivecantTellautomatic
No result row matched the expectationuntestedautomatic
The expectation uses assert: customuntestedmanual

An expectation is one claim over one or more criteria, so the worst criterion outcome governs. Expectations the run did not cover report untested rather than being omitted, which keeps a missing check visible instead of silently absent.

Expectations whose criteria a probe only informs resolve to cantTell in normal operation. That is expected: the probe gathered evidence without settling the claim.

A custom expectation reports untested whether or not the record carries a human override. The adapter records only observed runtime outcome in the artifact. Human override remains authoritative in the record itself and is not merged into the generated artifact outcome.

Interpretation is two-layered by contract, and the generated artifact now carries both layers on every assertion:

  • observedOutcome is the generated artifact field outcome. An override never replaces it.

  • effectiveOutcome applies fail-safe precedence. Either an observed or human failed outcome yields failed; human passed settles only untested, cantTell, or inapplicable; otherwise the observed outcome remains. This is the value the gate applies.

  • overrideConflict is true only when the observed and authored override outcomes are each passed or failed and differ. An override that settles an untested, cantTell, or inapplicable expectation is the documented use, not a conflict.

A conclusive conflict fails closed. verify-intent writes one Warning: line to stderr for each conflicting assertion, names the intent, expectation, observed outcome, and override outcome, and returns design-intent drift when the conflicting expectation blocks.

The shipped Python verifier rejects duplicate YAML keys, validates the complete authored schema, and enforces semantic checks for dates, filename and runtime-config bindings, duplicate identifiers, method pairing, and probe adequacy before writing an artifact. This repository's PowerShell validator independently enforces the same contract for source and generated-artifact validation.

Exit codes
  • 0 — the artifact was written and no blocking expectation failed.

  • 1 — the record or results document was malformed. Nothing is written.

  • 2 — the record or results document could not be read.

  • 3 — the artifact was written and a blocking expectation failed.

  • 4 — the artifact was written and a blocking expectation was never evaluated.

Exit codes 3 and 4 are enforcement signals. A consuming project's CI step fails its build on either non-zero exit, exactly as it would for any other command. The artifact is still written so the run can publish it. Which expectations block is the record's decision, through each expectation's blocking flag.

Graphics and diagram semantics have no runtime probe. Those expectations use assert: custom and resolve through human review; see the Graphics ARIA and SVG-AAM reference for the boundary between what automation can decide and what it cannot.

Rendering a record for review

A record states what must be true and how it is checked, but carries no implementation or delivery scope. Reviewers who want prose rather than YAML can render one:

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

Output is deterministic and renders only what the record already says, adding no analysis and no verification results. Generate it on demand rather than committing it, so it cannot drift from the record it describes. Without --out the Markdown goes to stdout.

Usage notes

  • Treat this skill as the default accessibility entrypoint for planning and review workflows.

  • Resolve framework and phase guidance through this skill instead of duplicating its internal reference paths in agents or instructions.

  • Use the scanner CLI when you need normalized findings from an accessibility scan.

Files

references/frameworks/coga.md


title: COGA framework reference description: Making Content Usable for People with Cognitive and Learning Disabilities (COGA) design patterns used as an accessibility assessment knowledge base

COGA framework reference

This SKILL.md is the entrypoint for the Making Content Usable for People with Cognitive and Learning Disabilities (COGA) framework skill used by the Accessibility Planner and the Accessibility Skill Assessor subagent.

COGA is a Working Group Note published by the W3C Cognitive Accessibility Task Force. Unlike the normative WCAG 2.2 success criteria, COGA provides informative design guidance: 53 design patterns are organised into eight user-need objectives that together cover the accessibility needs of people with cognitive, learning, neurological, and age-related impairments. Each pattern describes a user need, suggested design approaches, and evaluation considerations. COGA patterns frequently complement WCAG 2.2 criteria, since several user needs (consistent navigation, clear labels, error prevention, focus support) are partially expressed across both standards.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, https://www.w3.org/TR/coga-usable/.

Licensing posture

COGA is published under the W3C Document License as a Working Group Note. This skill paraphrases pattern intent rather than reproducing the source verbatim, in line with the paraphrase-preferred posture defined in accessibility-license-posture.instructions.md. Every per-objective reference file cites the canonical W3C URL anchor for each pattern, and any future verbatim quotation must carry the W3C copyright attribution line specified in that instruction file. When that instruction content is unavailable, apply the paraphrase-only posture stated here and do not quote the source verbatim, because the required attribution line cannot be confirmed.

Pattern roll-up

The table below lists every COGA pattern grouped by objective. The Reference column links into the per-objective reference file using an anchor that matches the section header for that pattern. Total: 53 patterns across 8 objectives.

#PatternUser needDesign patternsAssessment heuristicsReference
1.1Make the Purpose of Your Page ClearClear PurposeDescriptive titles, headers, signposts, top-of-page summaryConfirm purpose is visible without scrolling; titles match the taskobjective-clear-purpose.md#control-make-the-purpose-of-your-page-clear
1.2Use a Familiar Hierarchy and DesignClear OperationConventional layout, predictable patterns, standard navigationConfirm controls live where users expect; avoid novel patternsobjective-clear-purpose.md#control-use-a-familiar-hierarchy-and-design
1.3Use a Consistent Visual DesignClear OperationConsistent layout, colours, typography, control placementConfirm same controls render identically across pagesobjective-clear-purpose.md#control-use-a-consistent-visual-design
1.4Make Each Step ClearClear OperationOne concept per step, step indicators, progress feedbackConfirm each step has a clear heading and progress is visibleobjective-clear-purpose.md#control-make-each-step-clear
1.5Clearly Identify Controls and Their UseClear OperationConventional control shapes, visible focus, descriptive labelsConfirm interactive elements look interactive; labels describe outcomeobjective-clear-purpose.md#control-clearly-identify-controls-and-their-use
1.6Make the Relationship Clear Between Controls and the Content They AffectClear OperationProximity, grouping, visible references, aria-controlsConfirm users can predict what a control will changeobjective-clear-purpose.md#control-make-the-relationship-clear-between-controls-and-the-content-they-affect
1.7Use Icons that Help the UserUse SymbolsFamiliar icons, paired text labels, consistent meaningConfirm icons have text labels and follow industry conventionsobjective-clear-purpose.md#control-use-icons-that-help-the-user
2.1Make it Easy to Find the Most Important Tasks and Features of the SiteFindabilityProminent placement, above-the-fold key actions, clear entry pointsConfirm primary tasks appear without scrolling on common viewportsobjective-find-help.md#control-make-it-easy-to-find-the-most-important-tasks-and-features-of-the-site
2.2Make the Site Hierarchy Easy to Understand and NavigateFindabilityLogical groupings, predictable menus, breadcrumbsConfirm sitemap depth is shallow; navigation paths are stableobjective-find-help.md#control-make-the-site-hierarchy-easy-to-understand-and-navigate
2.3Use a Clear and Understandable Page StructureFindabilityDistinct page regions, headings, whitespace, dividersConfirm regions are visually distinct and use landmark rolesobjective-find-help.md#control-use-a-clear-and-understandable-page-structure
2.4Make it Easy to Find the Most Important Actions and Information on the PageFindabilityProminent CTAs, summary at top, key info above the foldConfirm primary actions are visually emphasised and reachable quicklyobjective-find-help.md#control-make-it-easy-to-find-the-most-important-actions-and-information-on-the-page
2.5Break Media into ChunksFindabilitySegmented video, chapter markers, summariesConfirm long media has chapter navigation or transcripts with anchorsobjective-find-help.md#control-break-media-into-chunks
2.6Provide SearchFindabilitySite search, spell-check, suggestions, recent queriesConfirm search exists and tolerates typos and synonymsobjective-find-help.md#control-provide-search
3.1Use Clear and Understandable LanguageClear MeaningPlain language, defined terms, simple vocabularyConfirm reading level matches audience; jargon is defined inlineobjective-clear-meaning.md#control-use-clear-and-understandable-language
3.2Use Familiar WordsClear MeaningCommon words, audience-appropriate vocabularyConfirm uncommon words have a glossary entry or definitionobjective-clear-meaning.md#control-use-familiar-words
3.3Use Simple Sentence StructureClear MeaningShort sentences, active voice, one idea per sentenceConfirm sentences are short and avoid embedded clausesobjective-clear-meaning.md#control-use-simple-sentence-structure
3.4Use Headings and SectionsClear MeaningHierarchical headings, scannable sectionsConfirm headings are nested correctly and convey topicobjective-clear-meaning.md#control-use-headings-and-sections
3.5Use ListsClear MeaningBulleted or numbered lists, short list itemsConfirm enumerable content is presented as a list rather than proseobjective-clear-meaning.md#control-use-lists
3.6Keep Text SuccinctClear MeaningShort paragraphs, summaries, removal of fillerConfirm content is trimmed to essentials; long pages have summariesobjective-clear-meaning.md#control-keep-text-succinct
3.7Use Clear, Unambiguous Formatting and PunctuationClear MeaningStandard punctuation, avoid all-caps, avoid italics for emphasisConfirm formatting is consistent and avoids cognitive ambiguityobjective-clear-meaning.md#control-use-clear-unambiguous-formatting-and-punctuation
3.8Separate Each InstructionClear MeaningOne instruction per line, numbered steps, clear separationConfirm multi-step tasks are split into discrete numbered stepsobjective-clear-meaning.md#control-separate-each-instruction
3.9Use White SpacingClear MeaningGenerous margins, line height, spacing between blocksConfirm density is low enough that elements do not crowd each otherobjective-clear-meaning.md#control-use-white-spacing
3.10Ensure Foreground Content is not Obscured by BackgroundClear MeaningHigh contrast, no busy backgrounds behind textConfirm text contrast meets WCAG and backgrounds do not interfereobjective-clear-meaning.md#control-ensure-foreground-content-is-not-obscured-by-background
3.11Explain Implied ContentClear MeaningSpell out idioms, expand abbreviations, define referencesConfirm content does not assume cultural or contextual knowledgeobjective-clear-meaning.md#control-explain-implied-content
3.12Provide Alternatives for Numerical ConceptsClear MeaningVisualisations, comparisons, plain-language equivalentsConfirm numbers and percentages have non-numeric alternativesobjective-clear-meaning.md#control-provide-alternatives-for-numerical-concepts
3.13Support Different ModalitiesClear MeaningText, image, audio, video alternativesConfirm critical content is reachable via at least two modalitiesobjective-clear-meaning.md#control-support-different-modalities
4.1Ensure Controls and Content Do Not Move UnexpectedlyError PreventionStable layouts, no auto-shifts, predictable insertionsConfirm targets remain stable while users interact with the pageobjective-error-prevention-recovery.md#control-ensure-controls-and-content-do-not-move-unexpectedly
4.2Let Users Go BackError PreventionBack button works, undo for actions, no trap pagesConfirm browser back and explicit back navigation always workobjective-error-prevention-recovery.md#control-let-users-go-back
4.3Notify Users of Fees and Charges at the Start of a TaskError PreventionUpfront pricing disclosure, hidden-fee avoidanceConfirm all costs are disclosed before any commitment is madeobjective-error-prevention-recovery.md#control-notify-users-of-fees-and-charges-at-the-start-of-a-task
4.4Design Forms to Prevent MistakesError PreventionMinimal fields, clear labels, format examples, inline validationConfirm forms reduce required input and validate as users typeobjective-error-prevention-recovery.md#control-design-forms-to-prevent-mistakes
4.5Make it Easy to Undo Form ErrorsError PreventionSaved drafts, retained input on error, undo affordancesConfirm partial form data persists after a validation failureobjective-error-prevention-recovery.md#control-make-it-easy-to-undo-form-errors
4.6Use Clear Visible LabelsError PreventionPersistent visible labels, no placeholder-only labelsConfirm labels remain visible after the user typesobjective-error-prevention-recovery.md#control-use-clear-visible-labels
4.7Use Clear Step-by-step InstructionsError PreventionNumbered steps, one action per step, examplesConfirm multi-step flows have explicit step indicators and examplesobjective-error-prevention-recovery.md#control-use-clear-step-by-step-instructions
4.8Accept Different Input FormatsError PreventionFlexible date, phone, address parsingConfirm common input formats are accepted without strict masksobjective-error-prevention-recovery.md#control-accept-different-input-formats
4.9Avoid Data Loss and TimeoutsError PreventionNo arbitrary timeouts, autosave, timeout warningsConfirm no required rapid response; timeouts are warned and extendableobjective-error-prevention-recovery.md#control-avoid-data-loss-and-timeouts
4.10Provide FeedbackError PreventionConfirmation messages, status updates, undo promptsConfirm every user action produces visible or audible feedbackobjective-error-prevention-recovery.md#control-provide-feedback
4.11Help the User Stay SafeError PreventionWarnings before risky actions, confirmation promptsConfirm destructive or costly actions require confirmation and are reversibleobjective-error-prevention-recovery.md#control-help-the-user-stay-safe
4.12Use Familiar Metrics and UnitsError PreventionLocale-appropriate units, conversions, plain labelsConfirm units match user locale or provide conversionsobjective-error-prevention-recovery.md#control-use-familiar-metrics-and-units
5.1Help Users FocusFocusMinimise distractions, prioritise one task at a timeConfirm pages do not present competing concurrent demands on attentionobjective-supports-attention.md#control-help-users-focus
5.2Make Short Critical PathsFocusFew steps to complete core tasks, streamlined flowsConfirm primary tasks complete in the smallest practical number of stepsobjective-supports-attention.md#control-make-short-critical-paths
5.3Avoid Too Much ContentFocusLimit on-screen items, three to six functions, brief contentConfirm visible content is bounded and avoids dense paragraphsobjective-supports-attention.md#control-avoid-too-much-content
6.1Ensure Processes Do Not Rely on MemoryMemoryPersistent information, repeated context across stepsConfirm users do not need to recall data from prior screensobjective-minimise-memory-load.md#control-ensure-processes-do-not-rely-on-memory
6.2Let Users Avoid Navigating Voice MenusMemoryText alternative to voice IVR, skip-prompts, quick keysConfirm voice or phone flows have text equivalents or shortcutsobjective-minimise-memory-load.md#control-let-users-avoid-navigating-voice-menus
6.3Do Not Rely on User Calculations or Memorising InformationMemoryProvide calculated values, avoid memorisation for securityConfirm calculations are done for the user; auth does not require recall puzzlesobjective-minimise-memory-load.md#control-do-not-rely-on-user-calculations-or-memorising-information
7.1Clearly State the Results and Disadvantages of Actions, Options, and SelectionsHelpOutcome descriptions, warnings about consequencesConfirm each choice explains what it does and what changesobjective-feedback-confirmation.md#control-clearly-state-the-results-and-disadvantages-of-actions-options-and-selections
7.2Provide Help for Forms and Non-standard ControlsHelpInline help, examples, password rules, control-specific docsConfirm complex inputs have inline accessible helpobjective-feedback-confirmation.md#control-provide-help-for-forms-and-non-standard-controls
7.3Make It Easy to Find Help and Give FeedbackHelpPersistent help link, multiple support channelsConfirm help is reachable from every page and offers multiple channelsobjective-feedback-confirmation.md#control-make-it-easy-to-find-help-and-give-feedback
7.4Provide Help with DirectionsHelpStep-by-step guidance, wayfinding, tooltipsConfirm tasks include clear contextual directions and visual aidsobjective-feedback-confirmation.md#control-provide-help-with-directions
7.5Provide RemindersHelpReminders for recurring tasks, confirmation of important actionsConfirm scheduled or repeated tasks support reminder hooksobjective-feedback-confirmation.md#control-provide-reminders
8.1Let Users Control When the Content Moves or ChangesAdaptUser-initiated motion, pause controls, no auto-launching pop-upsConfirm animation and auto-rotation have user-accessible controlsobjective-user-control.md#control-let-users-control-when-the-content-moves-or-changes
8.2Enable APIs and ExtensionsAdaptCompatible with assistive add-ons, password managers, simplifiersConfirm pages do not block accessibility-enhancing browser extensionsobjective-user-control.md#control-enable-apis-and-extensions
8.3Support SimplificationAdaptSimplified-view toggle, three to six core functions in simplified modeConfirm a low-complexity alternative view is available where practicalobjective-user-control.md#control-support-simplification
8.4Support a Personalised and Familiar InterfaceAdaptCustomisable layout, colours, terminology, system-preference respectConfirm user preferences are honoured and persisted across visitsobjective-user-control.md#control-support-a-personalised-and-familiar-interface

Assessment heuristics

Per-pattern assessment heuristics, design pattern detail, and scope notes live inside the per-objective reference files in references/. The Accessibility Skill Assessor subagent consumes the appropriate objective-<slug>.md#control-<pattern-slug> section when evaluating a finding against a specific COGA pattern.

Cross-skill use is the common case: a COGA finding usually cites both the pattern reference here and the most closely related WCAG 2.2 success criterion in wcag-22. For example, a page that auto-rotates a carousel without a pause control is cited against objective-user-control.md#control-let-users-control-when-the-content-moves-or-changes (for the COGA user-control pattern) and ../wcag-22/references/guideline-2-2.md#sc-2-2-2 (for the WCAG 2.2.2 Pause, Stop, Hide requirement).

Skill layout

  • SKILL.md — this file (skill entrypoint and 53-row roll-up table).

  • references/ — one markdown file per COGA objective. Each file contains a paraphrased description of every pattern within the objective, a Design patterns list of implementation approaches, an Assessment heuristics list for evaluation, and a canonical W3C source URL anchor.

Objective 3 - Use Clear and Understandable Content

Objective 3 covers patterns that make written content readable, scannable, and unambiguous. The user need is "Clear Meaning": users with cognitive, learning, and language-related disabilities benefit from plain language, familiar vocabulary, simple sentence structure, clear formatting, generous whitespace, and alternative modalities for content that is hard to convey in text alone.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 3, https://www.w3.org/TR/coga-usable/#objective-3.

control-use-clear-and-understandable-language

Control 3.1 Use Clear and Understandable Language

Content must be written at a reading level appropriate to the audience. Technical jargon, marketing prose, and formal register exclude many readers. Plain language increases comprehension for all users and is essential for users with cognitive and language-related disabilities.

Design patterns:

  • Write at a reading level appropriate to the audience.

  • Avoid jargon unless the audience uses it; define technical terms inline.

  • Use familiar, everyday vocabulary.

  • Prefer concrete examples over abstract descriptions.

Assessment heuristics:

  • Confirm the reading level matches the intended audience using a readability metric.

  • Confirm jargon is either defined inline or linked to a glossary.

  • Confirm examples accompany abstract concepts.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-familiar-words

Control 3.2 Use Familiar Words

Word choice affects comprehension as much as sentence structure. Using familiar synonyms in place of formal or technical terms expands the audience that can read the content without external aids.

Design patterns:

  • Prefer common words over rare ones (for example, "use" instead of "utilise").

  • Maintain a glossary for terms that must be technical.

  • Use the same word for the same concept throughout a document.

  • Test vocabulary with members of the target audience.

Assessment heuristics:

  • Confirm uncommon words are linked to or defined alongside a glossary.

  • Confirm a single term is used consistently for a single concept.

  • Confirm the page does not require an external dictionary to understand its core content.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-simple-sentence-structure

Control 3.3 Use Simple Sentence Structure

Long sentences with embedded clauses force readers to hold multiple ideas in working memory. Short sentences in active voice, with one idea per sentence, dramatically improve comprehension.

Design patterns:

  • Keep sentences short; aim for fewer than 20 words.

  • Use active voice rather than passive.

  • Express one idea per sentence.

  • Avoid nested clauses, parenthetical asides, and complex conditionals.

Assessment heuristics:

  • Confirm sentence length stays within plain-language guidance.

  • Confirm passive voice is used only when the actor is unknown or irrelevant.

  • Confirm sentences do not embed multiple conditions or qualifiers.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-headings-and-sections

Control 3.4 Use Headings and Sections

Headings let users scan a page and jump to the section they need. Without headings, users must read every paragraph to find what they want. Hierarchical headings convey structure to both sighted readers and assistive technology users.

Design patterns:

  • Divide long content into named sections with headings.

  • Use hierarchical heading levels (<h1> through <h6>) that reflect content structure.

  • Keep heading text concise and descriptive.

  • Provide a table of contents for long documents.

Assessment heuristics:

  • Confirm pages have a single <h1> and a logical heading hierarchy.

  • Confirm heading text accurately describes the section beneath it.

  • Confirm long documents include a navigable table of contents.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-lists

Control 3.5 Use Lists

Enumerable content is easier to scan and remember when presented as a list rather than as prose. Numbered lists imply order; bulleted lists imply a collection.

Design patterns:

  • Present sets of items, steps, or options as lists.

  • Use numbered lists for ordered sequences and bulleted lists for unordered collections.

  • Keep list items short and parallel in structure.

  • Avoid burying enumerable content in prose paragraphs.

Assessment heuristics:

  • Confirm enumerable content is marked up as <ul> or <ol> rather than as run-on prose.

  • Confirm list items follow a consistent grammatical structure.

  • Confirm ordered processes use numbered lists rather than bullets.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-keep-text-succinct

Control 3.6 Keep Text Succinct

Long paragraphs and verbose prose impose a cognitive cost. Trim content to essentials, use summaries for long pages, and let users drill into detail only if they want it.

Design patterns:

  • Trim filler, redundancy, and marketing language.

  • Place a summary at the top of long pages.

  • Provide an expand-on-demand mechanism for optional detail.

  • Prefer concise prose over exhaustive elaboration.

Assessment heuristics:

  • Confirm long pages open with a brief summary of the key points.

  • Confirm content uses progressive disclosure for optional detail.

  • Confirm paragraphs are short, typically three to five sentences or fewer.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-clear-unambiguous-formatting-and-punctuation

Control 3.7 Use Clear, Unambiguous Formatting and Punctuation

Inconsistent or unusual formatting introduces ambiguity. All-caps text is harder to read, italics reduce legibility, and idiosyncratic punctuation can confuse screen readers. Standard, conservative formatting supports comprehension.

Design patterns:

  • Use sentence case for body text and headings.

  • Avoid setting body text in all caps or italics.

  • Use standard punctuation; avoid stylised dashes and quotation marks where simpler equivalents work.

  • Apply formatting consistently across the document.

Assessment heuristics:

  • Confirm body text and headings use sentence case.

  • Confirm all caps is reserved for short labels (such as acronyms).

  • Confirm punctuation rendering is consistent and predictable.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-separate-each-instruction

Control 3.8 Separate Each Instruction

When multiple instructions are merged into a single sentence or paragraph, users struggle to identify or sequence the actions. Each instruction must stand on its own line or numbered step.

Design patterns:

  • Present each instruction on its own line or numbered step.

  • Use one verb per step.

  • Avoid combining setup, action, and follow-up in a single sentence.

  • Number steps when order matters.

Assessment heuristics:

  • Confirm instructions are presented as discrete steps rather than embedded in prose.

  • Confirm each step contains a single action.

  • Confirm steps are numbered when sequence is important.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-use-white-spacing

Control 3.9 Use White Spacing

Whitespace is not wasted space. Generous margins, line height, and spacing between sections help users locate content, parse structure, and rest their eyes. Dense layouts overwhelm readers who already struggle with visual processing.

Design patterns:

  • Apply generous line height (typically 1.5 or greater for body text).

  • Leave generous spacing between sections and around interactive elements.

  • Use margins to separate content blocks visually.

  • Avoid full-width prose; constrain text columns to comfortable reading widths.

Assessment heuristics:

  • Confirm body text has a line height of at least 1.5.

  • Confirm text columns stay within a comfortable reading width (typically 60 to 80 characters).

  • Confirm sections are visually separated by whitespace rather than only by borders.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-ensure-foreground-content-is-not-obscured-by-background

Control 3.10 Ensure Foreground Content is not Obscured by Background

Text placed over photographs, gradients, or busy patterns is hard to read even at high contrast ratios. Backgrounds must not compete with foreground content.

Design patterns:

  • Place body text on plain or near-plain backgrounds.

  • When text overlays images, apply an overlay or shadow to ensure consistent contrast.

  • Avoid placing text over animated or rotating backgrounds.

  • Test foreground readability at the worst-case point of the background.

Assessment heuristics:

  • Confirm text contrast meets WCAG 2.2 SC 1.4.3 across the full surface of the background.

  • Confirm overlays are applied where text sits on imagery.

  • Confirm text does not overlap with animated backgrounds.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-explain-implied-content

Control 3.11 Explain Implied Content

Idioms, abbreviations, cultural references, and metaphors exclude readers who do not share the relevant background. Spelling out the meaning the first time a reference appears keeps the content accessible.

Design patterns:

  • Expand abbreviations on first use.

  • Replace idioms with plain language or explain them inline.

  • Avoid culture-specific references unless the audience is known to share the culture.

  • Provide definitions or links for specialised terminology.

Assessment heuristics:

  • Confirm abbreviations have an explicit expansion on first use.

  • Confirm idiomatic language is replaced or annotated.

  • Confirm cultural references are explained when used.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-provide-alternatives-for-numerical-concepts

Control 3.12 Provide Alternatives for Numerical Concepts

Numbers, percentages, and statistics are abstract. Many users struggle to interpret them without context. Visualisations, plain-language equivalents, and concrete comparisons make numeric information meaningful.

Design patterns:

  • Pair numbers with plain-language equivalents (for example, "1 in 4" alongside "25 percent").

  • Provide visualisations (charts, infographics) alongside numeric tables.

  • Use comparisons to convey scale ("about the size of a soccer field").

  • Avoid relying solely on percentages or large numbers without context.

Assessment heuristics:

  • Confirm key statistics have a plain-language or visual equivalent.

  • Confirm percentages are accompanied by absolute counts when feasible.

  • Confirm comparisons are provided to convey scale.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

control-support-different-modalities

Control 3.13 Support Different Modalities

Some users read text well; some understand pictures better; some prefer audio or video. Content delivered through multiple modalities reaches more users without requiring them to adapt.

Design patterns:

  • Provide images, diagrams, or video alongside written instructions.

  • Provide audio narration alongside text where feasible.

  • Ensure each modality is independently comprehensible.

  • Avoid requiring users to consume content in a specific modality.

Assessment heuristics:

  • Confirm critical content is reachable via at least two modalities (text plus image, text plus audio, or video plus transcript).

  • Confirm each modality conveys the full message rather than partial information.

  • Confirm modality alternatives are equally discoverable.

Source: https://www.w3.org/TR/coga-usable/#objective-3.

Objective 1 - Help Users Understand What Things Are and How to Use Them

Objective 1 covers patterns that make the purpose of a page, the role of each control, and the relationship between controls and their effects immediately clear. The user need is "Clear Purpose" and "Clear Operation": users with cognitive and learning disabilities benefit when sites use predictable, consistent layouts, conventional control shapes, and familiar iconography so that recognition replaces the need for problem-solving.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 1, https://www.w3.org/TR/coga-usable/#objective-1.

control-make-the-purpose-of-your-page-clear

Control 1.1 Make the Purpose of Your Page Clear

The user must be able to tell within a few seconds what a page is for and what tasks it supports. Pages that bury their purpose in marketing copy or assume context from prior navigation exclude users who land on the page directly, who navigate with assistive technology, or who struggle with extended reading. A short, plain-language purpose statement near the top of the page makes the page self-describing.

Design patterns:

  • Provide a descriptive page title that matches the user's task vocabulary.

  • Place a short purpose statement or summary near the top of the page.

  • Use prominent, descriptive headings that signpost the main sections.

  • Avoid splash screens, marketing carousels, or pre-content overlays that delay the user.

Assessment heuristics:

  • Confirm the page purpose is visible without scrolling on common viewports.

  • Confirm the <title> element matches the visible top-of-page heading or summary.

  • Confirm landmark structure (<main>, <nav>, <header>) is present so assistive technology users can skip directly to the primary content.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-use-a-familiar-hierarchy-and-design

Control 1.2 Use a Familiar Hierarchy and Design

Users with cognitive disabilities rely on prior experience to navigate. When a site uses a layout that diverges from established conventions, every interaction becomes a learning task. Conventional placement of navigation, search, account controls, and footer information lets users transfer skills learned elsewhere.

Design patterns:

  • Place primary navigation at the top or left of the page.

  • Place search in a conventional location such as the top right.

  • Place account, login, and shopping cart controls where users expect to find them on similar sites.

  • Avoid inventing new interaction patterns when an established pattern would serve.

Assessment heuristics:

  • Compare the page layout against three to five comparable sites in the same domain and confirm key controls live in conventional positions.

  • Confirm primary navigation appears in the same location on every page in the site.

  • Confirm novel patterns are accompanied by inline guidance the first time they appear.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-use-a-consistent-visual-design

Control 1.3 Use a Consistent Visual Design

Visual consistency reduces cognitive load by letting users recognise rather than relearn each control. When the same action looks different across pages, users must re-evaluate every interaction. Consistent colour, typography, iconography, and control shapes turn the interface into a learnable system.

Design patterns:

  • Define a small palette and apply it consistently across pages.

  • Use the same shape, size, and styling for the same control across the site.

  • Reserve specific colours for specific meanings (for example, red for destructive actions) and apply them consistently.

  • Maintain a consistent typographic hierarchy.

Assessment heuristics:

  • Confirm the same button type (primary, secondary, destructive) renders identically across pages.

  • Confirm icons used in multiple places carry the same meaning everywhere.

  • Confirm typography hierarchy is consistent across templates.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-make-each-step-clear

Control 1.4 Make Each Step Clear

Multi-step processes overwhelm users when several decisions are presented at once or when it is not obvious where the user currently sits in the flow. Each step must have a clear heading describing the current task, must avoid mixing unrelated decisions, and must indicate progress so the user can pace themselves.

Design patterns:

  • Break long tasks into single-concept steps with clear headings.

  • Include a progress indicator that shows current step and total steps.

  • Place a brief summary of completed steps so users can review without going back.

  • Avoid combining unrelated decisions in a single step.

Assessment heuristics:

  • Confirm each step has a heading naming the current task.

  • Confirm a progress indicator is visible on every step.

  • Confirm users can review previous steps without losing their place.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-clearly-identify-controls-and-their-use

Control 1.5 Clearly Identify Controls and Their Use

Controls must look like controls. A flat, decorative design where buttons are indistinguishable from text or where links are hidden in body copy increases the time and effort required to find interactive elements. Visual affordances, descriptive labels, and clear focus indicators help users locate and operate controls.

Design patterns:

  • Style buttons and links so they are visually distinct from non-interactive text.

  • Use descriptive labels that say what the control does rather than generic verbs such as "click here".

  • Provide a strong visible focus indicator.

  • Avoid relying on hover-only affordances since touch users cannot hover.

Assessment heuristics:

  • Confirm interactive elements have visual cues (colour, underline, button shape) distinguishing them from static content.

  • Confirm control labels describe the outcome of activation.

  • Confirm focus indicators are visible and meet the non-text contrast threshold.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-make-the-relationship-clear-between-controls-and-the-content-they-affect

Control 1.6 Make the Relationship Clear Between Controls and the Content They Affect

When activating a control changes something on the page, the user must be able to predict and locate the change. Hidden side effects, distant updates, or unclear bindings between filters and results disorient users and risk leaving important changes unnoticed.

Design patterns:

  • Place controls adjacent to the content they affect.

  • Use visible grouping (cards, borders, whitespace) to associate controls with their targets.

  • Use aria-controls and live regions to convey relationships and updates programmatically.

  • Provide a visible confirmation when a control changes distant content.

Assessment heuristics:

  • Confirm the user can predict, from looking at the control, which area of the page it will change.

  • Confirm filter controls update results immediately and visibly, with a textual or aria-live confirmation.

  • Confirm controls that affect distant content (such as a filter that updates a list below the fold) provide an announcement or scroll cue.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

control-use-icons-that-help-the-user

Control 1.7 Use Icons that Help the User

Icons help recognition only when they are familiar and consistently meaningful. Novel or culturally specific icons exclude users who do not share the reference. Icons paired with text labels combine the speed of recognition with the precision of text.

Design patterns:

  • Use widely understood, conventional icons (for example, magnifying glass for search, gear for settings).

  • Pair every icon with a text label unless the icon is universally recognised.

  • Apply consistent meaning to each icon across the site.

  • Avoid using icons as the sole indicator of state or action.

Assessment heuristics:

  • Confirm each icon either has a visible text label or, where space is constrained, an accessible name via aria-label or visually hidden text.

  • Confirm icon meaning is consistent across the site.

  • Confirm uncommon icons are accompanied by inline text the first time they appear.

Source: https://www.w3.org/TR/coga-usable/#objective-1.

Objective 4 - Help Users Avoid Mistakes and Know How to Correct Them

Objective 4 covers patterns that prevent errors before they occur and that help users recover quickly when errors do occur. The user need is "Error Prevention": users with cognitive and learning disabilities are disproportionately affected by error-prone interfaces, unforgiving forms, time pressure, hidden costs, and unexpected layout shifts. Designs that anticipate mistakes and offer painless recovery support all users.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 4, https://www.w3.org/TR/coga-usable/#objective-4.

control-ensure-controls-and-content-do-not-move-unexpectedly

Control 4.1 Ensure Controls and Content Do Not Move Unexpectedly

Layout shifts caused by deferred content loading, rotating banners, or pop-ups disorient users and cause mis-clicks. Targets must remain stable while users interact with the page.

Design patterns:

  • Reserve space for asynchronous content so the layout does not shift when it loads.

  • Avoid auto-rotating content in primary interaction areas.

  • Avoid inserting content above the current scroll position after the page has loaded.

  • Provide user controls (pause, dismiss) for any non-essential motion.

Assessment heuristics:

  • Confirm Cumulative Layout Shift remains low during page load and interaction.

  • Confirm content inserted asynchronously appears in reserved space.

  • Confirm rotating or moving content does not interfere with users while they are interacting nearby.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-let-users-go-back

Control 4.2 Let Users Go Back

Users must be able to back out of any step without losing data or being trapped. Browser back, in-app back buttons, and undo affordances must all work reliably.

Design patterns:

  • Make the browser back button work without losing state.

  • Provide in-app back buttons on multi-step flows.

  • Provide undo for destructive actions.

  • Avoid pages that trap the user with no way out.

Assessment heuristics:

  • Confirm the browser back button works on every page and preserves user input.

  • Confirm multi-step flows include an explicit back affordance.

  • Confirm destructive actions are reversible or require confirmation.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-notify-users-of-fees-and-charges-at-the-start-of-a-task

Control 4.3 Notify Users of Fees and Charges at the Start of a Task

Hidden fees, late-stage upsells, and surprise charges at checkout exploit users who have already invested effort and feel committed. All costs must be disclosed at the start so users can make an informed decision.

Design patterns:

  • Disclose all fees, taxes, and charges at the start of a task.

  • Show running totals throughout the flow.

  • Avoid revealing additional charges only at the final confirmation step.

  • Be explicit about subscriptions, renewals, and cancellation terms.

Assessment heuristics:

  • Confirm the total price is visible before the user begins committing actions.

  • Confirm any fee added late in the flow is highlighted and explained.

  • Confirm subscription terms (price, frequency, cancellation) are visible before sign-up.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-design-forms-to-prevent-mistakes

Control 4.4 Design Forms to Prevent Mistakes

Forms are a common source of frustration. Reducing the number of required fields, providing clear labels and format examples, and validating input inline prevents most mistakes before they happen.

Design patterns:

  • Ask only for information that is strictly required.

  • Provide clear, persistent labels for every field.

  • Show format examples alongside fields that require specific formats.

  • Validate input inline as the user types or moves between fields.

Assessment heuristics:

  • Confirm forms ask only for necessary fields.

  • Confirm format examples appear next to fields with specific format requirements.

  • Confirm validation provides actionable, polite messages.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-make-it-easy-to-undo-form-errors

Control 4.5 Make it Easy to Undo Form Errors

When a form fails validation, the user's input must be preserved. Forcing the user to re-enter data after a validation failure compounds frustration and increases the chance of further errors.

Design patterns:

  • Preserve all user input across validation failures.

  • Highlight errors precisely without clearing valid fields.

  • Provide clear instructions for fixing each error.

  • Offer autosave for long forms.

Assessment heuristics:

  • Confirm partial form data persists after a validation failure.

  • Confirm error messages identify the field, the problem, and the fix.

  • Confirm long forms autosave or offer a manual save option.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-use-clear-visible-labels

Control 4.6 Use Clear Visible Labels

Placeholder text is not a label. Once the user begins typing, placeholder labels disappear, leaving the user with no reminder of what the field expects. Persistent visible labels are essential.

Design patterns:

  • Provide persistent visible labels above or beside each form field.

  • Avoid using placeholder text as the only label.

  • Use clear, plain-language labels that say what the field expects.

  • Keep the label visible after the user enters data.

Assessment heuristics:

  • Confirm every form field has a persistent visible label.

  • Confirm labels remain visible after the user enters data.

  • Confirm labels describe the expected input rather than restating the placeholder.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-use-clear-step-by-step-instructions

Control 4.7 Use Clear Step-by-step Instructions

Multi-step instructions must be presented as discrete numbered steps with concrete examples. Burying steps in paragraphs forces users to parse the prose to extract the sequence.

Design patterns:

  • Present multi-step tasks as numbered steps.

  • Provide a concrete example for each step where helpful.

  • Show progress through the steps.

  • Avoid combining multiple actions in a single step.

Assessment heuristics:

  • Confirm multi-step processes use numbered steps rather than prose.

  • Confirm each step contains a single action and an optional example.

  • Confirm a progress indicator shows current step and total steps.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-accept-different-input-formats

Control 4.8 Accept Different Input Formats

Strict input masks reject valid data formatted differently from what the form expects. Phone numbers, dates, addresses, and credit card numbers should be accepted in any common format and normalised behind the scenes.

Design patterns:

  • Accept multiple common formats for phone numbers, dates, currency, and addresses.

  • Strip non-numeric characters from numeric fields before validating.

  • Avoid input masks that reject valid characters.

  • Normalise data server-side rather than rejecting it client-side.

Assessment heuristics:

  • Confirm phone, date, and credit card fields accept common formatting variants.

  • Confirm whitespace and punctuation are stripped rather than rejected.

  • Confirm rejection messages identify the actual issue, not the format mismatch.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-avoid-data-loss-and-timeouts

Control 4.9 Avoid Data Loss and Timeouts

Timeouts that discard user input penalise users who take longer to read, type, or decide. Where security or technical constraints require a timeout, the user must be warned and given the chance to extend it.

Design patterns:

  • Avoid arbitrary timeouts on forms or session.

  • Autosave user input continuously.

  • Warn the user before a timeout expires and offer an extension.

  • Preserve user input even if a session expires.

Assessment heuristics:

  • Confirm forms do not impose time limits unless strictly required.

  • Confirm timeout warnings appear with sufficient time for the user to respond.

  • Confirm user input is preserved across session timeouts where possible.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-provide-feedback

Control 4.10 Provide Feedback

Every user action must produce immediate visible or audible feedback. Silent interfaces leave users unsure whether their action succeeded, prompting repeated attempts and accidental duplicates.

Design patterns:

  • Provide a visible response to every user action.

  • Use live regions to announce status changes to assistive technology.

  • Confirm completion of long-running actions.

  • Distinguish success, warning, and error feedback by colour, icon, and text.

Assessment heuristics:

  • Confirm every interactive control produces visible or audible feedback within 100 milliseconds of activation.

  • Confirm status changes are announced via aria-live regions where appropriate.

  • Confirm feedback messages are distinct by category (success, warning, error).

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-help-the-user-stay-safe

Control 4.11 Help the User Stay Safe

Destructive or costly actions must require confirmation. Where possible, actions should be reversible. Users with cognitive disabilities are especially vulnerable to interfaces that punish accidental clicks.

Design patterns:

  • Require explicit confirmation for destructive or costly actions.

  • Make actions reversible where possible (undo, restore, cancel).

  • Use clear warning language before risky actions.

  • Avoid making destructive actions the default option in dialogs.

Assessment heuristics:

  • Confirm destructive actions (delete, send, purchase) require confirmation.

  • Confirm reversible alternatives are offered where feasible.

  • Confirm the destructive option is not the default button in confirmation dialogs.

Source: https://www.w3.org/TR/coga-usable/#objective-4.

control-use-familiar-metrics-and-units

Control 4.12 Use Familiar Metrics and Units

Units of measurement must match the user's locale. Showing imperial units to a metric audience (or vice versa) creates avoidable cognitive friction.

Design patterns:

  • Detect or ask for user locale and display units accordingly.

  • Provide unit conversions where multiple units are common.

  • Label units clearly; avoid ambiguous abbreviations.

  • Allow the user to switch units explicitly.

Assessment heuristics:

  • Confirm units match the user's locale by default.

  • Confirm conversions are provided when units may be unfamiliar.

  • Confirm unit abbreviations are unambiguous (for example, distinguishing kilometres from kilobytes).

Source: https://www.w3.org/TR/coga-usable/#objective-4.

Objective 7 - Provide Help and Support

Objective 7 covers patterns that explain consequences, offer in-context help, gather feedback, and confirm important actions. The user need is "Feedback and Confirmation": users with cognitive and learning disabilities benefit when the interface explains outcomes before they commit, makes help easy to find, and reminds them of upcoming events or tasks.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 7, https://www.w3.org/TR/coga-usable/#objective-7.

control-clearly-state-the-results-and-disadvantages-of-actions-options-and-selections

Control 7.1 Clearly State the Results and Disadvantages of Actions, Options, and Selections

Users must know what an action will do before they commit. Hidden consequences (recurring charges, account merges, irreversible deletions) damage trust and exclude users who cannot easily reverse mistakes.

Design patterns:

  • State the outcome of each action in plain language before the user commits.

  • Disclose recurring or future commitments (subscriptions, cancellation fees) clearly.

  • Warn the user before irreversible actions.

  • Show comparisons between options to help users choose.

Assessment heuristics:

  • Confirm action labels describe the outcome (for example, "Send invoice" rather than "Submit").

  • Confirm recurring commitments are disclosed before the user commits.

  • Confirm irreversible actions are flagged and require confirmation.

Source: https://www.w3.org/TR/coga-usable/#objective-7.

control-provide-help-for-forms-and-non-standard-controls

Control 7.2 Provide Help for Forms and Non-standard Controls

Help must be available where the user needs it, not buried in a separate help section. Inline help, examples, and tooltips placed next to form fields and non-standard controls answer questions at the point of confusion.

Design patterns:

  • Provide inline help next to fields that may confuse users.

  • Provide format examples for fields with specific format requirements.

  • Provide tooltips and inline guidance for non-standard controls.

  • Link to detailed help where inline guidance is insufficient.

Assessment heuristics:

  • Confirm inline help appears next to fields that require explanation.

  • Confirm format examples appear next to fields with specific format requirements.

  • Confirm non-standard controls have inline guidance the first time they appear.

Source: https://www.w3.org/TR/coga-usable/#objective-7.

control-make-it-easy-to-find-help-and-give-feedback

Control 7.3 Make it Easy to Find Help and Give Feedback

A user who cannot find help is a user who abandons the task. Help and feedback links must be present in conventional locations on every page, with multiple contact methods so users can choose the one that suits them.

Design patterns:

  • Place help links in conventional locations (header or footer) on every page.

  • Offer multiple contact methods (chat, phone, email, web form).

  • Provide a clear feedback channel so users can report problems.

  • Avoid burying help behind multi-level menus.

Assessment heuristics:

  • Confirm help and contact links appear on every page in a consistent location.

  • Confirm at least two contact methods are available.

  • Confirm a feedback channel is available for users to report issues.

Source: https://www.w3.org/TR/coga-usable/#objective-7.

control-provide-help-with-directions

Control 7.4 Provide Help with Directions

Wayfinding within a site or application must be straightforward. Breadcrumbs, clear page titles, and visible site maps help users keep track of where they are and find their way back.

Design patterns:

  • Provide breadcrumbs showing the current location within the site.

  • Use descriptive page titles that match the user's location.

  • Provide a site map for complex sites.

  • Show "you are here" indicators in navigation.

Assessment heuristics:

  • Confirm breadcrumbs appear on every page below the home page.

  • Confirm the active navigation item is visually distinct.

  • Confirm a site map is provided for sites with more than a few sections.

Source: https://www.w3.org/TR/coga-usable/#objective-7.

control-provide-reminders

Control 7.5 Provide Reminders

Users with memory or attention differences benefit from reminders about upcoming events, expiring sessions, scheduled appointments, or incomplete tasks. Reminders must be timely and dismissible.

Design patterns:

  • Offer reminders for upcoming events, appointments, or expirations.

  • Allow the user to choose the reminder channel (email, in-app, push).

  • Allow the user to dismiss or snooze reminders.

  • Avoid spamming users with unnecessary reminders.

Assessment heuristics:

  • Confirm reminders are offered for time-sensitive events.

  • Confirm reminders can be customised by channel and frequency.

  • Confirm reminders can be dismissed or snoozed.

Source: https://www.w3.org/TR/coga-usable/#objective-7.

Objective 2 - Help Users Find What They Need

Objective 2 covers patterns that make important tasks, features, actions, and information easy to locate. The user need is "Findability": users with cognitive and learning disabilities benefit from prominent placement of primary tasks, predictable site hierarchies, clear page structure, segmented media, and tolerant search facilities.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 2, https://www.w3.org/TR/coga-usable/#objective-2.

control-make-it-easy-to-find-the-most-important-tasks-and-features-of-the-site

Control 2.1 Make it Easy to Find the Most Important Tasks and Features of the Site

The site's primary tasks must be discoverable without exploration. Users should not have to hunt through menus to find what the site is for. Prominent placement of the top three to five tasks lets users reach their goal quickly.

Design patterns:

  • Identify the top three to five user tasks and surface them on the home page.

  • Place primary calls to action above the fold on common viewports.

  • Use clear, action-oriented labels for primary tasks.

  • Avoid burying core tasks behind multi-level menus.

Assessment heuristics:

  • Confirm the site's primary tasks appear on the home page without scrolling.

  • Confirm task labels use the same vocabulary the audience uses.

  • Confirm users can reach the primary task in three clicks or fewer from the home page.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

control-make-the-site-hierarchy-easy-to-understand-and-navigate

Control 2.2 Make the Site Hierarchy Easy to Understand and Navigate

Site navigation must mirror how users think about the content, not how the organisation is structured. Shallow, intuitive hierarchies let users predict where to look. Breadcrumbs and consistent menus help users keep track of their location.

Design patterns:

  • Group content by user need rather than internal team structure.

  • Keep the hierarchy shallow; aim for content to be reachable within three levels.

  • Provide breadcrumbs showing the user's current location.

  • Maintain the same navigation across all pages.

Assessment heuristics:

  • Confirm navigation reflects user mental models, not the organisation chart.

  • Confirm breadcrumbs are present on every page below the home page.

  • Confirm navigation labels and structure are identical across pages.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

control-use-a-clear-and-understandable-page-structure

Control 2.3 Use a Clear and Understandable Page Structure

A page's regions must be visually and programmatically distinct so users can scan and skip. Dense, undifferentiated layouts force users to read every word to find what they need.

Design patterns:

  • Divide pages into visually distinct regions using whitespace, borders, or background variation.

  • Use semantic landmarks (<header>, <nav>, <main>, <aside>, <footer>).

  • Provide descriptive headings at each section level.

  • Avoid wall-of-text layouts; chunk content into scannable blocks.

Assessment heuristics:

  • Confirm landmarks divide the page into named regions.

  • Confirm heading structure is hierarchical and reflects content organisation.

  • Confirm visual region boundaries match the programmatic structure.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

control-make-it-easy-to-find-the-most-important-actions-and-information-on-the-page

Control 2.4 Make it Easy to Find the Most Important Actions and Information on the Page

Within a page, the primary action and the most important information must stand out. Users should not have to read or scan extensively to find the call to action. Visual hierarchy and prominent placement direct attention.

Design patterns:

  • Place the primary action prominently, typically above the fold and styled distinctively.

  • Place the most important information near the top of the page.

  • Use visual hierarchy (size, weight, colour) to indicate importance.

  • Avoid competing primary actions that dilute focus.

Assessment heuristics:

  • Confirm the primary action is visually distinct from secondary actions.

  • Confirm the page has at most one primary call to action.

  • Confirm key information appears in the first viewport on common viewports.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

control-break-media-into-chunks

Control 2.5 Break Media into Chunks

Long videos, podcasts, and tutorials overwhelm users who need to find or revisit specific content. Chunking media into chapters or segments, providing anchored transcripts, and offering summaries lets users navigate to the part they need.

Design patterns:

  • Provide chapter markers within long videos and audio.

  • Offer transcripts with anchored headings users can jump to.

  • Split long media into shorter standalone episodes when feasible.

  • Provide a brief summary alongside long media so users can decide whether to watch or read.

Assessment heuristics:

  • Confirm videos longer than approximately five minutes have chapter markers or segmented playback.

  • Confirm transcripts include anchored headings.

  • Confirm a written summary accompanies long-form media.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

Control 2.6 Provide Search

Users who cannot remember exact navigation paths benefit from search. Search must tolerate typos, recognise synonyms, and provide suggestions. Search without these affordances frustrates users who cannot spell technical terms or recall exact product names.

Design patterns:

  • Provide a site search in a conventional location.

  • Tolerate common typographical errors and offer "did you mean" suggestions.

  • Recognise synonyms and related terms.

  • Show recent searches and suggested completions.

Assessment heuristics:

  • Confirm site search is reachable from every page.

  • Confirm search returns useful results for common misspellings.

  • Confirm search supports auto-suggest and recent queries.

Source: https://www.w3.org/TR/coga-usable/#objective-2.

Objective 6 - Ensure Processes Do Not Rely on Memory

Objective 6 covers patterns that remove the burden of remembering information across screens, steps, or sessions. The user need is "Memory Support": users with cognitive and learning disabilities, working memory differences, or age-related decline are excluded by interfaces that expect them to memorise instructions, codes, or menu structures.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 6, https://www.w3.org/TR/coga-usable/#objective-6.

control-ensure-processes-do-not-rely-on-memory

Control 6.1 Ensure Processes Do Not Rely on Memory

Multi-step processes must not require the user to remember information from earlier steps. Reference numbers, prior selections, and instructions should remain visible or be reproduced where needed.

Design patterns:

  • Display reference numbers and prior selections persistently throughout multi-step processes.

  • Reproduce relevant instructions on the screen where they are needed.

  • Provide a summary of prior steps that remains accessible.

  • Avoid asking users to memorise temporary codes between screens.

Assessment heuristics:

  • Confirm information set in earlier steps remains visible when needed later.

  • Confirm reference numbers and confirmation codes are persistently visible or saved.

  • Confirm instructions are repeated on each screen where they apply.

Source: https://www.w3.org/TR/coga-usable/#objective-6.

control-let-users-avoid-navigating-voice-menus

Control 6.2 Let Users Avoid Navigating Voice Menus

Voice menus and interactive voice response trees impose heavy memory and attention demands. Users should have alternative contact methods (text chat, email, web form) so they can complete the task in a modality that suits them.

Design patterns:

  • Provide alternative contact methods alongside any voice menu.

  • Offer a direct route to a human agent.

  • Provide a visible flat menu (text) as an alternative to voice trees.

  • Allow callbacks rather than requiring users to wait on hold.

Assessment heuristics:

  • Confirm voice menus are accompanied by web-based alternatives (chat, email, web form).

  • Confirm users can reach a human without navigating a deep menu tree.

  • Confirm callback options are offered for long wait times.

Source: https://www.w3.org/TR/coga-usable/#objective-6.

control-do-not-rely-on-user-calculations-or-memorising-information

Control 6.3 Do Not Rely on User Calculations or Memorising Information

Users should never have to perform mental arithmetic or transcribe information across forms. Compute totals automatically and carry forward data the system already knows.

Design patterns:

  • Calculate totals, tax, and similar derived values automatically.

  • Pre-populate fields with information the system already holds.

  • Show running totals and intermediate results clearly.

  • Avoid asking users to copy or transcribe data the system can carry forward.

Assessment heuristics:

  • Confirm derived values (totals, percentages, due dates) are computed automatically.

  • Confirm known user information is pre-populated in subsequent forms.

  • Confirm users are never asked to perform arithmetic the system can perform.

Source: https://www.w3.org/TR/coga-usable/#objective-6.

Objective 5 - Help Users Focus

Objective 5 covers patterns that reduce distraction and protect the user's attention. The user need is "Attention Support": users with attention-related disabilities, anxiety, or executive function differences struggle when interfaces present competing demands, unnecessary detours, or visual noise. Designs that strip distraction and shorten critical paths help all users complete tasks.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 5, https://www.w3.org/TR/coga-usable/#objective-5.

control-help-users-focus

Control 5.1 Help Users Focus

Visual noise, autoplay media, and unsolicited overlays steal attention from the task at hand. Pages must minimise distraction so users can keep their focus on the action they came to perform.

Design patterns:

  • Reduce competing visual elements on task-focused pages.

  • Disable autoplay for video, audio, and animation by default.

  • Avoid unsolicited modal overlays during a task.

  • Use whitespace and visual hierarchy to direct attention to the primary action.

Assessment heuristics:

  • Confirm task-focused pages have a single dominant action and minimal competing content.

  • Confirm media does not autoplay without explicit consent.

  • Confirm overlays appear only in response to user action or as part of the task flow.

Source: https://www.w3.org/TR/coga-usable/#objective-5.

control-make-short-critical-paths

Control 5.2 Make Short Critical Paths

The path from intent to completion must be as short as possible. Every detour, intermediate page, or upsell increases the chance the user abandons the task or makes a mistake.

Design patterns:

  • Remove non-essential steps from critical paths (checkout, sign-in, support contact).

  • Combine related steps where it does not increase complexity.

  • Offer guest checkout and one-click options where appropriate.

  • Avoid forcing account creation before allowing a task to complete.

Assessment heuristics:

  • Confirm critical paths (checkout, sign-in, primary task) involve the minimum necessary steps.

  • Confirm optional information requests are clearly marked as optional.

  • Confirm the user can complete a primary task without unrelated detours.

Source: https://www.w3.org/TR/coga-usable/#objective-5.

control-avoid-too-much-content

Control 5.3 Avoid Too Much Content

Pages overloaded with information overwhelm users. Showing only what is needed for the current task, with optional detail available on demand, lets users absorb the content at their pace.

Design patterns:

  • Show only the information needed for the current task.

  • Use progressive disclosure (expandable sections, "show more") for optional detail.

  • Defer secondary information to separate pages or sections.

  • Trim repeated or redundant content.

Assessment heuristics:

  • Confirm pages display only the information needed to complete the immediate task.

  • Confirm optional detail is reachable but does not clutter the default view.

  • Confirm content is not repeated within the same page.

Source: https://www.w3.org/TR/coga-usable/#objective-5.

Objective 8 - Support Adaptation and Personalization

Objective 8 covers patterns that let users adapt the interface to their preferences and capabilities. The user need is "User Control": users with cognitive and learning disabilities benefit when they can control motion, integrate assistive extensions, simplify the interface, and personalise the appearance and behaviour to match their needs.

Source: W3C, Making Content Usable for People with Cognitive and Learning Disabilities, Objective 8, https://www.w3.org/TR/coga-usable/#objective-8.

control-let-users-control-when-the-content-moves-or-changes

Control 8.1 Let Users Control When the Content Moves or Changes

Motion, animation, and auto-advancing carousels distract users with attention differences and can trigger vestibular reactions. Users must be able to pause, stop, or disable motion globally.

Design patterns:

  • Provide pause and stop controls for any moving or auto-advancing content.

  • Honour the prefers-reduced-motion user preference.

  • Disable autoplay for video and animation by default.

  • Avoid using motion as the sole indicator of state.

Assessment heuristics:

  • Confirm prefers-reduced-motion disables non-essential animation.

  • Confirm auto-advancing content has visible pause and stop controls.

  • Confirm motion is not the sole indicator of state changes.

Source: https://www.w3.org/TR/coga-usable/#objective-8.

control-enable-apis-and-extensions

Control 8.2 Enable APIs and Extensions

Users rely on browser extensions, reading aids, and assistive technology to adapt content. The site must use standard semantic markup, expose accessibility APIs correctly, and avoid blocking extensions through anti-automation measures.

Design patterns:

  • Use semantic HTML so reading aids and extensions can parse the content.

  • Expose accessibility properties via ARIA where appropriate.

  • Avoid blocking browser extensions or assistive technology with anti-automation defences.

  • Avoid heavy client-side rendering that hides content from extensions.

Assessment heuristics:

  • Confirm content is exposed through the accessibility tree, not only through visual rendering.

  • Confirm browser extensions (reading aids, simplifiers, translators) can access and modify content.

  • Confirm anti-automation measures do not interfere with assistive technology.

Source: https://www.w3.org/TR/coga-usable/#objective-8.

control-support-simplification

Control 8.3 Support Simplification

Some users benefit from a simplified version of a page. Sites should support reader modes, provide print-friendly views, and avoid layouts that break under simplification.

Design patterns:

  • Support browser reader mode by using semantic article markup.

  • Provide a print-friendly view that strips navigation and decoration.

  • Avoid relying on positioning that breaks when content is linearised.

  • Ensure key content is reachable in a single linear reading order.

Assessment heuristics:

  • Confirm reader mode produces a usable, complete version of the content.

  • Confirm a print view is available and includes only the relevant content.

  • Confirm the linear reading order matches the visual order.

Source: https://www.w3.org/TR/coga-usable/#objective-8.

control-support-a-personalised-and-familiar-interface

Control 8.4 Support a Personalised and Familiar Interface

Personalisation lets users adjust the interface to suit their preferences. Honouring user settings (font size, contrast, dark mode, language) and remembering choices across sessions makes the interface feel familiar and reduces cognitive load.

Design patterns:

  • Honour user preferences for font size, contrast, dark mode, and language.

  • Remember personalisation choices across sessions when the user consents.

  • Use standard semantics so personalisation extensions can apply the user's chosen vocabulary, icons, or symbols.

  • Avoid forcing a single visual theme on all users.

Assessment heuristics:

  • Confirm user preferences (prefers-color-scheme, prefers-reduced-motion, font-size settings) are honoured.

  • Confirm personalisation choices persist across sessions when the user has opted in.

  • Confirm semantic markup supports personalisation extensions and assistive vocabularies.

Source: https://www.w3.org/TR/coga-usable/#objective-8.

Requirements and compatibility

Written for: GitHub Copilot, Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter, Needs Python, Needs Node.js

The author says: 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.

Security

What our scanner noticed· Low risk

  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Microsoft
Publisher
Microsoft (Official)
Source
microsoft/hve-core · .github/skills/accessibility/accessibility · commit f425e94
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Microsoft.

Get it from the source

1 of this skill’s files are not mirrored here, so there is no ZIP. Get the complete skill from its source: microsoft/hve-core