Web Accessibility Guide 📖

Monthly Accessibility Challenge #

Small, practical tasks to improve accessibility—one challenge at a time.

Challenge: Fix an inaccessible form

The form below has common accessibility issues. Identify and fix them: labels, error messages, focus order, and keyboard support.

Join the challenge (open issue) Submit a PR

Show the broken example

⚠️ Warning: This form is intentionally broken for demonstration purposes. It contains multiple accessibility issues that need to be fixed.

Hint: Check labels, focus states, and error feedback.

Challenge Archive #

Previous challenges and community submissions.

Screen Reader Optimization #

Screen readers help visually impaired users navigate websites. Semantic HTML and ARIA attributes improve compatibility.

ARIA Roles and Labels

Use ARIA roles to describe elements: <nav role="navigation">
Add aria-label to buttons and links for better descriptions: <button aria-label="Submit Form">Submit</button>

Knowledge Check

Loading question…

Before / After: Descriptive Links

<p>To learn more about WCAG, <a href="/wcag">click here</a>.</p>

<button onclick="save()">Click here</button>

<a href="/report.pdf">Download</a>

Issues: "Click here" and "Download" are meaningless when read out of context. Screen readers often list all links on a page — every one of these would sound identical.

<p>Learn more about
  <a href="/wcag">WCAG accessibility guidelines</a>.
</p>

<button type="button" onclick="save()">
  Save your progress
</button>

<a href="/report.pdf"
   aria-label="Download accessibility audit report (PDF)">
  Download report
</a>

Fixed: Each link and button describes its purpose. The PDF link uses aria-label to provide extra context (file type). Screen reader users can scan links and immediately understand where each one leads.

Contrast & Colors #

Ensure text is readable with sufficient contrast ratios. Use WCAG standards for guidance.

Tools for Testing Contrast

Contrast Checker

Text color

Background color

Contrast Ratio: 21.00

WCAG AA: ✓ Pass

WCAG AAA: ✓ Pass

Accessibility Checker

Paste HTML to analyze

Quick Check

Which of the following ensures sufficient color contrast?

Keyboard Navigation #

Keyboard accessibility is essential for users who cannot use a mouse. Ensure proper focus management.

Focus Traps

Prevent users from navigating outside modals or overlays.

Live Playground

Edit HTML:

Screen reader says: "Button 1, button. — Button 2, button. — Close, button."

Quick Check

What keeps a modal keyboard-friendly for everyone?

Dynamic Content #

Use ARIA live regions to announce dynamic changes to screen readers.

Welcome to our site!

Screen reader says: "The content has been updated!"

Live Playground

Edit HTML:

Quick Check

How can you make sure important dynamic updates are announced?

Form Validation #

Use accessible error messages for invalid inputs. ARIA attributes help convey errors to screen readers.

Screen reader says: "Email, edit text. Please enter a valid email address."

Live Playground

Edit HTML:

<form onsubmit="validateForm(event)">
  <h3>Accessible Form Demo</h3>
  <div>
    <label for="pg-name">Name (required):</label>
    <input type="text" id="pg-name" aria-describedby="pg-name-error" required>
    <div id="pg-name-error" aria-live="polite"></div>
  </div>
  <div>
    <label for="pg-email">Email:</label>
    <input type="email" id="pg-email" aria-describedby="pg-email-error">
    <div id="pg-email-error" aria-live="polite"></div>
  </div>
  <button type="submit">Submit</button>
</form>
<style>
label { display: block; margin: 10px 0 5px 0; font-weight: bold; }
input { 
  width: 100%; 
  padding: 8px; 
  border: 2px solid #ddd; 
  border-radius: 4px; 
  margin-bottom: 5px; 
}
input:focus { 
  outline: none; 
  border-color: #007bff; 
}
input:invalid { 
  border-color: #dc3545; 
}
button { 
  padding: 10px 20px; 
  background: #007bff; 
  color: white; 
  border: none; 
  border-radius: 4px; 
  margin-top: 10px; 
}
button:focus { 
  outline: 3px solid #ffcc00; 
  outline-offset: 2px; 
}
.error { 
  color: #dc3545; 
  font-size: 14px; 
  margin-top: 5px; 
}
</style>
<script>
function validateForm(event) {
  event.preventDefault();
  const name = document.getElementById('pg-name');
  const email = document.getElementById('pg-email');
  const nameError = document.getElementById('pg-name-error');
  const emailError = document.getElementById('pg-email-error');
  
  nameError.textContent = '';
  emailError.textContent = '';
  
  if (!name.value.trim()) {
    nameError.textContent = 'Name is required';
    name.focus();
    return;
  }
  
  if (email.value && !email.value.includes('@')) {
    emailError.textContent = 'Please enter a valid email address';
    email.focus();
    return;
  }
  
  alert('Form submitted successfully!');
}
</script>

