Web Accessibility Developer Handbook
Designing for accessibility means ensuring that your digital products are usable by everyone, regardless of their physical or cognitive abilities. This guide provides the strategic framework, WCAG rules, and code patterns for modern inclusive development.
The POUR Principles
The Web Content Accessibility Guidelines (WCAG) are organized around four core principles that provide the foundation for web accessibility.
Perceivable
Information and user interface components must be presentable to users in ways they can perceive. This means users must be able to perceive the information being presented (it can't be invisible to all of their senses).
Operable
User interface components and navigation must be operable. This means that users must be able to operate the interface (the interface cannot require interaction that a user cannot perform).
Understandable
Information and the operation of user interface must be understandable. This means that users must be able to understand the information as well as the operation of the user interface.
Robust
Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. This means that users must be able to access the content as technologies advance.
Enhancement Path
Follow this sequential path to transform any interface into a standards-compliant accessible experience.
Semantic HTML
Use proper tags like <button> for actions and <a> for navigation. Ensure headings (H1-H6) follow a logical hierarchy.
<!-- Prefer Native Controls over Generic Divs/Spans --> <!-- Action triggers on-page state / modal --> <button type="button" onclick="openMenu()"> Open Navigation Menu </button> <!-- Navigation changes the URL/path --> <a href="/dashboard"> Go to User Dashboard </a> <!-- Logical Heading Hierarchy inside Main Content --> <h1>Accessibility Directory</h1> <h2>Latest Audit Compliance</h2> <h3>Issues Detected by Scanner</h3>
Keyboard Navigation
Ensure all interactive elements are reachable via the 'Tab' key and have visible focus indicators.
<!-- Native elements are focusable by default -->
<button type="submit">Submit Report</button>
<!-- Custom elements need tabindex, appropriate roles, and keys -->
<div
tabindex="0"
role="checkbox"
aria-checked="false"
onkeydown="handleCheckboxKey(event)"
>
Accept Terms and Conditions
</div>
<!-- Visible focus rings must always be styled clearly -->
<style>
*:focus-visible {
outline: 3px solid #1A5AC1;
outline-offset: 4px;
box-shadow: 0 0 0 4px rgba(26, 90, 193, 0.2);
}
</style>Alt Text for Images
Provide descriptive alternative text for all non-decorative images so screen readers can describe them.
<!-- Decorative element: hide completely from screen readers --> <img src="/assets/decorative-wave.svg" alt="" aria-hidden="true" /> <!-- Informative image with detailed descriptions --> <img src="/images/charts/q4-performance.png" alt="Detailed quarterly chart showing revenue rising 22 percent between October and December." /> <!-- User Avatar profile icon --> <img src="/images/users/avatar-jane-doe.jpg" alt="Jane Doe, Lead Accessibility Engineer" />
Color Contrast
Maintain a contrast ratio of at least 4.5:1 for normal text to ensure readability for users with low vision.
/* Avoid low contrast relationships */
.bad-practice-poor-contrast {
color: #8A8A8A;
background-color: #E2E2E2; /* Contrast: 1.8:1 (FAIL) */
}
/* Ensure deep contrast ratios compliant with WCAG AA/AAA */
.accessible-contrast-standard {
color: #111827; /* Deep Graphite */
background-color: #FAFAFA; /* Off-White: 18.5:1 (PASS) */
}
/* For larger text (18pt/24px up), a 3:1 ratio is permitted */
.large-heading-contrast {
font-size: 1.5rem;
font-weight: 700;
color: #4B5563;
background-color: #FFFFFF; /* Contrast: 4.6:1 (PASS) */
}Good Content Structure
Semantic structure helps screen readers and search engines navigate your content.
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
<main>
<h1>Main Heading</h1>
<p>Introductory paragraph.</p>
<section>
<h2>Section Title</h2>
<ul>
<li>List item one</li>
<li>List item two</li>
</ul>
</section>
</main>Descriptive Actions
Stop using "Click Here" or "Read More". Screen reader users often jump between links, and without context, generic labels are useless.
| Avoid | Prefer |
|---|---|
click here | donate now |
submit | download guide |
learn more | start voice banking |
start | explore resources |
read more | read our annual report |
go | search catalog |
next | continue to payment |
here | view shipping rates |
<button>🔍</button> | <button aria-label="Search site">🔍</button> |
<a href="/donate">explore →</a> | <a href="/donate">Donate now <span aria-hidden="true">→</span></a> |
Eye-Tracking Guide
Interaction for gaze-based users requires a different mental model centered around steady eye movements and dwell-time triggers.
Design Requirements
Are buttons and links on your website big enough to tap easily (about finger size or a kitkat bar, ~44px)?
"Increase target sizes in CSS to at least 44px. Use padding instead of margins to expand the clickable area."
"Avoid using small text links. Use built-in button blocks and ensure they are set to "Large" or "Extra Large" size."
Is there enough space between clickable items so they don’t feel crowded (at least half a finger size)?
"Adjust grid/flexbox gaps in your theme. Ensure a minimum of 16-24px spacing between interactive elements."
"When adding buttons or links, use a "Spacer" block or add margin-bottom to blocks to ensure they aren't touching."
Can you clearly see which item is currently selected or focused?
"Implement a high-contrast :focus and :hover state in your CSS. Use a thick border (3px+) or a distinct background color change."
"Choose theme colors that have high contrast. Ensure your primary action buttons stand out significantly from the background."
Can all menus be opened by clicking or staring (without hovering)?
"Convert hover-triggered dropdowns to click-triggered menus using JavaScript. Ensure the menu stays open until explicitly closed."
"In your CMS, prefer using a "Mega Menu" plugin that supports click-to-open, or simplify your navigation to avoid deep nesting."
Development Requirements
Can you use the whole site with just the keyboard (Tab and Enter)?
"Ensure all interactive elements are reachable via Tab and have proper ARIA roles. Fix any "tab-traps" in modals."
"Test your pages by pressing Tab. If the focus disappears or jumps randomly, rearrange your blocks in your editor to follow a logical order."
Are clickable areas slightly bigger than what you see on screen?
"Use pseudo-elements (::after) to expand the hit area of small buttons without changing their visual size."
"If a button feels hard to click, try adding more padding around the text within your button settings."
Do pop-ups stay long enough to be read easily?
"Increase the duration of toast notifications to at least 10 seconds, or require an explicit "Close" action."
"Avoid using auto-scrolling carousels or sliders. If you use them, set the slide duration to at least 15 seconds."
Does the system prevent accidental double clicks or repeated actions?
"Implement debouncing or throttling on click handlers for critical actions like "Submit" or "Buy"."
"Avoid placing "Delete" or "Submit" buttons immediately next to "Cancel" buttons where a misfire could cause data loss."
Product Requirements
Does every pop-up have a large, easy-to-click “Close” button?
"Ensure all modals have a large, accessible close button (X) that is keyboard and gaze reachable."
"When using popup plugins, choose templates with large close buttons and ensure they are not hidden on mobile."
Are main action buttons (like “Donate” or “Send”) clearly bigger or more visible than others?
"Use a distinct "Primary" button style with high visual weight. Implement a "Call to Action" CSS class."
"Use the "Buttons" block and give your main action a bright, contrasting color compared to secondary links."
Do you regularly test your site for accessibility standards (like WCAG AA)?
"Integrate automated accessibility testing tools like Axe or Lighthouse into your development workflow."
"Use an accessibility checker tool to scan your content for common issues like missing alt text or low contrast."
Quick Audit Checklist
Use this rapid checklist for manual QA cycles before any production release.
Ready to verify your site?
Run our automated scan to identify critical accessibility blockers in seconds.
Resources
Deepen your understanding of web accessibility with these authoritative guides and techniques.