CI/CD for Accessibility: Run Checks Before You Ship

Why Shift-Left Works (and Pays Off)

• Fixes Early Cost Less and help reduce firefighting.

• Prevent regressions in templates and components.

• Enhances Core Web Vitals and improves overall UX quality—beneficial for users and search engines.

What to Test in CI (the 80/20 Rule)

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

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

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

Automation identifies repeatable issues. Quick keyboard + screen reader checks are still essential before release.

Thresholds & Gating (Practical Defaults)

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

• Serious/Moderate: initially allow a small budget (e.g., ≤ 5), auto-create tickets; gradually reduce 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)

• Begin with a small, stable ruleset; expand after managing false positives.

• Focus on static routes or pre-rendered HTML for consistency.

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

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

Short Manual Gate Before Release (30–45 Minutes)

Conduct in changed areas and top user journeys:

• Keyboard-Only Pass: menus, dialogs, tabs/accordions, forms (ensure no focus traps; visible focus).

• Screen Reader Skim: title, headings, landmarks, links list; check field labels and error announcements.

• Contrast & States: text/buttons/inputs; ensure hover/focus/active states are distinct and noticeable.

• Mobile Spot Check: ensure targets, reflow at 320 px, and zoom are allowed; ensure motion respects preferences.

Reporting & Trends

• Save reports per run; compare against baseline.

• Create a dashboard: violations by rule, by template, by severity.

• Celebrate zero-violation streaks; adjust thresholds quarterly.

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

Roles & Ownership

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

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

• QA/PM: schedule manual gates, define acceptance criteria, perform risk sign-off.

• Leadership: allocate time for remediation and expert reviews when necessary.

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: adjust rules; annotate known exceptions; fix components for good.

• 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 provide one-click presets (e.g., “Readable”, “Low Vision”).

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

• Page Options allow users to scale pages, hide images/animations, and highlight links—beneficial during iterations.

• Light/Dark/Color Modes and customizable toolbar/widget placement suit your brand.

Try Adjustable

FAQs

Should Accessibility Checks Fail the Build?
Yes—critical issues should indeed fail. Start with warnings for serious/moderate issues, then progressively tighten thresholds.

What About Authenticated Pages?
Utilize seeded test accounts and pre-auth sessions; alternatively, scan the HTML after SSR using fixtures.

Is Both CI and Manual Checking Necessary?
Definitely. CI catches repetitive issues; manual gates ensure real user flow protection.

How Can We Prevent Flakiness?
Stabilize timing, mock external widgets, and inspect rendered HTML where feasible. Monitor flaky routes and address root causes.

Next Steps

• Implement a basic a11y CI job with stringent critical thresholds.

• Test a 30–45 minute manual gate on your upcoming release.

• Designate component owners and adjust thresholds quarterly.

• Incorporate Adjustable to enhance real-world readability and task completion while iterating.