Accessibility
MicrosoftOfficialPublished by Microsoft
- Skill
- Tool integration
- Software development
- MIT
- Low risk
- Has scripts
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
1 of its files are not mirrored here, so install it from its source:
https://github.com/microsoft/hve-core/tree/f425e943bf228052a23e6bc4810b5faef030314f/.github/skills/accessibility/accessibility
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:
Phase 1 — Discovery (
discovery)Phase 2 — Framework Selection (
framework-selection)Phase 3 — Standards Mapping (
standards-mapping)Phase 4 — Plan Risk Assessment (
plan-risk-assessment)Phase 5 — Impact and Evidence (
impact-evidence)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.
| Class | Representative WCAG SC | What static analysis can do | Adequate method to decide |
|---|---|---|---|
| Static-decidable structure | 1.1.1, 1.4.3, 4.1.2 (name present), 2.4.2, 3.1.1 | Decide | axe / static scan |
| Interaction behavior | 2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11 | Inform only | Keyboard/interaction probe driving keys across focus/open states, or manual keyboard pass |
| Announcement correctness | 1.3.1, 4.1.2 (computed name/role), 4.1.3 | Inform only | Accessibility-tree assertion of computed name/role/live, or manual AT pass (Windows NVDA or human-led JAWS) |
| Adaptive rendering | 1.4.4, 1.4.10, 1.4.12, 2.4.11 | Inform only | Rendered probe at 200% zoom, 320px reflow, and text-spacing states |
| Faux semantics | 1.3.1 (faux headings), 2.4.3 (faux controls) | Cannot see | Heuristic source pass plus accessibility-tree assertion; no element exists for a rule engine to flag |
For the announcement class, the assistive-technology announcement model 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
informsit 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
npxavailable on PATH.Network access on first run so
npxcan 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.htmlLoopback HTTP(S) targets need no additional option. Every other remote host
requires either a matching, repeatable --allow-host HOST value or the broader
--allow-external confirmation. Local paths and local file: URIs must resolve
to existing regular files. Network shares, remote file authorities, directories,
missing files, credentials, leading-dash targets, and non-HTTP(S) remote schemes
are rejected before the axe CLI starts.
Parameters Reference
| Parameter | Required | Default | Description |
|---|---|---|---|
target | Yes | — | Authorized HTTP(S) URL or existing regular local file to scan. |
--output | No | stdout | Path to write the normalized JSON results. |
--allow-host | No | none | Authorize one non-loopback HTTP(S) host; repeat as needed. |
--allow-external | No | false | Confirm access to any non-loopback HTTP(S) host. |
Remote authorization applies to the initial scanner target only. It does not constrain browser redirects, DNS address changes, subresources, WebSockets, Service Workers, downloads, or other browser-derived requests. Run the scanner only from a workstation whose network reach matches the target's trust level.
Script Reference
Entrypoint: scripts/scan.py
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/climissing).
Troubleshooting
| Symptom | Likely cause | Action | Exit code |
|---|---|---|---|
scanner unavailable error | Node.js or npx not on PATH | Install Node.js so npx resolves, then re-run. | 2 |
| Long pause or download on first run | npx is fetching @axe-core/cli | Allow network access on the first run; later runs use the cache. | — |
Refusing to probe non-loopback host | Remote host was not explicitly authorized | Add --allow-host HOST or confirm with --allow-external. | 2 |
Local scan target does not exist | Local path or file URI cannot be resolved | Supply an existing regular local file, not a directory or share. | 2 |
scan failed or returned invalid output | axe-core CLI errored or emitted non-JSON | Confirm the target URL or file is reachable and well-formed. | 1 |
Empty violations but issues expected | Page rendered after the scan, or rules N/A | Confirm the target fully loads; check summary.inapplicable. | 0 |
Mapping findings to frameworks
Each violation's impact is one of minor, moderate, serious, or critical. axe rule tags decode to WCAG success criteria by stripping the wcag prefix and inserting decimals:
| axe tag | WCAG success criterion |
|---|---|
wcag111 | 1.1.1 Non-text Content |
wcag143 | 1.4.3 Contrast (Minimum) |
WCAG success criteria are normative; the axe techniques that surface them are informative. Treat scanner output as evidence pointing at a criterion, not a conformance verdict.
Runtime probe harness
The runtime probe harness (scripts/runtime_a11y) 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 ciPLAYWRIGHT_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 nvdaThe 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-onlyThe 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 --helpTo 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--configresolves relative to the current working directory.--outwrites the aggregated JSON document to disk.--base-urloverrides the configured base URL. It must remain a loopback origin unless the host is allowlisted or--allow-externalis supplied.--tracecaptures Playwright traces and screenshots.--allow-externalconfirms intentional probing of a non-loopback host.render-artifactsturns a rendered matrix JSON document into the complete coverage evidence bundle.
Evidence bundle composition
compose-evidence combines downstream-owned catalogs, cadence scope, run context, normalized source envelopes, state proofs, and optional qualified-reviewer supplements into one deterministic evidence bundle. It is separate from render-artifacts: rendering creates coverage, EARL, and manual-plan views from a matrix, while composition creates a revision-bound trust envelope across evidence producers.
The command requires explicit input paths and never infers product scope, Git state, time, retention, branch policy, or a release verdict. A consuming project owns those decisions. The composer validates artifact bytes beneath --artifact-root, preserves conflicts and quarantined results, and always emits non-attestation metadata. Automation, reviewer evidence, and release evidence have separate completeness states.
For pull requests, a valid initial bundle may report reviewer evidence as pending. A qualified reviewer can later provide a privacy-minimized, digest-bound supplement and registry snapshot for deterministic recomposition against the prior bundle. Recomposition supplies both --prior-bundle and its independently retained --prior-bundle-digest; omission or mutation of prior history fails closed. Missing required reviewer evidence blocks release completeness, not ordinary bundle production. Raw screen-reader phrases and restricted transcript paths are forbidden in ordinary bundles; only approved counts, redacted metadata, and digests cross this boundary.
Use --require-completeness automated, reviewer, or release only when the downstream workflow intends that dimension to gate. Valid incomplete bundles are still written for diagnosis. The additional exits are:
| Exit code | Meaning |
|---|---|
5 | Automated evidence is incomplete. |
6 | Reviewer evidence is pending or invalid. |
7 | Release evidence is incomplete. |
Existing exits 0 through 4 retain their meanings. The JSON contracts live beside the runtime at evidence-bundle.schema.json, evidence-source.schema.json, evidence-scope.schema.json, screen-reader-method-cell.schema.json, and qualified-human-result.schema.json.
For a complete adopter path from an inactive template to a first retained bundle and deterministic recomposition, including schema-valid examples for every authored input, read references/evidence-composition-adoption.md.
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-rootselects 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-rootallocates a timestamped run directory beneath that same root.--visual-surfaceand--visual-statenarrow 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.
serveMode | Behavior |
|---|---|
auto | Reuses a healthy server at the configured loopback origin, otherwise builds and starts one it owns and stops afterward. |
served | Requires a server already answering the configured loopback origin, and fails with the expected origin and start command when none responds. |
external | Never probes or starts a server. The configured target must already be reachable. |
off | Never probes or starts a server. |
auto and served accept only loopback origins, because the harness will not manage or health-probe a remote server. A non-loopback target still requires the allowlist or --allow-external, and is only valid with external or off.
Under auto, starting an owned server builds the site first, so a capture that has to start its own server takes several minutes before the first screenshot. Leave a server running at the configured origin to skip that cost, which is the reuse path.
The Docusaurus site in this repository is configured for auto at http://127.0.0.1:3001, which is the same production-build origin the Playwright end-to-end suite uses. Capturing against the production build keeps visual evidence consistent with what continuous integration verifies.
Config summary
The harness loads scripts/runtime_a11y/config-schema.json 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:
singlereads the cumulative speech log after commands and the configured settle interval.clear-and-captureclears earlier speech before the settle interval, then reads the cumulative log.actionwraps an existing post-start declarative trigger with Guidepup action capture. Assertions can selectactionSpeechoractionNormalizedSpeechto 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-axeprobe-keyboard-traversalprobe-focus-visibleprobe-focus-obscuredprobe-live-regionprobe-aria-treeprobe-widget-keyboardprobe-reflow-resizeprobe-target-sizeprobe-contrastprobe-forced-colorsprobe-reduced-motionprobe-structure-crawlprobe-name-in-labelprobe-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, invalidlang)
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
0indicates 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 code | Meaning | Typical response |
|---|---|---|
3 | A blocking expectation resolved failed | Treat as intent drift; the surface regressed |
4 | A blocking expectation was never evaluated | Treat 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--recordis the authored record. It is never read for anything but its declarations and never rewritten.--resultsis a results document fromrun-all.--outoverrides the output path, which defaults todesign-intent/.verification/<surface-id>.earl.jsonbeside 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.
| Situation | Outcome | Mode |
|---|---|---|
| Every matched criterion passed | passed | automatic |
| Any matched criterion failed | failed | automatic |
| Evidence gathered but not decisive | cantTell | automatic |
| No result row matched the expectation | untested | automatic |
The expectation uses assert: custom | untested | manual |
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:
observedOutcomeis the generated artifact fieldoutcome. An override never replaces it.effectiveOutcomeapplies fail-safe precedence. Either an observed or humanfailedoutcome yieldsfailed; humanpassedsettles onlyuntested,cantTell, orinapplicable; otherwise the observed outcome remains. This is the value the gate applies.overrideConflictistrueonly when the observed and authored override outcomes are eachpassedorfailedand differ. An override that settles anuntested,cantTell, orinapplicableexpectation 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.mdOutput 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
- ATTRIBUTION.mdAdded by AutoGineer836 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SECURITY.md40.9 KiB
- SKILL.md41.5 KiB
- pyproject.toml891 B
- references/ci/accessibility-coverage.workflow-template.yml23.3 KiB
- references/ci/act-rule-format.md5.4 KiB
- references/ci/probe-spec-parity.md15.3 KiB
- references/design-intent/record-contract.md9.6 KiB
- references/evidence-composition-adoption.md8.6 KiB
- references/examples/evidence/asset-journeys.json364 B
- references/examples/evidence/evidence-scope.json396 B
- references/examples/evidence/requirement-methods.json683 B
- references/examples/evidence/run-context.json994 B
- references/examples/evidence/state-proofs.json367 B
- references/frameworks/aria-apg.md88.7 KiB
- references/frameworks/at-announcement-model.md12.5 KiB
- references/frameworks/coga.md81.0 KiB
- references/frameworks/en-301-549.md153.9 KiB
- references/frameworks/graphics-aria-svg-aam.md6.9 KiB
- references/frameworks/section-508.md36.7 KiB
- references/frameworks/wcag-22.md66.2 KiB
- references/phases/backlog-handoff.md26.2 KiB
- references/phases/capture-coaching.md11.4 KiB
- references/phases/framework-selection.md8.3 KiB
- references/phases/impact-assessment.md18.8 KiB
- scripts/runtime_a11y/.npmrc923 B
- scripts/runtime_a11y/__init__.pyScript154 B
- scripts/runtime_a11y/__main__.pyScript89.3 KiB
- scripts/runtime_a11y/_config.pyScript8.1 KiB
- scripts/runtime_a11y/_errors.pyScript1.3 KiB
- scripts/runtime_a11y/_intent.pyScript33.0 KiB
- scripts/runtime_a11y/_projection.pyScript6.9 KiB
- scripts/runtime_a11y/aria-at-catalog.json20.7 KiB
- scripts/runtime_a11y/aria-at-catalog.schema.json5.7 KiB
- scripts/runtime_a11y/composition-summary.schema.json655 B
- scripts/runtime_a11y/config-schema.json12.1 KiB
- scripts/runtime_a11y/criteria-catalog.aria-apg.json1.6 KiB
- scripts/runtime_a11y/criteria-catalog.defect-scan.json2.0 KiB
- scripts/runtime_a11y/criteria-catalog.schema.json5.1 KiB
- scripts/runtime_a11y/criteria-catalog.wcag-22.json9.6 KiB
- scripts/runtime_a11y/design-intent.schema.json10.5 KiB
- scripts/runtime_a11y/evidence-bundle.schema.json11.2 KiB
- scripts/runtime_a11y/evidence-scope.schema.json2.2 KiB
- scripts/runtime_a11y/evidence-source.schema.json3.7 KiB
- scripts/runtime_a11y/evidence_bundle/__init__.pyScript494 B
- scripts/runtime_a11y/evidence_bundle/_adapters.pyScript15.1 KiB
- scripts/runtime_a11y/evidence_bundle/_canonical.pyScript1.3 KiB
- scripts/runtime_a11y/evidence_bundle/_compose.pyScript32.0 KiB
- scripts/runtime_a11y/evidence_bundle/_validate.pyScript5.8 KiB
- scripts/runtime_a11y/matrix/__init__.pyScript643 B
- scripts/runtime_a11y/matrix/_aria_at.pyScript10.7 KiB
- scripts/runtime_a11y/matrix/_artifacts.pyScript6.6 KiB
- scripts/runtime_a11y/matrix/_build.pyScript1.6 KiB
- scripts/runtime_a11y/matrix/_catalog.pyScript7.3 KiB
- scripts/runtime_a11y/matrix/_coverage.pyScript3.0 KiB
- scripts/runtime_a11y/matrix/_ingest_assessor.pyScript4.4 KiB
- scripts/runtime_a11y/matrix/_ingest_planner.pyScript5.6 KiB
- scripts/runtime_a11y/matrix/_ingest_probe.pyScript2.7 KiB
- scripts/runtime_a11y/matrix/_ingest_reports.pyScript3.5 KiB
- scripts/runtime_a11y/matrix/_merge.pyScript3.0 KiB
- scripts/runtime_a11y/matrix/_model.pyScript5.8 KiB
- scripts/runtime_a11y/matrix/_provenance.pyScript4.6 KiB
- scripts/runtime_a11y/matrix/_render_earl.pyScript7.3 KiB
- scripts/runtime_a11y/matrix/_render_json.pyScript2.1 KiB
- scripts/runtime_a11y/matrix/_render_md.pyScript4.5 KiB
- scripts/runtime_a11y/matrix/_render_test_plan.pyScript19.1 KiB
- scripts/runtime_a11y/methods.json1.8 KiB
- scripts/runtime_a11y/package-lock.json12.3 KiB
- scripts/runtime_a11y/package.json554 B
- scripts/runtime_a11y/probe-criteria-map.json11.9 KiB
- scripts/runtime_a11y/qualified-human-result.schema.json4.0 KiB
- scripts/runtime_a11y/runner/_core.mjsScript12.5 KiB
- scripts/runtime_a11y/runner/_shared.mjsScript42.4 KiB
- scripts/runtime_a11y/runner/assertions.mjsScript10.4 KiB
- scripts/runtime_a11y/runner/at-plan-executor.mjsScript40.0 KiB
- scripts/runtime_a11y/runner/calibration-checkpoint.mjsScript2.0 KiB
- scripts/runtime_a11y/runner/calibration-executor.mjsScript51.5 KiB
- scripts/runtime_a11y/runner/case-catalog.mjsScript13.0 KiB
- scripts/runtime_a11y/runner/drivers/command-contract.mjsScript4.2 KiB
- scripts/runtime_a11y/runner/drivers/driver-contract.mjsScript5.4 KiB
- scripts/runtime_a11y/runner/drivers/guidepup-adapter.mjsScript16.0 KiB
- scripts/runtime_a11y/runner/index.mjsScript894 B
- scripts/runtime_a11y/runner/methods.mjsScript1.0 KiB
- scripts/runtime_a11y/runner/probe-aria-tree.mjsScript2.1 KiB
- scripts/runtime_a11y/runner/probe-audio-control.mjsScript1.4 KiB
- scripts/runtime_a11y/runner/probe-axe.mjsScript2.7 KiB
- scripts/runtime_a11y/runner/probe-broken-links.mjsScript4.4 KiB
- scripts/runtime_a11y/runner/probe-console-errors.mjsScript1.7 KiB
- scripts/runtime_a11y/runner/probe-context-change.mjsScript2.5 KiB
- scripts/runtime_a11y/runner/probe-contrast.mjsScript1.8 KiB
- scripts/runtime_a11y/runner/probe-dom-hygiene.mjsScript3.4 KiB
- scripts/runtime_a11y/runner/probe-focus-obscured.mjs2.3 KiB
- scripts/runtime_a11y/runner/probe-focus-visible.mjs1.7 KiB
- scripts/runtime_a11y/runner/probe-forced-colors.mjs2.5 KiB
- scripts/runtime_a11y/runner/probe-forms.mjs2.2 KiB
- scripts/runtime_a11y/runner/probe-hover-focus.mjs2.2 KiB
- scripts/runtime_a11y/runner/probe-input-purpose.mjs2.1 KiB
- scripts/runtime_a11y/runner/probe-keyboard-traversal.mjs2.8 KiB
- scripts/runtime_a11y/runner/probe-link-purpose.mjs2.1 KiB
- scripts/runtime_a11y/runner/probe-live-region.mjs1.4 KiB
- scripts/runtime_a11y/runner/probe-name-in-label.mjs1.5 KiB
- scripts/runtime_a11y/runner/probe-orientation.mjs1.6 KiB
- scripts/runtime_a11y/runner/probe-real-sr.mjs2.0 KiB
- scripts/runtime_a11y/runner/probe-reduced-motion.mjs1.4 KiB
- scripts/runtime_a11y/runner/probe-reflow-resize.mjs1.1 KiB
- scripts/runtime_a11y/runner/probe-structure-crawl.mjs2.0 KiB
- scripts/runtime_a11y/runner/probe-target-size.mjs4.9 KiB
- scripts/runtime_a11y/runner/probe-text-spacing.mjs1.8 KiB
- scripts/runtime_a11y/runner/probe-timing.mjs1.2 KiB
- scripts/runtime_a11y/runner/probe-title-lang.mjs1.9 KiB
- scripts/runtime_a11y/runner/probe-use-of-color.mjs2.4 KiB
- scripts/runtime_a11y/runner/probe-virtual-sr.mjs1.2 KiB
- scripts/runtime_a11y/runner/probe-widget-keyboard.mjs2.1 KiB
- scripts/runtime_a11y/runner/probe-zoom-blocker.mjs1.6 KiB
- scripts/runtime_a11y/runner/route.mjs2.3 KiB
- scripts/runtime_a11y/runner/transcript.mjs2.1 KiB
- scripts/runtime_a11y/runner/validation.mjs1.8 KiB
- scripts/runtime_a11y/runner/visual-review-executor.mjs14.4 KiB
- scripts/runtime_a11y/schema-validation-report.schema.json826 B
- scripts/runtime_a11y/screen-reader-binding.schema.json3.5 KiB
- scripts/runtime_a11y/screen-reader-case.schema.json1.6 KiB
- scripts/runtime_a11y/screen-reader-cases.json6.8 KiB
- scripts/runtime_a11y/screen-reader-method-cell.schema.json2.2 KiB
- scripts/runtime_a11y/validation-manifest.schema.json3.8 KiB
- scripts/runtime_a11y/validation_manifest.py7.1 KiB
- scripts/runtime_a11y/visual-review-manifest.schema.json3.2 KiB
- scripts/runtime_a11y/visual_review.py20.5 KiB
- scripts/scan.py10.9 KiB
- scripts/scanner_npm/.npmrc344 B
- scripts/scanner_npm/package.json203 B
- tests/conftest.py1.4 KiB
- tests/corpus/0_empty(opens on GitHub)Not mirrored: opens on GitHub5 B
- tests/corpus/1_axe_violation91 B
- tests/corpus/2_selector_dense85 B
- tests/corpus/3_empty_fields77 B
- tests/corpus/4_json_like_payload87 B
- tests/fixtures/combobox.html329 B
- tests/fixtures/contrast.html194 B
- tests/fixtures/dialog.html264 B
- tests/fixtures/headings.html182 B
- tests/fuzz_harness.py4.7 KiB
- tests/runtime_a11y/fixtures/aria-at-driver-matrix.json3.7 KiB
- tests/runtime_a11y/fixtures/aria-at-modal-dialog-matrix.json516 B
- tests/runtime_a11y/fixtures/assessor_findings.md330 B
- tests/runtime_a11y/fixtures/planner_state.json464 B
- tests/runtime_a11y/fixtures/probe_results.json329 B
- tests/runtime_a11y/fixtures/report_findings.md443 B
- tests/runtime_a11y/runner/_core.test.mjs10.8 KiB
- tests/runtime_a11y/runner/_shared.test.mjs13.3 KiB
- tests/runtime_a11y/runner/assertions-structured.test.mjs3.5 KiB
- tests/runtime_a11y/runner/at-plan-executor.test.mjs74.3 KiB
- tests/runtime_a11y/runner/calibration-checkpoint.test.mjs3.2 KiB
- tests/runtime_a11y/runner/calibration-executor.test.mjs58.0 KiB
- tests/runtime_a11y/runner/calibration-fixtures.mjs1.5 KiB
- tests/runtime_a11y/runner/case-catalog.test.mjs14.0 KiB
- tests/runtime_a11y/runner/cleanup-ownership.test.mjs2.4 KiB
- tests/runtime_a11y/runner/command-contract.test.mjs4.1 KiB
- tests/runtime_a11y/runner/methods.test.mjs2.2 KiB
- tests/runtime_a11y/runner/probe-broken-links.test.mjs4.7 KiB
- tests/runtime_a11y/runner/probe-smoke/live-region.cases.mjs1.5 KiB
- tests/runtime_a11y/runner/probe-smoke/probe-aria-tree.smoke.mjs2.1 KiB
- tests/runtime_a11y/runner/probe-smoke/probe-forced-colors.smoke.mjs2.6 KiB
- tests/runtime_a11y/runner/probe-smoke/probe-live-region.smoke.mjs1.9 KiB
- tests/runtime_a11y/runner/probe-smoke/probe-virtual-sr.smoke.mjs1.6 KiB
- tests/runtime_a11y/runner/probe-smoke/virtual-sr.cases.mjs998 B
- tests/runtime_a11y/runner/probe-smoke/visual-review.smoke.mjs2.8 KiB
- tests/runtime_a11y/runner/probe-verdicts.test.mjs4.5 KiB
- tests/runtime_a11y/runner/real-sr.test.mjs30.3 KiB
- tests/runtime_a11y/runner/route.test.mjs2.3 KiB
- tests/runtime_a11y/runner/visual-review-executor.test.mjs7.9 KiB
- tests/runtime_a11y/test_aria_at.py20.4 KiB
- tests/runtime_a11y/test_aria_at_dogfood.py4.6 KiB
- tests/runtime_a11y/test_artifacts.py17.5 KiB
- tests/runtime_a11y/test_branch_completion.py5.7 KiB
- tests/runtime_a11y/test_build_coverage.py2.6 KiB
- tests/runtime_a11y/test_catalog.py3.7 KiB
- tests/runtime_a11y/test_cli.py95.0 KiB
- tests/runtime_a11y/test_cli_branches.py26.8 KiB
- tests/runtime_a11y/test_config.py11.3 KiB
- tests/runtime_a11y/test_config_guard.py3.4 KiB
- tests/runtime_a11y/test_coverage.py1.3 KiB
- tests/runtime_a11y/test_evidence_bundle.py43.0 KiB
- tests/runtime_a11y/test_ingest.py1.7 KiB
- tests/runtime_a11y/test_ingest_branches.py5.0 KiB
- tests/runtime_a11y/test_ingest_reports.py2.6 KiB
- tests/runtime_a11y/test_intent.py51.6 KiB
- tests/runtime_a11y/test_live_lifecycle.py8.9 KiB
- tests/runtime_a11y/test_merge.py2.1 KiB
- tests/runtime_a11y/test_merge_branches.py3.0 KiB
- tests/runtime_a11y/test_projection.py12.3 KiB
- tests/runtime_a11y/test_provenance.py4.8 KiB
- tests/runtime_a11y/test_render.py4.0 KiB
- tests/runtime_a11y/test_render_earl.py5.5 KiB
- tests/runtime_a11y/test_sample_bundle.py7.7 KiB
- tests/runtime_a11y/test_validation_manifest.py9.1 KiB
- tests/runtime_a11y/test_visual_review.py21.0 KiB
- tests/test_scan.py10.2 KiB
- tests/test_scan_branches.py4.6 KiB
- uv.lock114.8 KiB
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.
| # | Pattern | User need | Design patterns | Assessment heuristics | Reference |
|---|---|---|---|---|---|
| 1.1 | Make the Purpose of Your Page Clear | Clear Purpose | Descriptive titles, headers, signposts, top-of-page summary | Confirm purpose is visible without scrolling; titles match the task | objective-clear-purpose.md#control-make-the-purpose-of-your-page-clear |
| 1.2 | Use a Familiar Hierarchy and Design | Clear Operation | Conventional layout, predictable patterns, standard navigation | Confirm controls live where users expect; avoid novel patterns | objective-clear-purpose.md#control-use-a-familiar-hierarchy-and-design |
| 1.3 | Use a Consistent Visual Design | Clear Operation | Consistent layout, colours, typography, control placement | Confirm same controls render identically across pages | objective-clear-purpose.md#control-use-a-consistent-visual-design |
| 1.4 | Make Each Step Clear | Clear Operation | One concept per step, step indicators, progress feedback | Confirm each step has a clear heading and progress is visible | objective-clear-purpose.md#control-make-each-step-clear |
| 1.5 | Clearly Identify Controls and Their Use | Clear Operation | Conventional control shapes, visible focus, descriptive labels | Confirm interactive elements look interactive; labels describe outcome | objective-clear-purpose.md#control-clearly-identify-controls-and-their-use |
| 1.6 | Make the Relationship Clear Between Controls and the Content They Affect | Clear Operation | Proximity, grouping, visible references, aria-controls | Confirm users can predict what a control will change | objective-clear-purpose.md#control-make-the-relationship-clear-between-controls-and-the-content-they-affect |
| 1.7 | Use Icons that Help the User | Use Symbols | Familiar icons, paired text labels, consistent meaning | Confirm icons have text labels and follow industry conventions | objective-clear-purpose.md#control-use-icons-that-help-the-user |
| 2.1 | Make it Easy to Find the Most Important Tasks and Features of the Site | Findability | Prominent placement, above-the-fold key actions, clear entry points | Confirm primary tasks appear without scrolling on common viewports | objective-find-help.md#control-make-it-easy-to-find-the-most-important-tasks-and-features-of-the-site |
| 2.2 | Make the Site Hierarchy Easy to Understand and Navigate | Findability | Logical groupings, predictable menus, breadcrumbs | Confirm sitemap depth is shallow; navigation paths are stable | objective-find-help.md#control-make-the-site-hierarchy-easy-to-understand-and-navigate |
| 2.3 | Use a Clear and Understandable Page Structure | Findability | Distinct page regions, headings, whitespace, dividers | Confirm regions are visually distinct and use landmark roles | objective-find-help.md#control-use-a-clear-and-understandable-page-structure |
| 2.4 | Make it Easy to Find the Most Important Actions and Information on the Page | Findability | Prominent CTAs, summary at top, key info above the fold | Confirm primary actions are visually emphasised and reachable quickly | objective-find-help.md#control-make-it-easy-to-find-the-most-important-actions-and-information-on-the-page |
| 2.5 | Break Media into Chunks | Findability | Segmented video, chapter markers, summaries | Confirm long media has chapter navigation or transcripts with anchors | objective-find-help.md#control-break-media-into-chunks |
| 2.6 | Provide Search | Findability | Site search, spell-check, suggestions, recent queries | Confirm search exists and tolerates typos and synonyms | objective-find-help.md#control-provide-search |
| 3.1 | Use Clear and Understandable Language | Clear Meaning | Plain language, defined terms, simple vocabulary | Confirm reading level matches audience; jargon is defined inline | objective-clear-meaning.md#control-use-clear-and-understandable-language |
| 3.2 | Use Familiar Words | Clear Meaning | Common words, audience-appropriate vocabulary | Confirm uncommon words have a glossary entry or definition | objective-clear-meaning.md#control-use-familiar-words |
| 3.3 | Use Simple Sentence Structure | Clear Meaning | Short sentences, active voice, one idea per sentence | Confirm sentences are short and avoid embedded clauses | objective-clear-meaning.md#control-use-simple-sentence-structure |
| 3.4 | Use Headings and Sections | Clear Meaning | Hierarchical headings, scannable sections | Confirm headings are nested correctly and convey topic | objective-clear-meaning.md#control-use-headings-and-sections |
| 3.5 | Use Lists | Clear Meaning | Bulleted or numbered lists, short list items | Confirm enumerable content is presented as a list rather than prose | objective-clear-meaning.md#control-use-lists |
| 3.6 | Keep Text Succinct | Clear Meaning | Short paragraphs, summaries, removal of filler | Confirm content is trimmed to essentials; long pages have summaries | objective-clear-meaning.md#control-keep-text-succinct |
| 3.7 | Use Clear, Unambiguous Formatting and Punctuation | Clear Meaning | Standard punctuation, avoid all-caps, avoid italics for emphasis | Confirm formatting is consistent and avoids cognitive ambiguity | objective-clear-meaning.md#control-use-clear-unambiguous-formatting-and-punctuation |
| 3.8 | Separate Each Instruction | Clear Meaning | One instruction per line, numbered steps, clear separation | Confirm multi-step tasks are split into discrete numbered steps | objective-clear-meaning.md#control-separate-each-instruction |
| 3.9 | Use White Spacing | Clear Meaning | Generous margins, line height, spacing between blocks | Confirm density is low enough that elements do not crowd each other | objective-clear-meaning.md#control-use-white-spacing |
| 3.10 | Ensure Foreground Content is not Obscured by Background | Clear Meaning | High contrast, no busy backgrounds behind text | Confirm text contrast meets WCAG and backgrounds do not interfere | objective-clear-meaning.md#control-ensure-foreground-content-is-not-obscured-by-background |
| 3.11 | Explain Implied Content | Clear Meaning | Spell out idioms, expand abbreviations, define references | Confirm content does not assume cultural or contextual knowledge | objective-clear-meaning.md#control-explain-implied-content |
| 3.12 | Provide Alternatives for Numerical Concepts | Clear Meaning | Visualisations, comparisons, plain-language equivalents | Confirm numbers and percentages have non-numeric alternatives | objective-clear-meaning.md#control-provide-alternatives-for-numerical-concepts |
| 3.13 | Support Different Modalities | Clear Meaning | Text, image, audio, video alternatives | Confirm critical content is reachable via at least two modalities | objective-clear-meaning.md#control-support-different-modalities |
| 4.1 | Ensure Controls and Content Do Not Move Unexpectedly | Error Prevention | Stable layouts, no auto-shifts, predictable insertions | Confirm targets remain stable while users interact with the page | objective-error-prevention-recovery.md#control-ensure-controls-and-content-do-not-move-unexpectedly |
| 4.2 | Let Users Go Back | Error Prevention | Back button works, undo for actions, no trap pages | Confirm browser back and explicit back navigation always work | objective-error-prevention-recovery.md#control-let-users-go-back |
| 4.3 | Notify Users of Fees and Charges at the Start of a Task | Error Prevention | Upfront pricing disclosure, hidden-fee avoidance | Confirm all costs are disclosed before any commitment is made | objective-error-prevention-recovery.md#control-notify-users-of-fees-and-charges-at-the-start-of-a-task |
| 4.4 | Design Forms to Prevent Mistakes | Error Prevention | Minimal fields, clear labels, format examples, inline validation | Confirm forms reduce required input and validate as users type | objective-error-prevention-recovery.md#control-design-forms-to-prevent-mistakes |
| 4.5 | Make it Easy to Undo Form Errors | Error Prevention | Saved drafts, retained input on error, undo affordances | Confirm partial form data persists after a validation failure | objective-error-prevention-recovery.md#control-make-it-easy-to-undo-form-errors |
| 4.6 | Use Clear Visible Labels | Error Prevention | Persistent visible labels, no placeholder-only labels | Confirm labels remain visible after the user types | objective-error-prevention-recovery.md#control-use-clear-visible-labels |
| 4.7 | Use Clear Step-by-step Instructions | Error Prevention | Numbered steps, one action per step, examples | Confirm multi-step flows have explicit step indicators and examples | objective-error-prevention-recovery.md#control-use-clear-step-by-step-instructions |
| 4.8 | Accept Different Input Formats | Error Prevention | Flexible date, phone, address parsing | Confirm common input formats are accepted without strict masks | objective-error-prevention-recovery.md#control-accept-different-input-formats |
| 4.9 | Avoid Data Loss and Timeouts | Error Prevention | No arbitrary timeouts, autosave, timeout warnings | Confirm no required rapid response; timeouts are warned and extendable | objective-error-prevention-recovery.md#control-avoid-data-loss-and-timeouts |
| 4.10 | Provide Feedback | Error Prevention | Confirmation messages, status updates, undo prompts | Confirm every user action produces visible or audible feedback | objective-error-prevention-recovery.md#control-provide-feedback |
| 4.11 | Help the User Stay Safe | Error Prevention | Warnings before risky actions, confirmation prompts | Confirm destructive or costly actions require confirmation and are reversible | objective-error-prevention-recovery.md#control-help-the-user-stay-safe |
| 4.12 | Use Familiar Metrics and Units | Error Prevention | Locale-appropriate units, conversions, plain labels | Confirm units match user locale or provide conversions | objective-error-prevention-recovery.md#control-use-familiar-metrics-and-units |
| 5.1 | Help Users Focus | Focus | Minimise distractions, prioritise one task at a time | Confirm pages do not present competing concurrent demands on attention | objective-supports-attention.md#control-help-users-focus |
| 5.2 | Make Short Critical Paths | Focus | Few steps to complete core tasks, streamlined flows | Confirm primary tasks complete in the smallest practical number of steps | objective-supports-attention.md#control-make-short-critical-paths |
| 5.3 | Avoid Too Much Content | Focus | Limit on-screen items, three to six functions, brief content | Confirm visible content is bounded and avoids dense paragraphs | objective-supports-attention.md#control-avoid-too-much-content |
| 6.1 | Ensure Processes Do Not Rely on Memory | Memory | Persistent information, repeated context across steps | Confirm users do not need to recall data from prior screens | objective-minimise-memory-load.md#control-ensure-processes-do-not-rely-on-memory |
| 6.2 | Let Users Avoid Navigating Voice Menus | Memory | Text alternative to voice IVR, skip-prompts, quick keys | Confirm voice or phone flows have text equivalents or shortcuts | objective-minimise-memory-load.md#control-let-users-avoid-navigating-voice-menus |
| 6.3 | Do Not Rely on User Calculations or Memorising Information | Memory | Provide calculated values, avoid memorisation for security | Confirm calculations are done for the user; auth does not require recall puzzles | objective-minimise-memory-load.md#control-do-not-rely-on-user-calculations-or-memorising-information |
| 7.1 | Clearly State the Results and Disadvantages of Actions, Options, and Selections | Help | Outcome descriptions, warnings about consequences | Confirm each choice explains what it does and what changes | objective-feedback-confirmation.md#control-clearly-state-the-results-and-disadvantages-of-actions-options-and-selections |
| 7.2 | Provide Help for Forms and Non-standard Controls | Help | Inline help, examples, password rules, control-specific docs | Confirm complex inputs have inline accessible help | objective-feedback-confirmation.md#control-provide-help-for-forms-and-non-standard-controls |
| 7.3 | Make It Easy to Find Help and Give Feedback | Help | Persistent help link, multiple support channels | Confirm help is reachable from every page and offers multiple channels | objective-feedback-confirmation.md#control-make-it-easy-to-find-help-and-give-feedback |
| 7.4 | Provide Help with Directions | Help | Step-by-step guidance, wayfinding, tooltips | Confirm tasks include clear contextual directions and visual aids | objective-feedback-confirmation.md#control-provide-help-with-directions |
| 7.5 | Provide Reminders | Help | Reminders for recurring tasks, confirmation of important actions | Confirm scheduled or repeated tasks support reminder hooks | objective-feedback-confirmation.md#control-provide-reminders |
| 8.1 | Let Users Control When the Content Moves or Changes | Adapt | User-initiated motion, pause controls, no auto-launching pop-ups | Confirm animation and auto-rotation have user-accessible controls | objective-user-control.md#control-let-users-control-when-the-content-moves-or-changes |
| 8.2 | Enable APIs and Extensions | Adapt | Compatible with assistive add-ons, password managers, simplifiers | Confirm pages do not block accessibility-enhancing browser extensions | objective-user-control.md#control-enable-apis-and-extensions |
| 8.3 | Support Simplification | Adapt | Simplified-view toggle, three to six core functions in simplified mode | Confirm a low-complexity alternative view is available where practical | objective-user-control.md#control-support-simplification |
| 8.4 | Support a Personalised and Familiar Interface | Adapt | Customisable layout, colours, terminology, system-preference respect | Confirm user preferences are honoured and persisted across visits | objective-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, aDesign patternslist of implementation approaches, anAssessment heuristicslist 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-controlsand 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-labelor 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-liveregions 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-provide-search
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-motionuser preference.Disable autoplay for video and animation by default.
Avoid using motion as the sole indicator of state.
Assessment heuristics:
Confirm
prefers-reduced-motiondisables 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.
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