WCAG 2.1 AA accessibility audit and conformance

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/wcag-2-1-aa-accessibility-audit-and-conformance/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Audits storefront and admin UI for WCAG 2.1 AA compliance (color contrast, keyboard nav, screen reader, semantic HTML, form labels, alt text on images). Publishes conformance claim and remediation roadmap.

The problem

My storefront has partial accessibility support but no audit. EU Accessibility Act (28 June 2025 deadline) makes this legally mandatory. I can’t claim compliance without evidence.

What it does

• Automated scan: run axe-core / WAVE on all public pages (home, product list, product detail, cart, checkout, account, order history)
• Manual audit: review keyboard navigation (Tab, Enter, Esc), screen reader output (NVDA, JAWS), color contrast ratio (4.5:1 for text)
• Admin UI audit: run scan on order detail, customer list, settings, catalog; verify keyboard navigation in forms
• Issue triage: categorize findings by severity (fail, needs review, pass) and status (remediated, deferred, won’t fix with reason)
• Remediation: fix critical issues (missing alt text, low contrast, missing form labels, broken keyboard nav)
• Conformance report: publish VPAT 2.4 (Voluntary Product Accessibility Template) or ATAG statement for admin
• Accessibility statement: publish on website and privacy policy linking to conformance report
• Periodic re-audit: schedule annual audit (manual); quarterly automated scans in CI
• Testing tools: document which screen readers/keyboards tested (NVDA + keyboard, JAWS + keyboard)
• Training: staff docs for maintaining accessibility (alt text on new images, semantic HTML in templates)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• PDF accessibility: out of scope—invoices/labels are PDFs; no remediation. Reason: separate spec (PDF/UA); deferred to later phase.
• Mobile app accessibility: out of scope—storefront is web-only (Next.js SSR). Reason: scope is web.
• Live chat accessibility: out of scope—no live chat in core. Reason: out of feature scope.
• Third-party plugin accessibility (e.g., custom extensions): out of scope—plugin authors responsible. Reason: system cannot audit external code.
• Video captions and transcripts: out of scope—merchants responsible for their own video content. Reason: outside CMS scope.
• Real-time accessibility testing (continuous): out of scope—annual audit + quarterly CI scans only. Reason: budget constraint.

Data model

No new entities. Accessibility audit results stored as JSON in settings (key: ‘accessibility_audit_report’); conformance claim as HTML static asset.

API

• GET /admin/accessibility/audit-status → {last_audit_date, fail_count, needs_review_count, pass_count, next_scheduled_audit}
• POST /admin/accessibility/run-audit (staff, background job) → {audit_id, status: ‘running’}
• GET /admin/accessibility/audit/:id → {audit_id, results: [{issue, severity, element, remediation_status}], summary}
• PUT /admin/accessibility/audit/:id/issue/:issue_id (staff, body: {status: ‘remediated’ | ‘deferred’ | ‘wont_fix’, notes}) → {issue_id, status}
• GET /.well-known/accessibility (public) → {conformance_level: ‘WCAG2.1AA’, conformance_date, audit_report_url, statement_url}

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Accessibility section in settings. Dashboard shows audit status (pass/fail/review counts), last audit date, next scheduled. Run Audit button starts background job. Audit report lists issues by page, severity, and remediation status. Issue detail shows screenshot, remediation steps, and notes field for team.

The seam — why this is core

Core owns automated and manual audit methodology, remediation, and conformance claim publication. Paid pack owns: continuous monitoring (24/7 re-scans), AI-assisted remediation suggestions, VPAT 3.0 (EU standard) generation, legal review of conformance claim. Why: core provides honest audit and remediation; legal liability and continuous monitoring are paid.

Legal compliance obligation. Merchants cannot delegate this risk if platform won’t.

Dependencies

• storefront-rendering (Next.js SSR must emit semantic HTML)
• admin-ui (HTML structure must be accessible)
• settings (audit results stored as key/value)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Automated scan of /products page detects image missing alt text; issue logged as ‘fail’
• Manual audit finds Tab does not move focus in cart quantity input; logged as keyboard navigation fail
• Color contrast scan shows form labels 6:1 ratio (PASS) but button text 3:1 (FAIL); issue logged
• Staff remediate button color issue; status changed to ‘remediated’; re-scan confirms pass
• Conformance report published at GET /.well-known/accessibility with WCAG2.1AA claim and link to full report
• Quarterly CI scan runs automatically; new issues flagged in Slack webhook
• VPAT statement includes admin UI audit results; accessibility@site.com provided as contact
• Product detail page alt text added; re-scan passes. Issue marked remediated with date.
• Deferred issue (live chat): status=‘deferred’, notes=‘live chat planned Q4 2026’
• Accessibility statement on privacy page links to conformance report and provides accessible format request email

Risks

Audit accuracy: automated scans miss ~20% of issues; manual audit is expensive and infrequent. Remediation: if alt text is added but screen reader cache not cleared, old text still heard. Legal: conformance claim without full audit exposes merchant to accessibility lawsuit. Continuous: without ongoing scans, regressions introduced in new features (images without alt, contrast changes) slip through. Third-party: plugins may break accessibility; no enforcement mechanism.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.