IBM Equal Access accessibility-checker

Companion reference for axe-a11y. Consult when the project ships to US federal / public-sector customers under Section 508 procurement, when an enterprise compliance program mandates IBM-branded reports, or to cross-check axe results from Selenium / Puppeteer / Playwright suites. For most projects without those constraints, direct axe (SKILL.md) is the standard recommendation - larger ecosystem, simpler integration.

IBM Equal Access provides an accessibility-checker as part of the broader Equal Access Toolkit, supporting a11y across "planning, design, development, and verification phases" (equal-access (opens in new window)). The differentiator vs. axe / pa11y / Lighthouse is US Section 508 specificity and IBM-branded enterprise rule sets.

Install

npm install --save-dev accessibility-checker

(Per equal-access (opens in new window).) Cypress uses the cypress-accessibility-checker wrapper; Karma / Selenium / Puppeteer / Playwright are bundled in accessibility-checker.

Authoring scans

const { getCompliance } = require('accessibility-checker');

const results = await getCompliance(page, 'My scan label');
if (results.report.results.filter(r => r.level === 'violation').length > 0) {
  process.exit(1);
}

(Adapted from equal-access (opens in new window); page is a Puppeteer / Playwright page.)

Configuration (.achecker.yml)

ruleArchive: latest
policies:
  - WCAG_2_2
failLevels:
  - violation
  - potentialviolation
reportLevels:
  - violation
  - potentialviolation
  - recommendation
outputFormat:
  - json
  - html
outputFolder: a11y-reports

Rule sets / policies

Per equal-access (opens in new window):

US Section 508 alignment is via the IBM-branded policies (the toolkit's compliance documentation maps Section 508 to specific rule combinations).

Results structure

getCompliance() returns a report with a summary.counts block and a results[] array; each result carries ruleId (e.g. WCAG20_Img_HasAlt), level, message, snippet, and a DOM path. Severity levels:

For CI gating, fail on violation (and optionally potentialviolation); aggregate the rest at the gate.

Playwright integration

const { test, expect } = require('@playwright/test');
const { getCompliance } = require('accessibility-checker');

test('checkout passes IBM Equal Access', async ({ page }) => {
  await page.goto('/checkout');
  const results = await getCompliance(page, 'checkout-page');
  const violations = results.report.results.filter(r => r.level === 'violation');
  expect(violations).toHaveLength(0);
});

For the ratchet pattern (block only on net-new violations), pipe the JSON output to a11y-violation-gate instead of asserting zero.

Anti-patterns

Limitations

• Smaller community than axe-core - fewer integrations and answers.
• Heavier setup than axe's drop-in.
• Section 508 specificity is the strength; for non-US-public-sector projects the extra coverage may not be load-bearing.

References

• IBM Equal Access - equal-access (opens in new window) (install, supported test frameworks, rule archives).
• IBM Equal Access Toolkit - https://www.ibm.com/able/toolkit/
• US Section 508 - https://www.section508.gov/

Lighthouse CI Accessibility category

Companion reference for axe-a11y. Consult when the project already runs Lighthouse CI for Web Vitals and wants a11y coverage in the same pipeline instead of a separate scanner. If the project doesn't already use Lighthouse CI, prefer direct axe integration (SKILL.md) - Lighthouse adds a layer.

Lighthouse CI ships five audit categories: Performance, Accessibility, Best Practices, SEO, and Progressive Web App. The Accessibility category runs a curated subset of axe-core rules (lhci (opens in new window)). It audits whole pages (scored 0 - 1, rule pass rate weighted by severity); for component-level coverage, use axe in unit / integration tests.

Install and configure

npm install --save-dev @lhci/cli

Add a11y assertions to the same .lighthouserc.js used for perf, so one config drives both categories:

// .lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000/', 'http://localhost:3000/checkout'],
      numberOfRuns: 3,
      startServerCommand: 'npm run start',
    },
    assert: {
      assertions: {
        // Accessibility - category score (0-1)
        'categories:accessibility':  ['error', { minScore: 0.95 }],

        // Per-audit overrides - error on critical-impact a11y rules
        'aria-required-attr':         ['error', { minScore: 1 }],
        'button-name':                ['error', { minScore: 1 }],
        'label':                      ['error', { minScore: 1 }],
        'meta-viewport':              ['error', { minScore: 1 }],

        // Lower-impact rules - warn but don't block
        'color-contrast':             ['warn',  { minScore: 1 }],
        'image-alt':                  ['warn',  { minScore: 1 }],
      },
    },
    upload: { target: 'temporary-public-storage' },
  },
};

