Accessibility Best Practices

Use-When

• Agent builds new UI components (buttons, forms, modals, menus)
• Agent creates page layouts or content structures
• Agent adds images, media, or interactive elements
• Agent audits existing code for accessibility issues
• Agent fixes accessibility bugs or violations
• Agent writes tests that should verify accessibility

Core Rules

Prevention (Building Accessible)

• ALWAYS ensure minimum 4.5:1 contrast ratio for normal text (3:1 for large text)
• ALWAYS use semantic HTML elements over custom divs
• ALWAYS provide explicit, visible labels for all form inputs
• ALWAYS make all interactive elements keyboard accessible
• ALWAYS include visible focus indicators
• ALWAYS use proper heading hierarchy (no skipping levels)
• ALWAYS provide alt text for meaningful images
• ALWAYS use buttons for actions, links for navigation
• PREFER semantic HTML over ARIA (ARIA is a supplement, not a replacement)

Identification (Finding Issues)

• ALWAYS test with automated tools (axe, WAVE) to catch common issues
• ALWAYS test with keyboard-only navigation
• ALWAYS test with a screen reader (NVDA, VoiceOver)
• REMEMBER: Automated tools catch only 30-57% of accessibility issues

Remediation (Fixing Issues)

• NEVER rely on color alone to convey information
• NEVER use placeholder text as a replacement for labels
• NEVER have empty links or buttons
• NEVER use generic text like "click here" for links
• NEVER create keyboard traps (focus must be escapable)

Common Agent Mistakes

• Using divs with onClick instead of buttons
• Adding role="button" to divs (still not keyboard accessible)
• Using placeholder as the only label (disappears on focus)
• Forgetting to associate error messages with form fields
• Adding redundant ARIA to native HTML elements
• Using aria-label when visible text would work
• Creating heading hierarchies that skip levels (h1 → h3)
• Making focus indicators invisible (outline: none without replacement)
• Using color as the only indicator of state (need text/icon too)
• Not providing way to escape modals/keyboard traps

Examples

✅ Correct

// Semantic elements with proper contrast
<button className="bg-slate-900 text-white focus-visible:ring-2">
  Submit
</button>

// Explicit form labels
<label htmlFor="email">Email address</label>
<input id="email" type="email" aria-describedby="email-hint" />
<p id="email-hint">We'll never share your email.</p>

// Image with alt text
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2" />

// Proper heading hierarchy
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

// Skip link
<a href="#main" className="sr-only focus:not-sr-only">Skip to content</a>
<main id="main">

❌ Wrong

// Using div as button (not keyboard accessible)
<div onClick={submit}>Submit</div>

// Placeholder only (invisible on focus)
<input placeholder="Enter email" />

// Missing alt text
<img src="photo.jpg" />

// Heading skip (h1 → h3)
<h1>Title</h1>
<h3>Subtitle</h3>

// Generic link text
<a href="/details">Click here</a> to learn more

// No focus indicator
<button className="outline-none">Action</button>

Testing Overview

1. Automated Testing - Catches ~30-57% of issues (contrast, labels, ARIA)
2. Keyboard Testing - All interactions must work without a mouse
3. Screen Reader Testing - Content must make sense when read aloud

References

• WCAG 2.2 Guidelines
• WebAIM Accessibility
• WAI-ARIA Authoring Practices
• WebAIM Million Report
• A11y Project Checklist