Accessibility Best Practices

This skill covers comprehensive accessibility patterns for building inclusive interfaces — from prevention to identification to remediation. It addresses the most common accessibility issues found on the web (based on WebAIM Million reports showing 95% of sites fail WCAG AA).

Use-When

This skill activates 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

Accessibility testing requires multiple approaches:

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

Run validation on all changes to ensure no regressions.

a11y-best-practices