Accessibility in Development | WCAG A11y Integration Guide
Integrate accessibility from project start. Track WCAG 2.1 compliance, add a11y to Definition of Done, and build products everyone can use. Reduce legal risk.
9 min read
Accessibility isn't optional - it's essential. GitScrum helps teams track accessibility requirements and ensure a11y is part of every feature.
Accessibility Fundamentals
Why A11y Matters
ACCESSIBILITY IMPACT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ WHO BENEFITS: │
│ │
│ PERMANENT DISABILITIES: │
│ • Blind users (screen readers) │
│ • Deaf users (captions, transcripts) │
│ • Motor disabilities (keyboard nav) │
│ • Cognitive disabilities (clear design) │
│ │
│ TEMPORARY CONDITIONS: │
│ • Broken arm (can't use mouse) │
│ • Eye infection (can't see well) │
│ • Loud environment (can't hear) │
│ │
│ SITUATIONAL: │
│ • Bright sunlight (low contrast) │
│ • One hand occupied (holding baby) │
│ • Slow connection (need lightweight) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ BUSINESS CASE: │
│ │
│ LEGAL: Many countries require accessibility │
│ • ADA (USA), EN 301 549 (EU), AODA (Canada) │
│ • Lawsuits increasing annually │
│ │
│ MARKET: 15% of world population has disability │
│ • Significant customer segment │
│ • Aging population increasing │
│ │
│ SEO: Accessible sites rank better │
│ • Semantic HTML helps search engines │
│ • Alt text improves image search │
│ │
│ QUALITY: Accessible = better for everyone │
│ • Clearer design │
│ • Better keyboard support │
│ • Improved performance │
└─────────────────────────────────────────────────────────────┘
WCAG Guidelines
WCAG 2.1 OVERVIEW:
┌─────────────────────────────────────────────────────────────┐
│ │
│ FOUR PRINCIPLES (POUR): │
│ │
│ PERCEIVABLE: │
│ Content must be presentable to users │
│ • Text alternatives for images │
│ • Captions for video │
│ • Sufficient color contrast │
│ • Resizable text │
│ │
│ OPERABLE: │
│ Interface must be navigable │
│ • Keyboard accessible │
│ • No seizure-inducing content │
│ • Enough time to read/interact │
│ • Clear navigation │
│ │
│ UNDERSTANDABLE: │
│ Content and interface must be clear │
│ • Readable text │
│ • Predictable navigation │
│ • Input assistance │
│ │
│ ROBUST: │
│ Content must work with assistive tech │
│ • Valid HTML │
│ • Proper ARIA usage │
│ • Compatible with screen readers │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ CONFORMANCE LEVELS: │
│ │
│ Level A: Minimum accessibility (bare minimum) │
│ Level AA: Standard target (most requirements) │
│ Level AAA: Highest level (specialized needs) │
│ │
│ RECOMMENDATION: Target WCAG 2.1 Level AA │
└─────────────────────────────────────────────────────────────┘
Integrating A11y
In Requirements
ACCESSIBILITY IN REQUIREMENTS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STORY WITH A11Y CRITERIA: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ PROJ-123: Add Image Upload Feature ││
│ │ ││
│ │ As a user ││
│ │ I can upload images to my projects ││
│ │ So that I can include visuals in documentation ││
│ │ ││
│ │ ACCEPTANCE CRITERIA: ││
│ │ ☐ Upload button with clear label ││
│ │ ☐ Drag-and-drop zone has keyboard alternative ││
│ │ ☐ Progress indicator announced to screen readers ││
│ │ ☐ Error messages are accessible ││
│ │ ☐ Uploaded images require alt text ││
│ │ ││
│ │ A11Y REQUIREMENTS: ││
│ │ ☐ Upload button keyboard accessible (Enter/Space) ││
│ │ ☐ Focus management after upload ││
│ │ ☐ ARIA live region for progress ││
│ │ ☐ Color contrast on all states ││
│ │ ☐ Alt text input is required field ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ A11Y IN DEFINITION OF DONE: │
│ │
│ ☐ Keyboard navigation works │
│ ☐ Screen reader tested │
│ ☐ Color contrast meets AA │
│ ☐ Focus states visible │
│ ☐ Form inputs have labels │
│ ☐ Automated a11y tests pass │
└─────────────────────────────────────────────────────────────┘
A11y Checklist
DEVELOPER A11Y CHECKLIST:
┌─────────────────────────────────────────────────────────────┐
│ │
│ KEYBOARD: │
│ ☐ All interactive elements focusable │
│ ☐ Focus order is logical │
│ ☐ Focus is visible (outline) │
│ ☐ No keyboard traps │
│ ☐ Skip links for main content │
│ ☐ Custom components have proper keyboard support │
│ │
│ SCREEN READERS: │
│ ☐ All images have alt text │
│ ☐ Decorative images have alt="" │
│ ☐ Headings are hierarchical (h1→h2→h3) │
│ ☐ Form inputs have labels │
│ ☐ Links have descriptive text (not "click here") │
│ ☐ Dynamic content announced (ARIA live) │
│ │
│ VISUAL: │
│ ☐ Color contrast 4.5:1 (text) / 3:1 (large text) │
│ ☐ Color not only indicator │
│ ☐ Text resizable to 200% │
│ ☐ Motion can be reduced (prefers-reduced-motion) │
│ │
│ STRUCTURE: │
│ ☐ Semantic HTML (nav, main, aside, etc.) │
│ ☐ Valid HTML │
│ ☐ Language attribute on html │
│ ☐ Page titles are descriptive │
│ │
│ FORMS: │
│ ☐ Labels associated with inputs │
│ ☐ Required fields indicated │
│ ☐ Error messages clear and associated │
│ ☐ Success/error states announced │
└─────────────────────────────────────────────────────────────┘
Testing A11y
Testing Approach
ACCESSIBILITY TESTING STRATEGY:
┌─────────────────────────────────────────────────────────────┐
│ │
│ AUTOMATED TESTING (Catch ~30% of issues): │
│ │
│ TOOLS: │
│ • axe-core (most popular) │
│ • Lighthouse accessibility audit │
│ • WAVE browser extension │
│ • ESLint jsx-a11y plugin │
│ │
│ INTEGRATION: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ // In test suite ││
│ │ import { axe } from 'jest-axe'; ││
│ │ ││
│ │ it('should have no a11y violations', async () => { ││
│ │ const { container } = render(<MyComponent />); ││
│ │ const results = await axe(container); ││
│ │ expect(results).toHaveNoViolations(); ││
│ │ }); ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ MANUAL TESTING (Catch remaining ~70%): │
│ │
│ KEYBOARD: │
│ • Tab through entire page │
│ • Use Enter/Space on all interactive elements │
│ • Check focus is always visible │
│ │
│ SCREEN READER: │
│ • Test with VoiceOver (Mac), NVDA (Windows) │
│ • Navigate headings, landmarks, links │
│ • Complete key user flows │
│ │
│ ZOOM: │
│ • Zoom to 200% │
│ • Check no content lost or overlapping │
│ │
│ COLOR: │
│ • Use colorblind simulator │
│ • Check meaning without color │
└─────────────────────────────────────────────────────────────┘
A11y Tasks
Tracking A11y Work
A11Y WORK IN GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ │
│ A11Y AUDIT TASK: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ A11Y-01: Q1 Accessibility Audit ││
│ │ ││
│ │ Scope: Full application audit ││
│ │ Standard: WCAG 2.1 AA ││
│ │ Due: End of Q1 ││
│ │ ││
│ │ Checklist: ││
│ │ ☐ Automated scan with axe ││
│ │ ☐ Manual keyboard testing ││
│ │ ☐ Screen reader testing (VoiceOver + NVDA) ││
│ │ ☐ Document all issues found ││
│ │ ☐ Prioritize and create fix tasks ││
│ │ ││
│ │ Output: A11Y issue backlog ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ A11Y FIX TASK: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ A11Y-15: Fix missing form labels on checkout ││
│ │ ││
│ │ WCAG: 1.3.1 (Info and Relationships) ││
│ │ Severity: Serious ││
│ │ Found in: /checkout page ││
│ │ ││
│ │ Issue: ││
│ │ Form inputs missing associated labels ││
│ │ Screen readers cannot identify fields ││
│ │ ││
│ │ Fix: ││
│ │ Add <label for="..."> to all inputs ││
│ │ Or use aria-labelledby ││
│ │ ││
│ │ Acceptance: ││
│ │ ☐ All inputs have visible labels ││
│ │ ☐ Labels correctly associated ││
│ │ ☐ Screen reader announces labels ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ LABELS: │
│ accessibility, wcag-aa, screen-reader, keyboard │
└─────────────────────────────────────────────────────────────┘
Common Patterns
Accessible Components
ACCESSIBLE COMPONENT PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ MODAL DIALOG: │
│ ✅ Traps focus inside modal │
│ ✅ Escape closes modal │
│ ✅ Returns focus to trigger on close │
│ ✅ role="dialog" aria-modal="true" │
│ ✅ Labeled with aria-labelledby │
│ │
│ CUSTOM DROPDOWN: │
│ ✅ role="listbox" and role="option" │
│ ✅ Arrow keys navigate options │
│ ✅ Enter/Space selects │
│ ✅ Escape closes │
│ ✅ aria-expanded on trigger │
│ │
│ TABS: │
│ ✅ role="tablist", role="tab", role="tabpanel" │
│ ✅ Arrow keys switch tabs │
│ ✅ aria-selected on active tab │
│ ✅ Tab panels labeled │
│ │
│ TOAST NOTIFICATIONS: │
│ ✅ role="alert" or aria-live="polite" │
│ ✅ Important: role="alert" (urgent) │
│ ✅ Less urgent: aria-live="polite" │
│ ✅ Can be dismissed by user │
│ │
│ TOGGLE/SWITCH: │
│ ✅ role="switch" (or checkbox) │
│ ✅ aria-checked state │
│ ✅ Clear label indicating what's toggled │
│ ✅ State change announced │
│ │
│ RESOURCES: │
│ • WAI-ARIA Authoring Practices (official patterns) │
│ • Inclusive Components (book) │
│ • a11y-style-guide │
└─────────────────────────────────────────────────────────────┘