WCAG 2.1 AA — Developer Checklist

1. WCAG 2.1 AA — Developer Checklist#

This notebook is a developer-oriented guide to implement and audit WCAG 2.1 AA in modern web apps (HTML/CSS/JS; SPA frameworks; data-heavy UIs).

1.1. 1) Overview — What is WCAG 2.1 AA?#

WCAG 2.1 (Web Content Accessibility Guidelines) provides criteria to make the web accessible to people with disabilities. It is structured by the POUR principles:

  • Perceivable: information must be presented in ways users can perceive (text alternatives, captions, sufficient contrast).

  • Operable: all UI must be keyboard-operable; provide visible focus; avoid traps.

  • Understandable: clear labels/instructions; consistent behavior; predictable navigation.

  • Robust: compatible with assistive technologies; use semantic HTML and valid markup.

Levels: A (basic), AA (required under ADA Title II web rule), AAA (enhanced).

1.2. 2) Detailed Developer Checklist#

1.2.1. A. General Structure / Semantic HTML#

  • Use semantic landmarks: <header>, <nav>, <main>, <aside>, <footer>.

  • One <h1> per page/view; subsequent headings (<h2>–<h6>) in logical order.

  • Prefer native HTML semantics before ARIA.

  • Ensure a unique, descriptive <title> for each page/route.

1.2.2. B. Text Alternatives & Media#

  • Images: Meaningful alt text; decorative images use alt="". Avoid images of text (logos OK).

  • Charts/Maps: Provide data tables or textual summaries; for maps, include an accessible list of locations.

  • Audio/Video: Captions for video; transcripts for audio-only; audio description when visuals convey meaning.

  • Icons/SVG: Provide accessible names (e.g., aria-label) if no visible text.

1.2.3. C. Color & Contrast#

  • Minimum contrast: 4.5:1 (normal text), 3:1 (large text ≥ 18pt or 14pt bold).

  • Don’t rely on color alone for meaning—add text/icons.

  • Keep focus indicators highly visible (:focus, :focus-visible).

  • Do not disable OS/browser high-contrast modes.

1.2.4. D. Keyboard Accessibility#

  • All functionality available via keyboard (no mouse required).

  • Logical tab order matches visual order; no keyboard traps.

  • Provide a Skip to main content link.

  • Modals: trap focus while open; restore focus to trigger when closed.

  • Menus/Dropdowns: support arrow keys; Esc closes.

  • Custom controls replicate native behavior using roles/tabindex/aria-* only as needed.

1.2.5. E. Forms & Inputs#

  • Every input has a visible <label> programmatically associated (via for/id or wrapping label).

  • Mark required fields in text (not color alone).

  • Clear, specific error messages; associate with fields using aria-describedby.

  • Group related controls with <fieldset>/<legend> where appropriate.

  • On submit errors, move focus to the first invalid field.

1.2.6. F. Dynamic Content / JavaScript / SPAs#

  • Announce dynamic updates with ARIA live regions (aria-live="polite").

  • Maintain sensible focus when injecting or replacing content.

  • Avoid auto-refresh/auto-redirect; provide user control.

  • Provide time extension where timeouts exist.

  • Use ARIA sparingly and correctly; prefer semantic HTML.

  • Custom widgets (tabs, sliders, modals): add proper roles & keyboard support; update document.title and move focus on route changes.

1.2.7. G. Navigation & Orientation#

  • Consistent navigation and placement across pages.

  • Use logical heading structure; no skipping levels.

  • Ensure responsive layouts preserve reading order.

  • Declare language on <html lang="...">.

1.2.8. H. Timing / Animations / Motion#

  • No flashing content > 3 times per second.

  • Provide pause/stop controls for carousels/auto-playing media.

  • Respect prefers-reduced-motion to limit motion effects.

  • Warn before session timeout; allow extension.

1.2.9. I. Documents & Downloads#

  • Make PDFs accessible (tagged, logical reading order) or provide equivalent HTML/text.

  • Use descriptive link text (e.g., “Download flood report (PDF)”).

1.2.10. J. Error Prevention & Feedback#

  • Confirm destructive actions or provide undo.

  • Provide top-of-form error summary for long forms.

  • Do not rely on color alone to indicate errors.

1.2.11. K. Mobile & Touch#

  • Proper viewport meta; content reflows without horizontal scrolling.

  • Touch targets ≥ 44×44 CSS px.

  • Don’t require gesture-only interactions; provide clickable alternatives.

1.2.12. L. Testing & Verification#

Automated checks: axe (ext/CLI), Lighthouse Accessibility, WAVE, Accessibility Insights. Manual checks: keyboard-only navigation; NVDA/VoiceOver screen reader passes; color-contrast tests; 200% zoom test; responsive/orientation tests.

1.3. 3) Implementation Notes for JS/SPA Apps#

  • On route change, update document.title and move focus to the main heading or content container.

  • Provide an offscreen ARIA live region for announcing updates.

  • Ensure modals/menus/popovers manage focus correctly.

  • For virtualized lists/tables, expose semantics and counts (e.g., role="table", aria-rowcount).

  • For interactive maps/charts, include accessible summaries, keyboard interactions, and data tables as alternatives.

1.4. 4) Workflow Integration (CI/CD)#

  • Design: include focus order and color-contrast checks in design reviews.

  • Development: semantic-first; ARIA minimal; keyboard paths implemented.

  • Testing: run automated checks per PR; monthly manual AT testing.

  • Deployment: publish accessibility statement and contact for feedback.

  • Maintenance: schedule periodic audits; fix regressions promptly.

1.5. 5) Quick Reference — Top 15 to Remember#

  1. Every image has correct alt (or alt="" if decorative).

  2. Headings are hierarchical and meaningful.

  3. Every form input has a proper label.

  4. All features are keyboard accessible.

  5. Focus is always visible.

  6. Text contrast ≥ 4.5:1 (3:1 for large text).

  7. Don’t use color alone to convey meaning.

  8. Captions and transcripts for media.

  9. Descriptive, programmatically associated error messages.

  10. Skip-to-content link.

  11. Unique page title per view/route.

  12. Responsive reflow preserves reading order.

  13. No auto-refresh/redirect without control.

  14. ARIA only when necessary and correct.

  15. Test with real assistive tech regularly.

1.5.1. Bonus: Simple ARIA Live Example#

<div id="sr-updates" aria-live="polite" class="sr-only"></div>

document.getElementById('sr-updates').textContent = 'Loaded Flood Risk Report section';

Prepared as a working checklist for engineers building data-heavy, map-centric web apps.

Contents