Hax A11y Audit

HAX Accessibility Audit (WCAG 2.0 AA — Read-Only Diagnostic)

Review authored content on an existing HAX site/page against WCAG 2.0 AA and emit a diagnostic + remediation report. This skill diagnoses and recommends only — it does not edit pages, mutate site.json, or insert components. It mirrors the hax-udl-audit and hax-ubd-unit-audit pattern but operates through the WCAG lens: does the authored content meet the technical access standard for people with disabilities?

The worldview in one paragraph

WCAG 2.0 AA is an explicit HAX ecosystem pillar — the ecosystem commits to it in its community pillars and component audits — yet no existing skill audits authored content for it. This skill fills that gap. WCAG is about technical access for people with disabilities: can a screen-reader user perceive the content, can a keyboard-only user operate it, is contrast sufficient for low-vision users, are media alternatives present. This is distinct from UDL (pedagogical inclusivity — multiple means of reaching diverse learners), from content chunking (cognitive load — is the page a wall of text), and from component-internal accessibility (a custom element's own shadow-DOM ARIA/keyboard, which hax-webcomponent-dev owns). Much of WCAG remediation on a HAX site is plain HTML: alt text, semantic headings, landmark roles, link text, scope/headers/caption on tables. The rest maps to real HAX components that bake accessibility in. This audit reports what fails, cites the WCAG criterion, and recommends only real remediation — never an invented tag.

When to Use

Trigger conditions:

• "Is this accessible" / "audit for WCAG" / "check my page for accessibility"
• "Does this meet WCAG 2.0 AA" / "screen reader test" / "accessibility audit"
• "Are my images described" / "is my color contrast OK" / "do my videos have captions"
• "Can a keyboard user get through this page" / "is my heading order right"
• even when the user does not say "WCAG" or "a11y" — if they question whether authored content is perceivable, operable, understandable, or robust for users with disabilities, this is the skill

When NOT to use (with redirect):

• Component-INTERNAL accessibility (a custom element's own shadow DOM ARIA/keyboard/tabindex) → hax-webcomponent-dev
• Pedagogical inclusivity / multiple means / learner agency → hax-udl-audit
• Page-scope cognitive load / "wall of text" / chunking → hax-content-chunking-audit
• DDD/CSS token-usage compliance (is the DDD token used at all) → hax-design-system
• MEDIA DEPTH (caption quality/timing/accuracy, transcript fidelity, audio-description authoring/coverage, asset production) → hax-media-a11y (this skill flags media caption/transcript/audio-description presence as a WCAG 1.2 finding and hands off to hax-media-a11y for depth + asset production — see the overlap rule below)
• Unit alignment / backward design → hax-ubd-unit-audit
• Cognitive level of an objective/assessment → grad-blooms

Scope: this skill is READ-ONLY

This skill diagnoses and recommends only. It produces a report. To apply remediation, hand off to the related skills and the hax CLI / hax-claudehax (see "Implementing the Recommendations" below). Never edit pages/*.html or site.json from within this skill.

Inputs

• a HAX site path: site.json (JOS tree) + pages/*.html, or a single page (JOS node / raw HTML / markdown)
• optional pageSlug to scope the audit to one page (else audit every page and report site-level patterns)
• optional reference to the DDD token values for contrast computation (the skill can read d-d-d tokens from the sibling repo if needed)

Methodology

1. Ingest structure. Locate the page(s) in the HAX project:
   • site.json (JSON Outline Schema) for the node tree + metadata
   • pages/<slug>.html for rendered page content (the canonical content source)
   • a JOS items export or markdown representation for offline review
2. Run the WCAG 2.0 AA checks across authored content. For each page, evaluate:
   • 1.1 Text Alternatives (1.1.1): every <img>, media-image, a11y-figure, or background-image carrying information has meaningful alt text. Decorative images get alt="" (or aria-hidden="true" on simple-icon-lite) — not missing alt, not alt="image". Flag both missing-alt and junk-alt (alt="placeholder", alt="arrow").
   • 1.3 Adaptable / heading hierarchy (1.3.1): exactly one h1 per page; no skipped levels (no h2 → h4); headings used for structure, not styling. Flag the skip location.
   • 1.3 Adaptable / landmarks (1.3.1): page content uses semantic landmarks (header, nav, main, article, aside, footer) or equivalent ARIA roles. Flag a page with no main landmark or div-soup structure.
   • 1.4 Distinguishable / contrast (1.4.3 text, 1.4.11 UI): authored text and UI components meet 4.5:1 (normal text < 18pt / 14pt bold) or 3:1 (large text ≥ 18pt / 14pt bold, and UI component boundaries). Compute ratios against the DDD token values the page uses. Report the actual ratio and the token pair. (Token usage compliance — did the author use a DDD token at all — is hax-design-system's job; contrast checking against token values is this skill's job.)
   • 2.4 Navigable / link text (2.4.4, 2.4.9): no "click here", "read more", "learn more", or bare URLs as link text. Every link's purpose is clear from the link text alone (or link text + context). Flag each ambiguous link with its text and href.
   • 2.4 Navigable / focus order (2.4.3): authored interactive markup (custom buttons, tabbed interfaces, collapsible sections) is keyboard-reachable in a logical order. Flag tabindex values that are positive (anti-pattern) or authored elements that lack keyboard access.
   • 3.3 Input Assistance / form labels (3.3.2): every authored form field has a programmatic label (<label for=...>, aria-label, or aria-labelledby). Flag unlabelled <input>, <select>, <textarea> in authored content.
   • 4.1 Compatible / ARIA correctness (4.1.2): authored ARIA is valid — role matches the element's function, aria-label/aria-labelledby on interactive elements, aria-hidden="true" on presentational icons, no redundant roles on native semantics (e.g. <button role="button"> is redundant). Flag each violation with the exact markup.
   • 1.3 Data tables (1.3.1): data tables use <caption>, scope on <th> (or headers/id for complex tables), and are not used for layout. Flag tables missing these.
   • 1.3 List semantics (1.3.1): lists use <ul>/<ol>/<dl>; do not flag styled lists that are genuinely presentational.
   • 1.2 Media alternatives (1.2.1, 1.2.2, 1.2.3, 1.2.5): every video-player / audio-player / a11y-media-player with audio has a track (captions) present; video has either captions or an audio-description track (audio-description-source); audio has a transcript link or slotted transcript. Flag presence only — caption quality/timing/accuracy, transcript fidelity, and audio-description authoring/coverage are hax-media-a11y's depth scope (see overlap rule).
3. Map each finding to a real HAX remediation. Use references/a11y-element-map.md. Every recommendation is either a component swap (replace the failing markup with a real HAX component that bakes in the accessibility) or a plain-HTML fix (edit the markup in pages/<slug>.html directly — alt text, headings, landmarks, link text, table markup). Never invent a tag name and never recommend a legacy tag (instruction-card, lrndesign-sidenote, link-preview, model-viewer are excluded).
4. Apply the overlap / defer rules:
   • Media depth (SYMMETRIC with hax-media-a11y): when a media finding is about caption quality, transcript fidelity, or audio-description authoring/coverage, defer to hax-media-a11y. This skill reports media presence (is there a track at all?) as a WCAG 1.2 finding and hands the depth work off. State this split explicitly in the finding so the orchestrator knows where to send the follow-up. This rule is symmetric: if hax-media-a11y discovers a presence gap (no track file exists), it should hand back to this skill to file the WCAG 1.2 finding.
   • Component-internal a11y: if the failure is inside a custom element's shadow DOM (the element's own tabindex/ARIA/keyboard), defer to hax-webcomponent-dev.
   • Pure token usage: if the only issue is "the author hardcoded a hex color instead of a DDD token," that is hax-design-system's scope. This skill only checks contrast ratios against the tokens the page actually uses.
   • Cognitive load / chunking: if the page is a wall of text, that is hax-content-chunking-audit's scope — do not double-report it as a WCAG finding.
5. Determine the overall rating:
   • Compliant: all checked criteria pass; no Level A or AA failures. Minor advisories (e.g. "consider a longer description for this complex diagram") may be noted but do not affect the rating.
   • Partial: one or more Level A/AA failures are present but the page is fundamentally perceivable/operable (e.g. a few missing alt texts, one heading skip, one ambiguous link). Remediation is surgical.
   • Non-compliant: a structural failure that blocks access — e.g. no main landmark, a full-screen keyboard trap, contrast below 3:1 on body text, or zero media alternatives on a media-heavy page.
6. Emit the report (format below), then an "Implementation handoff" block.