How We Automated Accessibility VPATs In CI How We Automated Accessibility VPATs In CI

Accessibility audits go out of date fast. A single code merge changes everything.

We fixed this. We turned our accessibility reports into a continuous build artifact.

Our pipeline uses three layers to find errors:

  • Static checks: We use axe-core for baseline tests in Storybook.
  • Interactive tests: We use custom Vitest helpers to test keyboard rules.
  • Manual audits: We store screen reader results as JSON files.

Our CI pipeline merges these results.

If a test fails, the PR fails. If all tests pass, the system builds a new PDF. This PDF ships with your release.

We tried one thing that failed.

We tried using an LLM to replace manual audits. We stopped using it immediately. AI results change too much. You need stable results for a CI gate.

Read the full technical breakdown here:

Source: https://dev.to/yassine_lakhdar_d0226709a/how-we-automated-our-accessibility-vpats-in-ci-46jk

ARTICLE: A development team has automated the creation of accessibility VPATs (Voluntary Product Accessibility Templates) directly in its continuous-integration (CI) pipeline, turning what used to be a periodic manual report into a build artifact that ships with every release. The new workflow fails pull requests that introduce accessibility regressions and produces a PDF compliance document automatically when the build succeeds, ensuring every code change stays within accessibility standards.

Why automation matters

Accessibility audits become obsolete the moment new code lands. A single merge can introduce missing alt text, improper focus order, or screen-reader issues that invalidate a previously issued VPAT. Maintaining compliance manually means re-running audits after each change, a costly and error-prone process that often lags behind development speed. By embedding checks in CI, teams get immediate feedback, keep compliance current, and avoid the legal and reputational risks of shipping inaccessible software.

The three-layer testing approach

  1. Static checks – The pipeline runs axe-core, an open-source library that scans components rendered in Storybook for known violations such as missing landmarks or insufficient color contrast. These tests catch problems before any interaction occurs.

  2. Interactive checks – Custom Vitest helpers exercise keyboard navigation rules, verifying that focus moves logically and that interactive elements respond to standard keyboard events. This layer goes beyond static analysis to ensure real-world usability.

  3. Manual audit artifacts – Results from screen-reader testing are saved as JSON files. Developers record observations during exploratory testing and commit the JSON alongside the code. The CI job merges these artifacts with the automated results, producing a single source of truth for the VPAT.

When any test in the first two layers fails, the pull request is blocked, preventing the change from reaching production. If all tests pass, the pipeline assembles the combined data into a PDF that is attached to the release, delivering an up-to-date VPAT without extra effort.

What didn’t work

The team experimented with using a large language model (LLM) to generate the manual audit portion automatically. The AI-produced results fluctuated too much, making the CI gate unreliable. Consistency is essential for a binary pass/fail check, so the experiment was abandoned in favor of the JSON-based manual artifacts.

What to watch next

For now, the three-layer CI model offers a pragmatic path to keep VPATs current, reduce manual overhead, and keep accessibility front-and-center in every code change.