Quick Check

Which practice keeps form error messages accessible?

Before / After: Form Labels & Errors

<form>
  <input type="text" placeholder="Name">
  <input type="email" placeholder="Email">
  <div style="color:red">Wrong!</div>
  <button type="submit">Send</button>
</form>

Issues: No <label> elements — screen readers cannot identify fields. Error text is vague and not linked to any input. Placeholder text disappears on focus, leaving no visible label.

<form novalidate>
  <label for="name">Name (required):</label>
  <input id="name" type="text" required
         aria-describedby="name-error">
  <div id="name-error" role="alert"
       aria-live="assertive"></div>

  <label for="signup-email">Email:</label>
  <input id="signup-email" type="email"
         aria-describedby="email-error">
  <div id="email-error" role="alert"
       aria-live="assertive"></div>

  <button type="submit">Send</button>
</form>

Fixed: Every field has a visible <label> linked via for/id. Errors use aria-describedby so screen readers announce them. role="alert" with aria-live="assertive" ensures errors are announced immediately.

Accessible Animations #

Animations can enhance user experience but should be designed carefully to ensure they do not cause discomfort or confusion, especially for users sensitive to motion.

Example: Motion Reduction

Use media queries to detect user preferences for reduced motion:

@media (prefers-reduced-motion: reduce) {
  * {
    animation: none;
    transition: none;
  }
}

Knowledge Check

Loading question…

Multilingual Support #

Providing multilingual support ensures inclusivity for users who speak different languages.

Best Practices for Multilingual Websites

Use the lang attribute to specify the language of the content:

<html lang="en">

Provide a language switcher for easy navigation between languages.
Ensure translations are accurate and culturally appropriate.

Language Detection Example

Detect the user's preferred language and set the page language accordingly.

navigator.language || navigator.userLanguage;

Display "Hello World" in Multiple Languages

Choose a language:

Hello World

Knowledge Check

Loading question…

Knowledge Check

Loading question…

Dark Mode #

Dark mode helps reduce eye strain and provides better readability in low-light environments.

Enable Dark Mode

Code Example

Below is an example of how to implement dark mode using JavaScript and CSS:

CSS:

/* General Dark Mode Styles */
.dark-mode {
  background-color: #121212;
  color: #f4f4f4;
}

.dark-mode header {
  background-color: #1f1f1f;
}

JavaScript:

function toggleTheme() {
  const body = document.body;
  const isDarkMode = body.classList.toggle("dark-mode");
  localStorage.setItem("dark-mode", isDarkMode ? "enabled" : "disabled");
}

// Load user preference on page load
document.addEventListener("DOMContentLoaded", () => {
  if (localStorage.getItem("dark-mode") === "enabled") {
    document.body.classList.add("dark-mode");
  }
});

Knowledge Check

Loading question…

Interactive Widgets #

Accessible sliders, date pickers, and other custom UI components.

Adjust Volume: 50

Select a Date:

Accessible Notifications #

Notifications should be accessible to all users, including those using screen readers. Use ARIA live regions to ensure important updates are announced.

Implementing Screen-Reader Friendly Notifications

Use role="alert" or aria-live="polite" for inline notifications to announce updates.
Ensure notifications have clear and concise messages.

Example:

<div role="alert" aria-live="assertive" class="toast-notification">
  Your changes have been saved successfully!
</div>

Knowledge Check

Loading question…

Hall of Fame #

Thanks to everyone improving accessibility—one contribution at a time.

Contribute #

Want to help make the web more inclusive? Here are easy ways to contribute.

Open an Issue

Report a bug, suggest a feature, or improve documentation.

Choose an issue template

Good First Issues

New to open source? Start here—small, friendly tasks.

View good first issues

Monthly Challenge

Join the monthly accessibility challenge and learn by doing.

Go to challenge

Submit a Pull Request

Small improvements are welcome—typos, examples, translations, UI polish.

Start a PR

Translate the Guide

Help translate UI and section titles. Add or improve a language file under /lang.

Translation guide

First time contributing? I'll help you through it—open an issue and say hi 👋

Translate the Guide #

Translations are community-driven. You can start small—just the UI and section headings.

Pick a language file under /lang (e.g., es.json).
Copy en.json as a base and translate values.
Keep keys unchanged; translate only the text.
Test locally and open a PR.

Open CONTRIBUTING.md

Community #

Have questions, ideas, or want to collaborate? Start a discussion.

Start a Discussion Open an Issue

