Accessibility Audit GitHub Action
Open-source GitHub Action that runs automated WCAG audits on preview deployments and posts AI-powered fix suggestions directly on pull requests.
The Problem
Accessibility violations are cheapest to fix when caught early, but most teams only audit after deployment, or not at all. Existing CI tools either lack context (running against static HTML rather than real rendered pages) or require expensive third-party services. I wanted a free, self-contained action that could audit Vercel/Netlify preview deployments and give developers actionable feedback before merge.
Approach
Built a composite GitHub Action that spins up a headless Chromium browser, crawls the target URL, and runs axe-core against every page. Violations are grouped by WCAG impact level (critical, serious, moderate, minor) and posted as a collapsible PR comment. An optional AI suggestions mode sends each violation to an LLM for specific, copy-pasteable fix recommendations tailored to the project's stack.
Architecture
Composite action using Playwright for browser automation and @axe-core/playwright for WCAG scanning. Triggered by the deployment_status event, provider-agnostic. Works with Vercel, Netlify, Render, or any platform that creates GitHub deployments. AI suggestions powered by OpenAI-compatible APIs with exponential backoff for rate limiting. Results posted via the GitHub API with hidden markers for comment upsert on subsequent pushes.
Results
Published on the GitHub Marketplace under MIT licence. Catches violations that unit tests and linters miss: real browser rendering, computed styles, focus order. The AI suggestions mode generates contextual fixes rather than generic WCAG references. Currently dogfooding on this portfolio, where it runs against every Vercel preview deployment.
Lessons Learned
The deployment_status event is the cleanest trigger for preview audits; it's provider-agnostic and gives you the URL for free. Collapsible markdown keeps PR comments manageable even with dozens of violations. LLM rate limits on free tiers require aggressive backoff (15s base delay). Shipping a GitHub Action as a composite with ncc bundling keeps the install fast and dependency-free for consumers.