hatch3r-a11y-audit

id	hatch3r-a11y-audit
name	hatch3r-a11y-audit
type	skill
description	Runs a WCAG AA accessibility audit with findings and fixes across 7 scan categories (keyboard, contrast, ARIA, reduced motion, screen reader, high contrast, automated axe). Use when auditing and remediating accessibility.
tags	["review","floor:ui-ux","a11y"]
quality_charter	agents/shared/quality-charter.md
efficiency_patterns	agents/shared/efficiency-patterns.md
cache_friendly	true

Accessibility Audit Workflow

Quick Start

Task Progress:
- [ ] Step 0: Detect ambiguity (P8 B1)
- [ ] Step 1: Read accessibility requirements from rules and specs
- [ ] Step 2: Automated scan — run axe-core or similar on all pages/components
- [ ] Step 3: Manual audit — load references/manual-audit-checklist.md
- [ ] Step 4: Catalog findings by severity (critical/major/minor)
- [ ] Step 5: Fix critical and major findings
- [ ] Step 6: Verify fixes with re-scan and manual check

Step 0 — Detect Ambiguity (P8 B1)

Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: WCAG conformance target (A vs AA vs AAA), scope (single component vs full app), surfaces to audit (which routes), fix authority (audit-only vs audit-and-fix), and screen-reader pass scope (per release vs per audit).

Fan-out Discipline (P8 B2)

Fan-out scales with task size; token cost never justifies serializing independent work (rules/hatch3r-fan-out-discipline.md P8 B2; agents/shared/efficiency-patterns.md). Emit sub_agents_spawned: { count, rationale, task_structure } in your output.

Relationship to the verification gates

This skill is the accessibility audit-and-fix WORKFLOW — enumerate violations (Steps 2-4), fix critical and major findings (Step 5), re-verify (Step 6). Its unique value is that fix loop plus the 7-category manual audit in references/manual-audit-checklist.md; no gate re-runs those. Two sibling skills own the pass/fail side of the same WCAG territory:

• skills/hatch3r-ui-ux-verify/SKILL.md — the pass/fail GATE. Its Gate 1 (axe-core), Gate 2 (keyboard trace), and Gate 3 (accessibility-tree snapshot) supersede this skill's Step 2 automated scan when both run in one flow: cite the gate's verdict instead of re-scanning the same routes.
• skills/hatch3r-browser-verify/SKILL.md — the Playwright execution layer that hatch3r-ui-ux-verify Gates 1/3/5 call.

Delegation chain: this skill's Required Agent Delegation spawns agents/hatch3r-ui.md (CQ1), and hatch3r-ui runs hatch3r-ui-ux-verify as its gate — so a11y-audit → hatch3r-ui → hatch3r-ui-ux-verify. No duplication: this skill owns the audit-and-fix workflow; the gate owns the pass/fail verdict.

Progressive Disclosure

• Main skill file (this): Workflow steps, automated scan, fix process, DoD.
• references/manual-audit-checklist.md: Detailed WCAG requirements matrix, per-category manual criteria, severity cataloging rubric. Load during Step 3.

Step 1: Read Accessibility Requirements

From project component rules (Accessibility section):

• All animations: wrap in prefers-reduced-motion media query AND check user's reduced motion setting.
• Color contrast: >= 4.5:1 for text (WCAG AA).
• Interactive elements: keyboard focusable with visible focus indicator.
• Dynamic content changes: use aria-live regions.
• Support high contrast mode.

For the full WCAG requirements matrix, load references/manual-audit-checklist.md.

For external library docs and current best practices, follow the project's tooling hierarchy.

Step 2: Automated Scan

• Install and run @axe-core/vue, vitest-axe, or Playwright's @axe-core/playwright on all pages and key components.
• Run against: main routes, key components (if testable in isolation).
• Capture all violations. Map to WCAG criteria (e.g., 1.1.1, 1.4.3, 2.1.1, 4.1.2).
• Document: rule ID, description, impact, elements affected, WCAG level.

Step 3: Manual Audit

Load references/manual-audit-checklist.md and work through each category:

1. Keyboard navigation
2. Color contrast
3. ARIA attributes
4. Reduced motion
5. Screen reader
6. High contrast mode

The reference file provides the specific criteria, DevTools settings, and pass/fail conditions for each.

Step 4: Catalog Findings

Use the severity rubric in references/manual-audit-checklist.md to assign severity. Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion. Prioritize critical first, then major. Minor can be batched.

Step 5: Fix Critical and Major Findings

• Implement fixes following project component and quality requirements.
• Use semantic HTML where possible (<button>, <a>, <nav>, <main>).
• Add aria-* attributes for custom components.
• Verify prefers-reduced-motion is respected by enabling the media query in DevTools and confirming animations are disabled or simplified.
• Add or fix focus styles. Use design tokens for focus ring.
• Verify reduced-motion behavior in tests.

Step 6: Verify Fixes

• Re-run automated scan. No critical or major violations.
• Manual keyboard and screen reader check on fixed areas.
• Run full test suite and confirm 0 failures to verify no regressions.
• Document remaining minor findings for future backlog.

Required Agent Delegation

You MUST spawn these agents via the Task tool (subagent_type: "general-purpose") at the appropriate points:

• hatch3r-ui (CQ1) — MUST spawn to perform the full WCAG AA compliance audit autonomously (axe-core + design-token + four-state + deep ARIA / reduced-motion). Provide the list of surfaces/components to audit and the current violation list.

Related Rules

• Rule: hatch3r-browser-verification — follow this rule for live browser-based accessibility testing

Error Handling

• No automated scanner available: If axe-core, Lighthouse, or equivalent is not installed, report the gap and proceed with manual checklist-only audit. Do not skip the audit.
• Scanner produces false positives: Cross-reference automated findings against manual inspection. Mark confirmed false positives with justification and exclude from the violation count.
• Component renders differently across browsers: Test in at least two browser engines (Chromium + Firefox or Safari). Document browser-specific a11y gaps with reproduction steps.

Definition of Done

• No critical a11y violations
• WCAG AA compliance on all audited surfaces
• Reduced motion respected (prefers-reduced-motion + user setting)
• Keyboard navigation complete with visible focus
• Color contrast >= 4.5:1 for text
• ARIA live regions for dynamic content
• Automated scan clean for critical/major
• Manual verification completed

References

• WCAG 2.2 — W3C Recommendation — accessed 2026-05-31, official-docs (W3C). Source for the success criteria (1.1.1, 1.4.3, 2.1.1, 4.1.2) and the 4.5:1 AA text-contrast ratio cited above.
• axe-core rules and WCAG mapping — accessed 2026-05-31, independent-analysis (Deque Systems). Source for the automated-scan rule IDs and impact levels mapped to WCAG criteria in Step 2.