Q&A — Ask questions and get help
Ideas — Suggest improvements or new sections
Translations — Help translate the guide
Monthly Challenge — Join and share progress
Show & Tell — Share PRs, demos, and learnings

Accessibility Personas #

Real people use the web in different ways. These personas help you design with empathy.

Amara — Screen Reader User

Goals: Navigate pages, fill out forms, and read content independently using a screen reader.
Pain points: Unlabelled buttons, missing alt text, dynamic content that updates silently, poor heading structure.
What helps: Semantic HTML, descriptive aria-label attributes, proper heading hierarchy, and aria-live regions for dynamic updates. See Screen Readers and Dynamic Content.

Leo — Keyboard-Only User

Goals: Complete every task — menus, forms, modals — without a mouse or trackpad.
Pain points: Focus traps with no escape, invisible focus indicators, interactive elements unreachable by Tab.
What helps: Visible :focus-visible outlines, logical tab order, skip links, and proper focus management in modals. See Keyboard Navigation.

Priya — Low Vision / Zoom User

Goals: Read all content comfortably at 200–400% zoom or with custom font sizes.
Pain points: Fixed-width layouts that break at high zoom, low contrast text, text embedded in images.
What helps: Responsive layouts, sufficient contrast ratios (AA minimum), resizable text, and real text instead of images. See Contrast & Colors and Dark Mode.

Sam — Cognitive Load Sensitivity

Goals: Understand content quickly without being overwhelmed by motion, clutter, or complex language.
Pain points: Auto-playing animations, walls of text, unclear error messages, unexpected layout shifts.
What helps: Respecting prefers-reduced-motion, clear form error messages, simple language, and consistent navigation. See Accessible Animations and Form Validation.

Contributor Spotlight #

Each month we highlight a community member who's making the web more accessible.

Accessibility Stories #

Real-world moments that show why accessibility matters — and what we can learn from them.

The Form That Locked Everyone Out

A checkout form relied entirely on placeholder text — no visible labels, no error messages. A screen reader user couldn't tell which field was which, and keyboard users had no idea what went wrong after pressing Submit. The team added proper <label> elements and aria-describedby error links, and support tickets dropped by 40% in a week.

Lesson learned: Labels aren't optional — they're the first thing assistive tech looks for.

Forms Screen readers

Trapped Inside a Modal

A marketing site launched a newsletter popup that couldn't be closed by keyboard. Pressing Escape did nothing, and Tab cycled through the page behind the overlay instead of staying inside the modal. After a user complaint went viral, the team added focus trapping, an Escape handler, and returned focus to the trigger button on close.

Lesson learned: Every modal needs a focus trap, an Escape exit, and a plan for where focus goes when it closes.

Keyboard Focus management

The Dashboard Nobody Could Read

An analytics dashboard used light-gray text on a white background for secondary stats. It looked "clean" in mockups, but users with low vision couldn't read the numbers, and everyone struggled in bright sunlight on laptops. Bumping the text to a 4.5:1 contrast ratio fixed readability without changing the design's feel.

Lesson learned: Contrast isn't just an accessibility rule — it's a readability baseline for every user, in every environment.

Contrast Low vision

What is Accessibility? #

Why is Accessibility Important?

Monthly Accessibility Challenge #

Challenge: Fix an inaccessible form

Challenge Archive #

Screen Reader Optimization #

ARIA Roles and Labels

Knowledge Check

Before / After: Descriptive Links

Contrast & Colors #

Tools for Testing Contrast

Contrast Checker

Accessibility Checker

Quick Check

Keyboard Navigation #

Focus Traps

Quick Check

Dynamic Content #

Quick Check

Form Validation #

Quick Check

Before / After: Form Labels & Errors

Accessible Animations #

Example: Motion Reduction

Knowledge Check

Multilingual Support #

Best Practices for Multilingual Websites

Language Detection Example

Display "Hello World" in Multiple Languages

Knowledge Check

Knowledge Check

Dark Mode #

Enable Dark Mode

Code Example

CSS:

JavaScript:

Knowledge Check

Interactive Widgets #

Accessible Notifications #

Implementing Screen-Reader Friendly Notifications

Knowledge Check

Hall of Fame #

Contribute #

Open an Issue

Good First Issues

Monthly Challenge

Submit a Pull Request

Translate the Guide

Translate the Guide #

Community #

Accessibility Personas #

Amara — Screen Reader User

Leo — Keyboard-Only User

Priya — Low Vision / Zoom User

Sam — Cognitive Load Sensitivity

Contributor Spotlight #

Accessibility Stories #

The Form That Locked Everyone Out

Trapped Inside a Modal

The Dashboard Nobody Could Read