Tutorial: Integrating Accessibility Checks into Your CI/CD Pipeline

#Tutorial: Integrating Accessibility Checks into Your CI/CD Pipeline

Manually checking color contrast is crucial during design and development, but automating these checks in your Continuous Integration/Continuous Deployment (CI/CD) pipeline provides a safety net, preventing inaccessible color combinations from reaching production.

This tutorial explores two ways to integrate automated contrast checks using @weable/a11y-color-utils into a typical CI/CD workflow, focusing on GitHub Actions as an example.

##Prerequisites

• A project using Node.js and npm/yarn.
• Basic understanding of CI/CD concepts and GitHub Actions.
• Familiarity with a testing framework like Jest or Vitest (for Option 1).
• The API server from the previous tutorial running (accessible to the CI runner) or deployed (for Option 2).

##Why Automate Accessibility Checks?

• Consistency: Ensures standards are checked on every commit/PR.
• Prevention: Catches regressions or newly introduced issues early.
• Efficiency: Frees up developers from repetitive manual checks.
• Compliance: Helps maintain adherence to WCAG standards required by law.

##Option 1: Direct Library Integration in Tests (Jest/Vitest)

This approach involves writing unit or integration tests that use @weable/a11y-color-utils directly to verify critical color combinations within your application, often defined in theme files or design system constants.

1. Install Dependencies:

npm install --save-dev jest @weable/a11y-color-utils
#or
npm install --save-dev vitest @weable/a11y-color-utils

2. Create Test File (e.g., tests/accessibility.test.js):

// tests/accessibility.test.js
import {
getColorContrast,
getColorContrastAPCA,
hexToRgb,
} from '@weable/a11y-color-utils';

// --- Configuration ---
// Ideally, import these from your theme/design system constants
const themeColors = {
primaryText: '#212121',
primaryBackground: '#FFFFFF',
accent: '#3498DB',
accentText: '#FFFFFF',
error: '#C0392B',
errorText: '#FFFFFF',
subtleText: '#777777',
// ... add other critical colors
};

const WCAG_AA_NORMAL_THRESHOLD = 4.5;
// Example APCA Threshold (Body Text: 16px/400 weight)
const APCA_BODY_THRESHOLD = 75;

// --- Helper Function ---
function checkContrastPair(label, colorHex1, colorHex2) {
const color1 = hexToRgb(colorHex1);
const color2 = hexToRgb(colorHex2);

if (!color1 || !color2) {
throw new Error(`Invalid HEX color in pair: ${label}`);
}

const wcagRatio = getColorContrast(color1, color2);
const apcaLc = Math.abs(getColorContrastAPCA(color1, color2)); // Use absolute value

// WCAG Check (Minimum AA)
expect(wcagRatio).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_THRESHOLD);

// Optional: APCA Check (Example: Body text readability)
// Note: Adjust threshold based on expected usage (font size/weight)
// expect(apcaLc).toBeGreaterThanOrEqual(APCA_BODY_THRESHOLD);

console.log(`Checked: ${label} - WCAG: ${wcagRatio.toFixed(2)}, APCA Lc: ${apcaLc.toFixed(1)}`);
}

// --- Test Suite ---
describe('Color Contrast Accessibility Checks', () => {
test('Primary Text on Primary Background meets WCAG AA', () => {
checkContrastPair(
'Primary Text/Background',
themeColors.primaryText,
themeColors.primaryBackground
);
});

test('Accent Text on Accent Background meets WCAG AA', () => {
checkContrastPair(
'Accent Text/Background',
themeColors.accentText,
themeColors.accent
);
});

test('Error Text on Error Background meets WCAG AA', () => {
checkContrastPair(
'Error Text/Background',
themeColors.errorText,
themeColors.error
);
});

test('Subtle Text on Primary Background meets WCAG AA', () => {
// This might intentionally fail if 'subtle' doesn't meet AA
// Adjust threshold or colors based on design requirements
checkContrastPair(
'Subtle Text/Background',
themeColors.subtleText,
themeColors.primaryBackground
);
});

// ... Add more tests for critical combinations
});

