CI/CD for Accessibility: Run Checks Before You Ship

Why shift-left works (and pays)

• Earlier fixes cost less and reduce firefighting.

• Prevent regressions across templates and components.

• Supports Core Web Vitals and overall UX quality—good for people and search.

What to test in CI (the 80/20)

• Templates & key routes: Home, navigation, category/listing, product/service, blog post, contact/checkout.

• Rules to include: page titles, landmarks, form labels, name/role/value, colour contrast flags, image alt presence, focusable controls.

• Artifacts: machine-readable reports (JSON/HTML) uploaded per run.

Automation finds repeatable issues. You still need fast keyboard + screen reader checks before release.

Thresholds & gating (practical defaults)

• Critical violations: 0 allowed (fail the job).

• Serious/moderate: allow a small budget at first (e.g., ≤ 5) and auto-create tickets; ratchet down to 0 over time.

• New vs baseline: fail builds only when a branch introduces new issues beyond the baseline.

GitHub Actions example (axe/Pa11y/Lighthouse subset)

name: a11y-ci
on: [pull_request]

npm run a11y:ci (concept):

"scripts": {
  "a11y:ci": "node scripts/run-a11y.js --urls routes.txt --output reports/a11y"
}

GitLab CI example

Bitbucket Pipelines example

pipelines:
  pull-requests:
    '**':
      - step:
          image: node:20
          caches: [node]
          script:
            - npm ci
            - npm run build && npm run start & npx wait-on http://localhost:3000
            - npm run a11y:ci
            - node scripts/enforce-thresholds.js --critical=0 --serious<=5
          artifacts:
            - reports/a11y/**

Keeping noise low (so teams trust the job)

• Use a small, stable ruleset first; expand after false positives are under control.

• Target static routes or pre-rendered HTML for consistency.

• Normalise dynamic content (e.g., stub ads/AB tests, freeze dates).

• Track flaky pages and fix root causes (timing, auth, popups).

Short manual gate before release (30–45 minutes)

Run on changed areas + top user journeys:

• Keyboard-only pass: menus, dialogs, tabs/accordions, forms (no focus traps; focus visible).

• Screen reader skim: title, headings, landmarks, links list; field labels and error announcements.

• Contrast & states: text/buttons/inputs; hover/focus/active distinct and visible.

• Mobile spot check: targets, reflow at 320 px, zoom allowed; motion respects preferences.

Reporting & trends

• Store reports per run; diff against baseline.

• Dashboard: violations by rule, by template, by severity.

• Celebrate zero-violation streaks; ratchet thresholds quarterly.

• Auto-create Jira issues with page, rule, and reproduction steps.

Roles & ownership

• Engineering: CI setup, thresholds, component fixes, flake reduction.

• Design/Content: tokens for contrast, focus styles, headings, link text, alt text quality.

• QA/PM: schedule manual gates, accept criteria, risk sign-off.

• Leadership: time for remediation and expert reviews when needed.

Common pitfalls (and quick fixes)

• Green pipeline, broken flow: add a 15-minute keyboard/screen reader gate.

• Per-page scanning too slow: scan templates or a representative route set.

• False positives fatigue: tune rules; annotate known exceptions; fix the component once.

• Blocking the team early: start with warn mode on moderate issues, then enforce after 2–3 sprints.

Copy-paste checklists

CI scope (Markdown)

Manual release gate (Markdown)

Example routes.txt (scan targets)

How Adjustable helps (after guardrails are in place)

• Text to Speech and Language Translation broaden reach and comprehension.

• Accessibility Profiles give one-click presets (e.g., “Readable”, “Low Vision”).

• Text Options, Reading Ruler, Cursor Adjustment, Screen Mask support long reading and complex forms.

• Page Options let users scale pages, hide images/animations, and highlight links—great while you iterate.

• Light/Dark/Colour modes and configurable toolbar/widget placement fit your brand.

Try Adjustable

FAQs

Should accessibility checks fail the build?
Yes—critical issues should fail. Start with warnings for serious/moderate, then tighten thresholds.

What about authenticated pages?
Use seeded test accounts and pre-auth sessions; or scan the HTML after SSR with fixtures.

Do I need both CI and manual checks?
Absolutely. CI catches repetitive issues; manual gates protect real user flows.

How do we prevent flakiness?
Stabilise timing, mock external widgets, and scan rendered HTML where possible. Track flaky routes and fix root causes.

Next steps

• Add a minimal a11y CI job with tight critical thresholds.

• Pilot a 30–45 minute manual gate on your next release.

• Assign component owners and ratchet thresholds quarterly.

• Install Adjustable to boost real-world readability and task completion while you iterate.