WCAG compliance report for website

WCAG Compliance Report Development

A WCAG (Web Content Accessibility Guidelines) compliance report is a formal document certifying a website's accessibility level. It's required for government sites, educational platforms, banks, and companies with ESG commitments. WCAG 2.1 AA is the minimum international standard.

Conformance Levels

• WCAG 2.1 A — basic requirements, 30 criteria
• WCAG 2.1 AA — standard level, 20 additional criteria (50 total)
• WCAG 2.1 AAA — maximum level, 28 additional criteria (rarely required fully)

Most legal requirements in the EU, US, and Australia are tied to WCAG 2.1 AA.

Report Structure

The report includes: scope of review, methodology, summary of POUR principles, detailed findings, and remediation plan.

POUR Principles:

• Perceivable — perceivable (alt text, captions, contrast)
• Operable — operable (keyboard navigation, sufficient time)
• Understandable — understandable (language, predictability, error assistance)
• Robust — robust (assistive technology compatibility)

Audit and Documentation

// scripts/wcag-report-generator.js
const AxeBuilder = require('@axe-core/playwright').default;
const { chromium } = require('@playwright/test');
const fs = require('fs');

const PAGES = [
  { url: 'https://example.com',          name: 'Home Page' },
  { url: 'https://example.com/catalog',  name: 'Catalog' },
  { url: 'https://example.com/login',    name: 'Login' },
  { url: 'https://example.com/checkout', name: 'Checkout' },
];

// Mapping axe rule ID → WCAG criteria
const RULE_TO_WCAG = {
  'color-contrast':   '1.4.3 (Level AA)',
  'image-alt':        '1.1.1 (Level A)',
  'label':            '1.3.1, 4.1.2 (Level A)',
  'button-name':      '4.1.2 (Level A)',
  'link-name':        '2.4.4 (Level A)',
  'heading-order':    '1.3.1 (Level A)',
  'duplicate-id':     '4.1.1 (Level A)',
  'html-has-lang':    '3.1.1 (Level A)',
  'keyboard':         '2.1.1 (Level A)',
  'focus-visible':    '2.4.7 (Level AA)',
};

async function generateReport() {
  const browser = await chromium.launch();
  const allViolations = [];
  const pageSummaries = [];

  for (const pageConfig of PAGES) {
    const page = await browser.newPage();
    await page.goto(pageConfig.url, { waitUntil: 'networkidle' });

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .analyze();

    const violations = results.violations.map(v => ({
      rule:       v.id,
      wcag:       RULE_TO_WCAG[v.id] || 'See axe docs',
      impact:     v.impact,
      count:      v.nodes.length,
      description: v.description,
      help_url:   v.helpUrl,
      elements:   v.nodes.slice(0, 3).map(n => n.target[0]),
    }));

    pageSummaries.push({
      name:        pageConfig.name,
      url:         pageConfig.url,
      total:       violations.length,
      critical:    violations.filter(v => v.impact === 'critical').length,
      serious:     violations.filter(v => v.impact === 'serious').length,
      violations,
    });

    allViolations.push(...violations);
    await page.close();
  }

  await browser.close();

  const report = {
    generated_at: new Date().toISOString(),
    standard:     'WCAG 2.1 Level AA',
    tool:         'axe-core 4.x via Playwright',
    pages_tested: PAGES.length,
    total_violations: allViolations.length,
    by_impact: {
      critical: allViolations.filter(v => v.impact === 'critical').length,
      serious:  allViolations.filter(v => v.impact === 'serious').length,
      moderate: allViolations.filter(v => v.impact === 'moderate').length,
      minor:    allViolations.filter(v => v.impact === 'minor').length,
    },
    pages: pageSummaries,
  };

  fs.writeFileSync('wcag-report.json', JSON.stringify(report, null, 2));
  console.log('Report saved: wcag-report.json');
  return report;
}

generateReport();

Manual Testing: Checklist

Automation covers ~40% of criteria. The rest are checked manually:

Keyboard Navigation:

• All interactive elements are reachable via Tab
• Tab order is logical and matches visual order
• Modal windows trap focus
• Escape closes modals and dropdown menus

Screen Readers:

• NVDA + Firefox: testing forms, tables, modals
• VoiceOver + Safari (macOS/iOS): mobile gestures
• Dynamic content announcements via live regions

Contrast and Zoom:

• Text passes 4.5:1 at normal size and 3:1 at large size
• 400% zoom without horizontal scrolling
• Windows high contrast mode

Remediation Plan Documentation

## Critical Violations (fix before release)

### 1.1.1 Images without alt text
- **Pages**: catalog, product pages
- **Count**: 23 elements
- **Fix**: Add alt="" for decorative, meaningful alt for informational
- **Timeline**: 3 days
- **Owner**: Frontend team

### 1.4.3 Insufficient Contrast
- **Elements**: Form placeholders (#9ca3af on white = 2.7:1)
- **Required**: ≥ 4.5:1
- **Fix**: Change color to #6b7280 (4.6:1)
- **Timeline**: 1 day

Timeline

Complete WCAG 2.1 AA audit (automated + manual testing) with report and remediation plan: 5–8 business days.