Per lhci (opens in new window), assertion levels are 'error' (CI fails), 'warn' (surfaced but doesn't fail), and 'off'. Run all three phases (collect / assert / upload) with npx lhci autorun.

Per-URL thresholds with assertMatrix

assert.assertions applies one threshold set to every collected URL. When pages need different bars, use assertMatrix: an array pairing a matchingUrlPattern regex with its own assertions block (lhci (opens in new window)). assertMatrix and assertions are mutually exclusive at the assert level, and the first matching pattern wins - order specific patterns before the catch-all:

assert: {
  assertMatrix: [
    { matchingUrlPattern: '.*/checkout.*',
      assertions: { 'categories:accessibility': ['error', { minScore: 0.98 }] } },
    { matchingUrlPattern: '.*',
      assertions: { 'categories:accessibility': ['error', { minScore: 0.90 }] } },
  ],
},

Common accessibility audit IDs

Used in assertions:; per lhci (opens in new window) (full list in Lighthouse's accessibility audit documentation):

CI integration

# .github/workflows/lighthouse.yml
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run build
      - run: npx lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      - if: always()
        uses: actions/upload-artifact@v4
        with: { name: lighthouse-reports, path: .lighthouseci/ }

Anti-patterns and limits

• Asserting only the category score hides per-rule regressions - assert specific audit IDs in addition to the score.
• minScore: 1 on the category blocks every PR on a single moderate-severity failure; start at 0.95 and tighten.
• A score of 1.0 doesn't mean perfect a11y - Lighthouse runs a subset of axe rules and covers ~50-60% of WCAG; pair with manual testing (screen-reader-test-author) and direct axe scans.
• Page-level only - per-component coverage isn't supported.

References

• Lighthouse CI - lhci (opens in new window) (install, lhci autorun, config shape, assertion levels, assertMatrix).
• W3C WCAG 2.2 - https://www.w3.org/TR/WCAG22/

pa11y - CLI scanner (htmlcs + axe engines)

Companion reference for axe-a11y. Consult when the project needs scriptable a11y scans without a full test framework (CI cron job, docs publication, static-site CI), or when a Node-stack project wants a single-command scanner instead of framework-integrated axe tests.

pa11y is "your automated accessibility testing pal" - a Node.js CLI that runs a11y tests on a page via the command line or a programmatic API (pa11y (opens in new window)). It can use HTML CodeSniffer (htmlcs, default) or axe-core as the underlying engine. If the project already runs Playwright / Cypress with axe-core, prefer the direct axe integration in SKILL.md - pa11y adds a layer.

Install and run

npm install -g pa11y        # or --save-dev per-project
pa11y https://example.com

(Per pa11y (opens in new window).)

Key flags

pa11y's WCAG2AA standard is 2.0/2.1; WCAG 2.2 SCs (2.4.11, etc.) need --runner axe alongside htmlcs.

Multi-URL with pa11y-ci

pa11y-ci (https://github.com/pa11y/pa11y-ci) batches a URL set from a .pa11yci config and exits non-zero if any URL exceeds threshold - the canonical CI gate signal:

{
  "defaults": {
    "standard": "WCAG2AA",
    "runners": ["axe", "htmlcs"],
    "includeWarnings": true,
    "threshold": 0
  },
  "urls": [
    "https://staging.example.com/",
    "https://staging.example.com/dashboard",
    "https://staging.example.com/checkout"
  ]
}

Programmatic API and results structure

const pa11y = require('pa11y');

const results = await pa11y('https://example.com', {
  standard: 'WCAG2AA',
  runners: ['axe', 'htmlcs'],
  includeWarnings: true,
});

console.log(results.issues);

results.issues[] holds one object per finding with code, type (error / warning / notice), typeCode, selector, context, message, and runner. When both engines run, the same defect appears twice under different codes - WCAG-SC-coded from htmlcs (WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail), rule-coded from axe (color-contrast) - and a11y-violation-gate collapses the pair via its fingerprint field.

Worked example

pa11y --standard WCAG2AA \
      --runner htmlcs --runner axe \
      --include-warnings \
      --reporter json \
      --threshold 0 \
      https://staging.example.com/checkout > pa11y-results.json

The run exits non-zero (threshold 0 exceeded) and pa11y-results.json holds the issues[] array for the gate.

Anti-patterns

Limitations

• Selector reliability. htmlcs sometimes produces selectors that don't uniquely identify the failing element; axe is more precise.
• JS-rendered content. pa11y's default Chromium runner waits for the load event; SPAs may need --wait-for-selector before scanning.
• No native test-framework integration. For Playwright / Cypress, use the direct axe integration in SKILL.md.

References

• pa11y - https://github.com/pa11y/pa11y (install, CLI flags, runners, reporter formats).
• pa11y-ci - https://github.com/pa11y/pa11y-ci (multi-URL).
• HTML CodeSniffer (the htmlcs runner) - https://github.com/squizlabs/HTML_CodeSniffer

axe-core results structure and rule configuration

Results structure

axe.run() resolves to an object with four arrays (axe-core (opens in new window)):

Each violation has:

Triage with jq:

# Top violations by impact
jq -r '.violations[] | "\(.impact): \(.id) - \(.description)"' axe-results.json

# Just the failing selectors per rule
jq -r '.violations[] | "\(.id):", (.nodes[].target | tostring)' axe-results.json

Rule configuration

By tags

axe ships rules tagged with conformance levels:

new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])

Common tag sets:

Disable specific rules

new AxeBuilder({ page }).disableRules(['color-contrast'])

For per-page disabling (e.g. a known false positive on a specific component):

new AxeBuilder({ page })
  .exclude('.legacy-component')   // selector exclusion
  .analyze();

For per-rule severity in CI gating (e.g. block on critical / serious only): handle in a11y-violation-gate using the impact field.

WAVE - WebAIM's visual-overlay scanner

Companion reference for axe-a11y. Consult when a regulatory audit requires WebAIM-branded reports (common in US public-sector / education compliance), when designers or non-technical reviewers need the visual overlay, when auditing a third-party site without code access, or to cross-check axe / pa11y findings. For purely automated CI gating, direct axe (SKILL.md) and pa11y are simpler and free.

WAVE (Web Accessibility Evaluation Tool) is WebAIM's flagship scanner - distinguished by a visual overlay that places icons directly on the rendered page. It runs via browser extension (manual, visual), the WAVE API (programmatic), or the commercial Stand-Alone API (self-hosted).

WAVE categorizes findings into: errors (definite WCAG failures), alerts (likely issues needing review), features (positive patterns), structural elements (landmarks, headings), HTML5 / ARIA semantics, and contrast errors.

Source-fetch note (2026-05-04): WAVE's documentation lives across wave.webaim.org and webaim.org/articles; the API specifics may evolve - verify the current WAVE API v3+ documentation at wave.webaim.org/api before authoring CI integrations against specific endpoints.

Access

Manual usage (extension)

1. Install the WAVE extension; navigate to the page under test.
2. Click the WAVE icon - the page reloads with the overlay: red error icons (definite failures), yellow alert, green feature, purple structural, blue HTML5/ARIA.
3. The "Details" sidebar tab gives per-icon explanations.

Programmatic usage (API)

curl 'https://wave.webaim.org/api/request?key=YOUR_KEY&url=https://example.com&reporttype=4'

Reporttype 4 returns the full JSON: a statistics block (errorcount, alertcount, featurecount, ...) and a categories object (error / alert / feature / structure / html5 / contrast). Per category, items is keyed by WAVE issue code (e.g. alt_missing, label_missing, contrast); each entry has description, count, selectors[], and per-instance xpath / selector / html.

jq triage:

# All error-level codes + counts
jq -r '.categories.error.items | to_entries[] | "\(.key): \(.value.count)"' wave-results.json

# Failing selectors per issue
jq -r '.categories.error.items | to_entries[] | .value.selectors[] | tostring' wave-results.json

CI integration

Capture WAVE API JSON per URL and feed it to the gate (a11y-violation-gate owns the gate logic):

- name: Run WAVE scan via API
  env:
    WAVE_API_KEY: ${{ secrets.WAVE_API_KEY }}
  run: |
    for url in https://staging.example.com/ https://staging.example.com/dashboard; do
      slug=$(echo "$url" | tr '/:' '__')
      curl -sS "https://wave.webaim.org/api/request?key=$WAVE_API_KEY&url=$url&reporttype=4" \
        > "wave-$slug.json"
    done

Anti-patterns

Limitations

• Authenticated pages. The WAVE API scans public URLs only; auth-required pages need the Stand-Alone API or the extension manually.
• SPAs. URL-based scanning may not match the user's actual journey.
• Quotas / costs. The free API tier has limits; high-traffic CI usage requires a paid tier.
• Different rule coverage than axe / pa11y - complementary, not a replacement.

References

• WAVE - https://wave.webaim.org/
• WAVE API documentation - https://wave.webaim.org/api/
• WebAIM - https://webaim.org/
• W3C WCAG 2.2 - https://www.w3.org/TR/WCAG22/