3. Configure package.json:

{
"scripts": {
"test": "jest",
// or
// "test": "vitest run"
"test:ci": "npm run test -- --ci --silent" // Example for CI environment
}
}

4. GitHub Actions Workflow (.github/workflows/ci.yml):

name: Node.js CI

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build:
runs-on: ubuntu-latest

strategy:
matrix:
node-version: [18.x, 20.x]

steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install Dependencies
run: npm ci
- name: Run Accessibility Tests
run: npm run test:ci # Run tests, including contrast checks
#The job will fail if any expect() fails

##Option 2: Calling the Accessibility Check API

If you have deployed the API server from the previous tutorial, you can call it from your CI script.

1. Define Critical Pairs (e.g., in a script or file):

You might have a simple script or configuration file defining the color pairs you want to check.

2. GitHub Actions Workflow (.github/workflows/ci.yml):

name: Node.js CI & API Checks

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
accessibility_check:
runs-on: ubuntu-latest
#Ensure API_URL is configured (e.g., via GitHub Secrets)
env:
API_URL: ${{ secrets.A11Y_CHECK_API_URL }} # e.g., https://your-a11y-api.com/check-contrast

steps:
- uses: actions/checkout@v4

#Example: Check a single pair directly with curl
- name: Check Primary Text/Background via API
run: |
response=$(curl -s -w "%{http_code}" -X POST "$API_URL" \
-H "Content-Type: application/json" \
-d '{
"textColor": "#212121",
"backgroundColor": "#FFFFFF"
}')
http_code=$(tail -n1 <<< "$response") # Extract HTTP code
body=$(sed '$d' <<< "$response") # Extract body

if [ "$http_code" -ne 200 ]; then
echo "API Error: HTTP $http_code"
echo "$body"
exit 1
fi

#Check WCAG ratio (using jq to parse JSON)
wcag_ratio=$(echo "$body" | jq '.results.wcag.ratio')
wcag_pass=$(echo "$wcag_ratio >= 4.5" | bc -l)

echo "Checked Primary: WCAG Ratio $wcag_ratio"
if [ "$wcag_pass" -ne 1 ]; then
echo "Accessibility Check Failed: Primary Text/Background WCAG ratio ($wcag_ratio) is below 4.5"
exit 1
else
echo "Accessibility Check Passed: Primary Text/Background"
fi

#--- Add more checks for other pairs ---
#You would likely use a script here to loop through multiple pairs
#- name: Check Multiple Pairs via API Script
#run: node ./scripts/check-colors-via-api.js

(Note: The curl example is basic. A dedicated script (check-colors-via-api.js) using Node.js fetch and handling multiple pairs would be more robust.)

##Failing the Build

Both approaches naturally integrate with CI:

• Option 1: If any expect() assertion in your Jest/Vitest tests fails, the test runner exits with a non-zero code, failing the GitHub Actions step.
• Option 2: The script calling the API (like the curl example or a Node.js script) must explicitly check the results and exit 1 if a contrast check fails. This non-zero exit code fails the GitHub Actions step.

##Next Steps

• Expand Coverage: Add more critical color pairs to your tests or API checks.
• Refine Thresholds: Adjust WCAG (e.g., AAA) or APCA thresholds based on specific component requirements.
• Integrate APCA: Add APCA checks (using appropriate Lc thresholds based on font context) alongside WCAG.
• Linting: Explore linters (like stylelint-a11y) that can catch some issues statically.
• Reporting: Configure test runners or scripts to produce clearer reports on failures.

By integrating automated accessibility checks into your CI/CD pipeline using @weable/a11y-color-utils (either directly or via an API), you build a more robust process for creating and maintaining accessible web applications.