WCAG 2.1 Compliance Checker

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/wcag-2-1-compliance-checker/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core-free accessibility auditor that runs against the live storefront and published posts, reports WCAG 2.1 AA violations (contrast, alt text, heading hierarchy, form labels, keyboard navigation), and flags them in the admin for the merchant to fix. No automatic remediation — the merchant owns the fix; AstroBaaS provides the scanner.

The problem

Merchants do not know if their site is accessible. Disabled users cannot navigate it and leave. The merchant faces ADA lawsuits (USA, approximately USD 8,000–100,000 per instance) and AODA fines (Canada, CAD 50,000–250,000). No tools built into the CMS to audit compliance.

What it does

• Accessibility audit engine that validates the public site against WCAG 2.1 level AA rules (headings, contrast, alt text, form labels, ARIA, keyboard nav)
• Admin scan trigger (manual or scheduled) that crawls public pages and returns a list of issues per page
• Issues reported with rule identifier (WCAG rule code), severity (error/warning), page URL, element selector, and remediation hint
• Results dashboard showing pass/fail per page, trend over time (if rescanned), and drill-down to individual issues
• Accessibility report exportable as CSV/JSON for audit or legal defense
• Settings option to exclude URLs from scanning (e.g., archived pages, demo content)
• Integration with post editor: accessibility checks run in the editor as the merchant writes and surface inline hints (no server round trip)

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.

• No automatic remediation — AstroBaaS cannot rewrite merchant content (reason: accessibility fixes are design decisions, not algorithm outputs; a merchant must own the fix)
• No real device or screen-reader testing — the scanner uses heuristic rules only (reason: genuine accessibility testing requires blind users and real assistive tech; this is a static checker)
• No Third-party iframe/embed scanning — iframes are not on the sanitizer allow-list anyway (reason: embedded content is not under the merchant’s control)

Data model

New AccessibilityIssue entity: {page_url, rule_code (WCAG rule), severity, element_selector, message, hint, first_seen_date, last_seen_date, dismissed_by_admin (boolean)}. Settings key: a11y_scan_schedule (cron) and a11y_excluded_urls (array). No schema migration; optional feature.

API

• POST /api/accessibility/scan (start a new audit, returns scan_id and status)
• GET /api/accessibility/scans/:id (poll scan progress)
• GET /api/accessibility/results/:scan_id (fetch issues from a completed scan)
• POST /api/accessibility/issues/:id/dismiss (merchant acknowledges an issue, won’t re-report)
• GET /api/accessibility/report (export results as CSV or JSON)

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

Admin

Admin dashboard gains ‘Accessibility’ tab showing scan results, trend chart (pass/fail over scans), and issue drill-down (page → issue → selector + hint + screenshot). Scan trigger button with optional schedule. Settings → Accessibility: configure excluded URLs and scan schedule. Post editor sidebar shows real-time a11y checks as the merchant types (no server call; runs in-browser via lightweight algorithm).

The seam — why this is core

Core owns the scanner and issue storage. Merchants own the remediation. Themes and plugins must not add inaccessible markup (they already don’t, per CSP + sanitizer). The scanner is purely advisory; there is no enforcement gate.

Core owns the interface + honest accessibility auditor; compliance is infrastructure, not a per-country obligation or credential.

Dependencies

• Public URL router (core)
• Post editor (core)
• Settings (core)
• Crawler/DOM parser library (axe-core or similar, external dependency)

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.

• Scanning a page with a heading that skips levels (h1 → h3) reports ‘Heading hierarchy violation’
• Scanning a page with text <5.5:1 contrast ratio reports ‘Contrast ratio’ violation with measured ratio and guideline value
• Scanning a page with an image that has empty alt text (alt=”) reports nothing; explicit empty alt is correct for decorative images
• Scanning a page with an image that has no alt attribute reports ‘Image missing alt text’
• Editor displays a11y check result inline as the merchant types (contrast check for typed text color)
• Dismissed issues do not re-appear in subsequent scans if nothing changed
• Export CSV includes page URL, rule code, issue description, and selector for each issue

Risks

Scanner goes stale if it is not re-run; a old pass does not mean the current site is accessible. Scanning can be slow on a large site; need timeout/pagination. Heuristics miss real issues (false negatives) and may flag false positives; the merchant must still test with real users. Editor a11y checks run on unvalidated user input; must sandbox/rate-limit.

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.