Automating WCAG 2.2 AA: How Ally Enforces Its Accessibility Styleguide with AI Code Reviews
Static linters like axe-linter and eslint-plugin-jsx-a11y catch issues such as missing alt attributes or invalid ARIA roles. However, static linters can miss accessibility issues that depend on interaction or runtime behavior, such as keyboard focus management, focus restoration, or CSS reordering that creates a confusing focus sequence.
To bridge this gap, we evolved our workflow at Ally from simple automated checks into a hybrid AI pipeline fed directly by our internal accessibility styleguide.
Moving Beyond Static Linters: Our Shift-Left Evolution
Our automation journey started with Gemini’s free GitHub integration, which we configured with our internal guidelines to automate basic pull request feedback. When Google sunset the consumer version of Gemini Code Assist on GitHub, we transitioned to an in-house custom agent to maintain full control over our code quality pipeline.
Crucially, our guidelines extend far beyond accessibility. They define engineering standards across Frontend, Backend, WordPress, and TypeScript and continue to evolve as new technologies enter our stack.
To catch code quality issues, avoidable bugs, and architecture drift long before code reaches a pull request or the active development branch, we embraced a shift-left code review strategy:
- Inline IDE Validation (Copilot AI Skill): We are building a custom AI skill directly within GitHub Copilot. This enables developers to validate inline code changes against our WCAG 2.2 AA rules and technology-specific coding standards in the editor before staging files. It also gives AI models used during development clearer standards to follow.
- Pre-Push Execution (Gemini API): We retained Gemini by integrating its API as an optional pre-push step. Developers can run quick, manual sanity checks against our multi-domain styleguide locally on their branch, with reviewer feedback output directly to the command-line interface.
- PR Automated Audits (In-House Agent + Copilot): In GitHub Actions workflows, GitHub Copilot reviews run in parallel with our dedicated in-house agent. While Copilot handles general code health, our custom agent reviews implementation patterns associated with dynamic accessibility behavior, such as focus restoration refs, keydown handlers for Escape and Tab, and layout order. It also reviews implementation logic against standards defined in our custom styleguide.md, which can be overridden by repository-specific rules when needed. Comments from both agents are posted directly inline on the associated PR.
- Distributed Local AI Trial (Ollama + Qwen 2.5): To make deeper PR reviews fast, secure, and cost-effective, we are trialing a distributed runner setup. The custom agent executes Qwen 2.5 locally via Ollama, triggered through GitHub Actions on developers’ laptops during PR runs.
How We Format Styleguide Rules for AI Agents
Generic prompts yield generic reviews, often with plenty of errors. We formatted our styleguide into structured guidelines that explicitly contrast what static linters can catch with what the AI agent should inspect in dynamic JavaScript.
Here is a small example of how our styleguide is structured:
## Section 9.2: Operable — Keyboard Navigation & Focus Controls
### 2.1.2 Dynamic Focus Management & Trapping
- **Semantics**: Prefer native `<dialog>` elements over `<div role="dialog">` where appropriate.
- **Focus Restoration**: Save `document.activeElement` prior to opening an overlay and return focus appropriately when the overlay closes.
- **Keyboard Handling**: Support expected keyboard interactions, such as `Escape` to close controls and appropriate `Tab` behavior within modal interfaces.
- **Visual vs. DOM Order**: Flag CSS using `flex-direction: column-reverse` or `order` when it may create a focus sequence that conflicts with the meaning or operability of the interface.
- **Agent Enforcement**: As an Ally implementation rule, flag dynamic overlay PR diffs that appear to lack appropriate focus management or restoration.
Human reviewers remain an essential part of that process, focusing on architecture, implementation decisions, and accessibility issues that require context and judgment.
Building Accessibility Into the Development Workflow
Automating multi-domain standards reflects how we pair a strong engineering mindset with an inclusive culture at Ally.
Each layer has a different job. Copilot helps catch issues earlier in the IDE. Our local Qwen 2.5 agent reviews pull requests against our accessibility and engineering standards. Automated and manual accessibility testing then validates the rendered experience and catches issues that code review alone cannot.
Human reviewers remain an essential part of that process, focusing on architecture, implementation decisions, and accessibility issues that require context and judgment.
The goal isn't to automate WCAG compliance. It's to build accessibility into the development process early enough that fewer issues make it downstream.
AI gives us another layer of review. Our styleguide gives that review a standard to follow. And human testing gives us the validation that code analysis alone can't provide.
That combination helps us ship better code and build accessibility into the product from the start.



