Accessibility Audit (WCAG 2.1 AA)

This skill audits media against WCAG 2.1 Level AA — the technical standard the U.S. Department of Justice incorporated into its April 2024 ADA Title II final rule and the standard most courts and procurement contracts use as the practical floor for ADA compliance.

Core philosophy

Three principles drive every decision in this skill:

1. Deterministic CLIs first, judgment second. Token cost compounds across long audits. Every check that an off-the-shelf tool can decide should be delegated to that tool. Save Claude's reasoning budget for the things that genuinely need it: alt-text quality, caption accuracy, reading-order sanity, and ambiguous gray-area calls. If a question can be answered by axe, verapdf, or ffprobe, those tools answer it.

2. Practicality over performative purity. A 100% WCAG pass rate is rarely achievable without flattening legitimate design intent, and pretending otherwise wastes everyone's time. The skill grades findings on severity (blocker / major / moderate / advisory), respects WCAG's own essential-content exceptions (1.4.5, 1.4.10, etc.), honors the user's declared target viewports, and remembers documented exceptions across runs via the accessibility-context.yaml file. Read references/severity-model.md for the grading framework and references/exception-catalog.md for the built-in WCAG exceptions.

3. Honest about the gap. Automated tooling catches roughly 30–60% of real-world accessibility issues depending on media type and source (Deque's 2021 benchmark put axe-core at 57.38% by issue volume; the long-standing industry rule of thumb is closer to 30–40% for scanners generally). The remaining 40–70% needs human review or LLM judgment. Every finding carries a review_status field so the consumer knows exactly which bucket a result came from. Never claim conformance the tooling can't substantiate.

When this skill triggers, do this first

Before running any analysis, gather these three pieces of context. They change everything downstream.

Target subject(s). What is being audited? A URL, a local file, or a directory? If a directory, recurse and route each file by type. If the user points at a single file, infer the media type from extension and content (file --mime-type for ambiguous cases).

Conformance target. Default to WCAG 2.1 AA. If the user explicitly asks for 2.2 AA, AAA, or Section 508, note it and adjust the reference data load. If the user has not specified a conformance target, default silently to WCAG 2.1 AA and record the assumption in audit_metadata.assumed_defaults. Do not ask — the cost of being wrong is recorded in the report header and the user can correct course on the next run.

Practical context. Look in the current directory (or repo root) for accessibility-context.yaml. If it exists, load it — it declares target viewports, accepted exceptions with rationale, audience, and known compromises. Treat declared exceptions as resolved findings unless the user asks for a "strict" audit. If no file exists, default target_viewports to [mobile, desktop] and record the assumption in audit_metadata.assumed_defaults. Mention in the chat summary that no context file was found and offer to scaffold one from assets/example-accessibility-context.yaml after the audit completes. Do not block on a question.

The four-bucket review-status model

Every finding the skill emits falls into one of four buckets. This is the central abstraction — keep it straight in the output and the user can triage instantly.

Never mark something definite based on Claude's judgment alone. If you reasoned it through, it's llm_judged — that distinction is the user's trust signal.

Routing: which runner for which media

Detect the media type, then read the corresponding reference file in references/runners/ for the full procedure. Do not try to remember all six procedures from this file — each runner doc has its tool versions, invocation flags, output-parsing details, and known gotchas. Read the one you need; ignore the rest.

For directories, route each file then merge the per-file reports into one consolidated EARL JSON. The merger logic lives in scripts/merge_reports.py.

Output format

The skill produces a single EARL-influenced JSON file as its primary output, plus an optional human-readable HTML report. The JSON schema is documented in detail in references/earl-schema.md. The shape, at a glance:

{
  "@context": "https://act-rules.github.io/earl-context.json",
  "audit_metadata": {
    "skill_version": "0.1.0",
    "conformance_target": "WCAG 2.1 AA",
    "context_file": "accessibility-context.yaml" ,
    "target_viewports": ["mobile", "desktop"],
    "timestamp": "2026-05-27T14:09:00Z"
  },
  "summary": {
    "subjects_audited": 1,
    "findings_by_severity": { "blocker": 2, "major": 5, "moderate": 11, "advisory": 8 },
    "findings_by_status": { "definite": 9, "needs_human_review": 12, "llm_judged": 4, "out_of_scope": 1 },
    "wcag_criteria_with_findings": ["1.1.1", "1.4.3", "2.4.4"]
  },
  "subjects": [
    {
      "source": "file:///path/or/url",
      "media_type": "html",
      "findings": [
        {
          "wcag_sc": "1.4.3",
          "wcag_title": "Contrast Minimum",
          "level": "AA",
          "outcome": "failed",
          "severity": "major",
          "review_status": "definite",
          "tool": "[email protected]",
          "rule_id": "color-contrast",
          "selector": "html > body > main > p.byline",
          "message": "Element has insufficient color contrast of 3.2 (foreground #888 on background #fff)",
          "exception_eligible": false,
          "suggested_fix": "Increase foreground contrast to at least 4.5:1 for normal text"
        }
      ]
    }
  ]
}

The HTML report renderer is scripts/render_report.py and reads this JSON.

Output files

All artifacts from a single run go in one directory: ./audit-output/<UTC-ISO-timestamp>/, where the timestamp is YYYY-MM-DDTHHMMSSZ (filesystem-safe). Inside that directory:

• report.json — the final EARL-influenced JSON described in references/earl-schema.md. This is the primary deliverable.
• report.html — the rendered HTML view, produced by scripts/render_report.py from report.json. Always produce this; users skim it before opening the JSON.
• per-subject/<sha1-of-source>.json — the classified finding list for each subject before merging. Useful for debugging and for the user to inspect per-file detail.
• raw/<sha1-of-source>/ — raw tool outputs (axe.json, pa11y.json, etc.) for that subject. Useful when a finding is contested.
• preflight.json — what scripts/preflight.py found at run start. Includes tools_invoked (with versions) and tools_missing (with reasons).

Always write to that directory. Do not write artifacts to the working directory root. When you're done, mention the absolute path to report.html in the chat summary so the user can open it.

What you must NOT do

• Never re-implement deterministic checks in Claude. If axe can answer "does this image have alt?", you call axe. Re-reasoning about it from raw HTML is a token-waste and an accuracy regression.
• Never silently skip findings the user might disagree with. Every finding goes in the report. If the user has declared an exception in accessibility-context.yaml, mark the finding as exception_eligible: true and outcome: "exception_claimed", but still include it. Hiding findings breaks trust.
• Never claim WCAG conformance on the user's behalf. The skill produces an audit report. Conformance claims are formal statements that require human attestation. The report can say "no automated violations detected at WCAG 2.1 AA in scanned subjects" but must not say "this site is WCAG 2.1 AA compliant."
• Never mark `definite` based on Claude's reasoning. If a tool didn't decide it, the bucket is llm_judged or needs_human_review. This is the trust contract.
• Never bundle the tools themselves into this repo. The skill invokes them as external processes. The user installs them per references/runners/*.md install sections, or the skill runs an install-check at start and tells the user what's missing.

Workflow

1. Detect media type(s) for the subject(s).
2. Load accessibility-context.yaml if present.
3. Pre-flight: run `python scripts/preflight.py --media <detected-media-types> --out audit-output/<timestamp>/preflight.json`.
   Read the result. If a runner's primary tool is missing (axe for web, ffprobe for video/audio, etc.),
   tell the user the install command from preflight.json and ask whether to proceed without it.
   If only secondary tools are missing, proceed and note in the report.
4. For each subject:
   a. Read the appropriate references/runners/<media>.md for the procedure.
   b. Invoke the deterministic tool(s) via scripts/run_<media>.{sh,py}.
   c. For runners with structured normalization, run or use scripts/build_subject_report.py
      to convert raw outputs into per-subject JSON.
   d. For findings that require LLM judgment (per the runner doc's "Judgment handoffs" section),
      reason about them and attach review_status: llm_judged with a rationale.
5. Run scripts/classify.py to apply the four-bucket review-status logic and severity grading.
6. Apply accessibility-context.yaml exceptions to mark exception_eligible findings.
7. Merge per-subject reports via scripts/merge_reports.py into audit-output/<timestamp>/report.json.
8. Always render audit-output/<timestamp>/report.html via scripts/render_report.py.
9. Summarize for the user in chat: total findings by severity, top 3 most-impactful issues by
   (severity, then review_status), and the absolute path to report.html.

A note on practicality

This skill is opinionated about not being precious. Accessibility is a craft, not a checkbox — and the worst accessibility tools are the ones that cry wolf so loudly that teams stop listening. If a finding is advisory-severity on a low-traffic legalese page, say so. If a contrast ratio is 4.48:1 instead of 4.5:1 on a hero headline, that's a moderate worth fixing but not a blocker. If the user has documented in accessibility-context.yaml that their data-density admin table doesn't reflow at 320px because nobody administers SQL on a phone, respect that and stop re-flagging it.

The goal is shippable, defensible audits that move real teams toward real accessibility — not a wall of red that gets ignored.