DEV Community: Priya Nair

Mastering Focus Management in React 19: Solving the Single-Page Application Routing Gap for WCAG 2.1 and EN 301 549 Compliance

Priya Nair — Sun, 21 Jun 2026 08:25:57 +0000

Mastering Focus Management in React 19: Solving the Single-Page Application Routing Gap for WCAG 2.1 and EN 301 549 Compliance

Meta: Stop losing your users on page transitions. Learn how to manage focus in React 19 to meet WCAG 2.1 standards and provide a seamless screen reader experience.

When you click a link in a traditional multi-page website, the browser does something vital: it refreshes the page, resets the focus to the top of the document, and announces the new page title. For a sighted user, this is a blink-and-you-miss-it transition. For a screen reader user, it is a critical signal that they have arrived at a new destination.

In a Single-Page Application (SPA) built with React, this behavior vanishes. Because the page doesn't actually refresh—React simply swaps out the component tree—the browser’s focus stays exactly where it was. If the user clicked a "View Profile" link in the footer and that link disappears from the DOM during the transition, the focus often drops back to the <body> or, worse, vanishes into a "focus vacuum."

The result? A screen reader user is left stranded. They don't know if the page changed, where they are, or how to start reading the new content. This isn't just a "UX quirk"; it is a direct violation of WCAG 2.1 Success Criterion 2.4.3 (Focus Order) and is a failure under the EN 301 549 European accessibility standards.

If you want your app to be truly inclusive, you have to take manual control of the focus. Here is how to do it professionally in React 19.

Why Focus Management is a Business Requirement

I often hear developers say, "Our site passes the automated audit, so we're good." Automated tools (like Axe or Lighthouse) are great for catching missing alt text or low contrast, but they cannot tell you if your focus management is logical. They can't feel the frustration of a user who has to tab through the entire navigation menu again every time they change pages.

Poor focus management creates a "cognitive tax." When users have to hunt for their position on a page, they fatigue faster and abandon the product. In the context of European regulations (EN 301 549), failing to provide a predictable focus order can leave your organization legally vulnerable. Accessibility is not a feature you "add" at the end of a sprint; it is a core engineering requirement for a production-ready application.

The "Focus Vacuum" Problem

Imagine a user navigating your app using a screen reader (like NVDA or VoiceOver). They click a link to navigate to /settings. React updates the DOM. The link they just clicked is gone. The browser now has no active element.

Depending on the browser and screen reader combination, one of three things happens:

Focus resets to the very top of the document (forcing the user to tab through the global header again).
Focus stays on the body element, meaning the user has to manually search for the main content.
The focus "gets lost," and the screen reader remains silent, leaving the user wondering if the click even worked.

To solve this, we need to implement a "Focus Wrapper" or a global focus management strategy that explicitly moves the focus to a known, logical location upon every route change.

The Implementation: A Custom Focus Manager

In React 19, we can leverage the updated hooks and the refined component lifecycle to create a reusable FocusManager component. The goal is to move focus to a top-level heading (usually the <h1>) of the new page.

Step 1: Creating the Focusable Wrapper

First, we need a way to make an element focusable that isn't naturally focusable (like an <h1>). We do this using tabIndex="-1". This allows the element to receive focus programmatically via JavaScript, but prevents it from being part of the natural Tab sequence, so we don't clutter the user's navigation.

import React, { useEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom'; // Assuming react-router-dom

const PageFocusManager = ({ children }) => {
  const { pathname } = useLocation();
  const focusRef = useRef(null);

  useEffect(() => {
    // We use a small timeout to ensure the DOM has fully updated 
    // and the new page content is rendered before attempting to focus.
    const timer = setTimeout(() => {
      if (focusRef.current) {
        focusRef.current.focus();
      }
    }, 100);

    return () => clearTimeout(timer);
  }, [pathname]);

  return (
    <div className="page-wrapper">
      {/* 
          tabIndex="-1" is the magic here. 
          It allows .focus() to work without adding the element to the Tab order.
      */}
      <h1 ref={focusRef} tabIndex="-1" style={{ outline: 'none' }}>
        {/* This will be populated by the page content, 
            or we can use a visually hidden announcement */}
        <span className="sr-only">Page Loaded</span>
      </h1>
      {children}
    </div>
  );
};

export default PageFocusManager;

Step 2: The "Visually Hidden" Pattern

You might be thinking, "I don't want my <h1> to be the focus target because it looks weird when it's highlighted."

The solution is the .sr-only (screen-reader only) CSS pattern. This keeps the element available to assistive technology while hiding it from sighted users.

/* Standard .sr-only utility for inclusive design */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Advanced Pattern: Managing Modals and Dialogs

Routing isn't the only place where focus breaks. Modals are the most common source of accessibility failures. When a modal opens, focus must move into the modal. When it closes, focus must return exactly to the button that opened it.

Failure to do this violates WCAG 2.1 2.4.3. If you open a modal and the focus stays on the trigger button behind the modal's backdrop, the user is effectively trapped in a "ghost" layer.

Here is a professional implementation of a focus-trapped modal:

import React, { useEffect, useRef } from 'react';

const AccessibleModal = ({ isOpen, onClose, title, children }) => {
  const modalRef = useRef(null);
  const triggerRef = useRef(null);

  useEffect(() => {
    if (isOpen) {
      // Store the element that triggered the modal to return focus later
      triggerRef.current = document.activeElement;

      // Move focus to the modal container or the first focusable element
      modalRef.current?.focus();
    } else {
      // Return focus to the trigger button when the modal closes
      triggerRef.current?.focus();
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div 
      className="modal-overlay" 
      role="dialog" 
      aria-modal="true" 
      aria-labelledby="modal-title"
    >
      <div 
        ref={modalRef} 
        tabIndex="-1" 
        className="modal-content"
      >
        <h2 id="modal-title">{title}</h2>
        {children}
        <button onClick={onClose}>Close</button>
      </div>
    </div>
  );
};

The "Keyboard Trap" and Focus Trapping

Moving focus into a modal is only half the battle. You must also prevent the user from Tabbing out of the modal and back into the background page. This is called a "Keyboard Trap," and it's a critical failure.

To solve this, you need to listen for the Tab key and wrap the focus from the last focusable element back to the first.

const handleKeyDown = (e) => {
  if (e.key !== 'Tab') return;

  const focusableElements = modalRef.current.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];

  if (e.shiftKey && document.activeElement === firstElement) {
    lastElement.focus();
    e.preventDefault();
  } else if (!e.shiftKey && document.activeElement === lastElement) {
    firstElement.focus();
    e.preventDefault();
  }
};

Testing Your Implementation

You cannot verify focus management by looking at your code. You must test it. I recommend a three-tiered testing strategy:

The Keyboard-Only Test: Put your mouse away. Navigate your entire application using only Tab, Shift+Tab, and Enter. If you ever "lose" your place or have to Tab through the whole header to reach the content, your focus management is broken.
The Screen Reader Test: Use NVDA (Windows) or VoiceOver (macOS). Navigate through a route change. Does the screen reader immediately announce the page title? If it says "blank" or starts reading the navigation menu, you have a gap.
The document.activeElement Audit: Open your DevTools console and type document.activeElement after a page transition. If it returns <body>, you are failing WCAG 2.1.

Summary of Best Practices for React Developers

To ensure your application meets WCAG 2.1 and EN 301 549 compliance, follow these non-negotiable rules:

Route Changes: Always move focus to the <h1> or a visually hidden "Page Loaded" announcement.
Modal Entry: Move focus to the modal container or the first interactive element immediately upon opening.
Modal Exit: Return focus to the element that triggered the modal.
Tab Index: Use tabIndex="-1" for programmatic focus targets that shouldn't be in the natural Tab order.
Semantic HTML: Use role="dialog" and aria-modal="true" for overlays to signal to screen readers that the rest of the page is inert.

Quick Reference Checklist

Action	Target	WCAG Criterion	Requirement
Page Transition	`<h1>` or Page Title	2.4.3	Predictable focus order
Open Modal	Modal Container	2.4.3	Focus moved to active content
Close Modal	Trigger Button	2.4.3	Restore previous context
Navigation	Menu items	2.1.1	Full keyboard accessibility

Final Thoughts

Focus management is often overlooked because it's "invisible" to most developers. But for a significant portion of your users, focus is the only way they can perceive the structure of your application. By implementing these patterns in React 19, you aren't just checking a compliance box—you are removing barriers and making your software usable for everyone.

Stop treating accessibility as a "nice-to-have" cleanup task. Treat it as a technical requirement, just like performance or security.

What’s your biggest struggle with focus management in SPAs? Do you use a specific library for focus trapping, or do you prefer custom hooks? Let's discuss in the comments.

About the Author: Priya Nair is a Senior Frontend Developer and Accessibility Consultant based in Amsterdam. She specializes in WCAG 2.1 compliance and inclusive design patterns for high-growth startups. She is a contributor to several open-source accessibility libraries and a frequent speaker on the intersection of engineering and inclusion.

Beyond the Div: Leveraging Semantic HTML to Solve Complex ARIA Failures in Modern React Applications

Priya Nair — Thu, 18 Jun 2026 08:05:57 +0000

Meta: Stop over-using ARIA. Learn how semantic HTML solves complex accessibility failures in React and how to meet WCAG 2.1 AA without the ARIA overhead.

Beyond the Div: Leveraging Semantic HTML to Solve Complex ARIA Failures in Modern React Applications

I remember a project I worked on a few years ago for a fintech client in Amsterdam. The team had built a beautiful, high-performance dashboard in React. Visually, it was stunning. But when I opened VoiceOver (a screen reader for macOS), the experience was a nightmare.

The entire application was essentially a "div soup." Every button was a div with an onClick handler; every navigation link was a span with a cursor: pointer. To "fix" the accessibility, the developers had layered on a massive amount of ARIA (Accessible Rich Internet Applications) attributes. They had role="button", tabIndex="0", and complex aria-labelledby relationships everywhere.

On paper, the code looked "compliant." In practice, it was fragile. A single typo in an ID reference broke the relationship between a label and an input, and the keyboard navigation was inconsistent because they had to manually manage focus with useEffect hooks. They were working ten times harder to simulate behavior that the browser provides for free.

The most important lesson I learned from that project—and one I share in my "Accessibility Office Hours" every month—is this: ARIA is a polyfill for missing semantics. The best ARIA is no ARIA.

If you can use a native HTML element to achieve your goal, do it. Every time you use a div where a button or nav should be, you are opting out of decades of browser and assistive technology optimization.

The "ARIA Paradox" in Modern Frameworks

In the React ecosystem, we often get caught up in the "componentization" of everything. We create <CustomButton /> or <CustomInput /> components. Because these are often wrapped in multiple layers of abstraction, developers tend to reach for ARIA roles to "tell" the screen reader what the component is.

The paradox is that the more ARIA you add to a non-semantic element, the more likely you are to introduce a bug. ARIA doesn't change the behavior of an element; it only changes how it is announced.

If you give a div a role="button", the screen reader says "Button," but the browser still doesn't know that the Enter key or the Space bar should trigger a click event. You then have to write a custom onKeyDown handler to handle those keys. If you forget one, you've just failed WCAG 2.1 Success Criterion 2.1.1 (Keyboard).

Compare that to a native <button>. It is focusable by default, it triggers on Enter and Space by default, and it is announced as a button by default. Zero lines of extra JavaScript.

The Cost of "Div Soup"

Let's look at a common failure pattern. Imagine a custom dropdown menu built with div elements.

The "Wrong" Way (The ARIA Overload)

// ❌ Fragile and over-engineered
const CustomDropdown = ({ options }) => {
  return (
    <div 
      role="combobox" 
      aria-expanded="false" 
      aria-haspopup="listbox" 
      className="dropdown-container"
      tabIndex="0"
      onKeyDown={handleKeyDown} // Manually managing Enter/Space/Arrows
    >
      Select an option...
      <div role="listbox" className="options-list">
        {options.map(opt => (
          <div 
            role="option" 
            tabIndex="-1" 
            className="option-item"
            onClick={() => selectOption(opt)}
          >
            {opt.label}
          </div>
        ))}
      </div>
    </div>
  );
};

In the example above, we are fighting the browser. We have to manually manage tabIndex, manually handle keyboard events, and manually track the aria-expanded state. If the state logic fails, the screen reader user is left in a vacuum.

The "Right" Way (Semantic HTML)

Now, let's look at how we achieve the same result using semantic HTML. While some complex patterns truly require ARIA, many "custom" components can be simplified.

// ✅ Robust, accessible, and lightweight
const SemanticDropdown = ({ options }) => {
  return (
    <div className="field-wrapper">
      <label htmlFor="category-select">Choose a category</label>
      <select id="category-select" name="category">
        {options.map(opt => (
          <option key={opt.id} value={opt.id}>
            {opt.label}
          </option>
        ))}
      </select>
    </div>
  );
};

By using <select> and <option>, we satisfy WCAG 2.1 SC 4.1.2 (Name, Role, Value) automatically. The browser handles the keyboard navigation, the focus management, and the screen reader announcement without a single line of custom ARIA.

Solving Common ARIA Failures with Semantics

Let's dive into three common areas where developers over-use ARIA and how to fix them using a semantic-first approach.

1. Clickable Elements

The Mistake: Using div or span for buttons because "it's easier to style."
The Failure: Failure of WCAG 2.1 SC 2.1.1 (Keyboard). Users who rely on keyboards cannot tab to your "button," and users with screen readers may not realize the element is interactive.

The Fix: Use a <button>. If you hate the default browser styling, use CSS to reset it.

/* Resetting button styles to make it a blank canvas */
.btn-reset {
  background: none;
  color: inherit;
  border: none;
  padding: 0;
  font: inherit;
  cursor: pointer;
  outline: inherit;
}

// Use the reset class to get the look you want with the functionality you need
<button className="btn-reset" onClick={doSomething}>
  Click Me
</button>

2. Navigation Landmarks

The Mistake: Wrapping your site navigation in a div and adding role="navigation".
The Failure: While technically compliant, it's redundant. If you forget the role on one page, you break the landmark structure.

The Fix: Use the <nav> element. It provides the landmark role implicitly.

// Instead of <div role="navigation">
<nav aria-label="Main Navigation">
  <ul>
    <li><a href="/home">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

Note: Adding aria-label to the <nav> is important if you have multiple navigation blocks (e.g., Header and Footer) so users can distinguish between them.

3. Form Labels and Associations

The Mistake: Using a div as a label and trying to connect it using aria-labelledby.
The Failure: If the ID is duplicated or missing, the association is lost. This violates WCAG 2.1 SC 1.3.1 (Info and Relationships).

The Fix: Use the <label> element with the htmlFor attribute.

// ❌ Fragile
<div id="label-1">Email Address</div>
<input aria-labelledby="label-1" type="email" />

// ✅ Robust
<label htmlFor="email-field">Email Address</label>
<input id="email-field" type="email" />

When is ARIA Actually Necessary?

I don't want you to think ARIA is "evil." It is an incredibly powerful tool. However, it should be your last resort, not your first step.

You should use ARIA when:

You are building a complex widget that HTML doesn't have a native equivalent for (e.g., a Tab panel, a Tree view, or a Modal dialog).
You need to communicate dynamic changes that aren't visually obvious (e.g., using aria-live to announce a successful form submission without moving the user's focus).
You are enhancing a native element (e.g., adding aria-invalid="true" to an input when a validation error occurs).

Even then, follow the First Rule of ARIA: If you can use a native HTML element or attribute with the semantics and behavior you require already built-in, do so.

A Practical Workflow for React Developers

If you're working in a fast-paced startup environment, you don't have time to read the entire WAI-ARIA specification every morning. Here is the workflow I use when building new components:

The Semantic Search: Ask, "Is there an HTML element that does this?" (e.g., Instead of a div with a click handler $\rightarrow$ <button>. Instead of a div for a list $\rightarrow$ <ul> and <li>).
The Keyboard Test: Unplug your mouse. Can you reach the element? Can you trigger it? Does the focus indicator (the outline) clearly show where you are?
The Screen Reader Audit: Use VoiceOver (Mac) or NVDA (Windows). Does the element announce its purpose and state?
The ARIA Layer: Only now, if the behavior is missing or the announcement is vague, add the minimum amount of ARIA required to bridge the gap.

Accessibility Essentials Checklist

To make this actionable, here is a quick reference for your next PR review:

Instead of...	Use...	Why?	WCAG Criteria
`<div onClick={...}>`	`<button>`	Native focus & keyboard support	2.1.1
`<div className="header">`	`<header>`	Structural landmark for screen readers	1.3.1
`<span className="link">`	`<a>`	Proper navigation and SEO	2.1.1 / 4.1.2
`<div role="main">`	`<main>`	Implicit landmark	1.3.1
`<div>` (as a list)	`<ul>` / `<li>`	Announces number of items in the list	1.3.1

Final Thoughts: Accessibility is a Business Requirement

Some developers argue that using native elements limits their design flexibility. This is a myth. CSS is powerful enough to make a <button> look like anything—a pill, a square, a ghost button, or a complex icon. What you cannot "style" is the underlying accessibility tree that a screen reader relies on.

When we prioritize semantic HTML, we aren't just "checking a box" for compliance. We are ensuring that a user with a motor impairment can navigate our site, a blind user can understand our layout, and a user with a cognitive disability can predict how our interface behaves.

Building inclusive software isn't about adding features; it's about removing barriers. Start with the basics. Stop the "div soup." Let the browser do the heavy lifting.

Let's Discuss

What is the most frustrating "custom" component you've encountered that should have just been a native HTML element? Or, have you found a specific case where ARIA was the only way to solve a problem? Let's talk in the comments.

About the Author:
Priya Nair is a Senior Frontend Developer and Accessibility Consultant based in Amsterdam. She specializes in WCAG 2.1 compliance and inclusive design patterns for React applications. She is a frequent speaker at a11y conferences and maintains several open-source accessibility checklists on GitHub.

Keyboard Navigation Testing: The 20-Minute Audit Any Developer Can Run

Priya Nair — Wed, 15 Apr 2026 07:17:03 +0000

Keyboard Navigation Testing: The 20-Minute Audit Any Developer Can Run

Meta: You don't need tools to test keyboard navigation. You just need your keyboard and 20 minutes. Here's the exact walkthrough I use.

Keyword: keyboard navigation accessibility testing web

Tags: #accessibility #testing #wcag #webdev #a11y

Why Keyboard Navigation Matters (More Than You Think)

Before we get into the how-to, let me explain the why.

Keyboard-only users aren't a tiny edge case. They include:

Blind users — Screen reader software doesn't control the mouse; it navigates via keyboard.
Motor disabilities — People with cerebral palsy, Parkinson's, or arthritis can't manipulate a mouse.
Power users — Developers, writers, accessibility professionals who just prefer keyboard.
Broken hands, surgery recovery — You'd be surprised how often this happens.
Mobile users tabbing through a website — Yes, mobile has Tab support in some browsers.

So when a website breaks keyboard navigation, you're not just inconveniencing someone. You're locking them out.

The good news? Testing keyboard navigation takes no special tools, no software, no budget. Just your keyboard and 20 minutes.

The Only Tools You Need

Your keyboard. Seriously.

Tab — Move focus forward (one interactive element at a time)

Shift+Tab — Move focus backward

Enter — Activate a button or link

Space — Activate a button or toggle a checkbox

Arrow Keys — Navigate within components (menu items, radio buttons, slider)

Escape — Close modals, collapse menus

That's it. You don't need browser extensions, accessibility tools, or a screen reader. Just these keys.

The 20-Minute Keyboard Audit: Step-by-Step

Step 1: The Tab Test (3 minutes)

Open your site in a fresh browser tab. Press Tab.

Did a focus outline appear? If not, you already found a problem.

Now keep pressing Tab. Watch the focus move through the page.

Questions to answer:

Does focus appear as a visible outline, border, or shadow around each element?
Does focus move logically through the page? (Left to right, top to bottom, roughly in reading order?)
Does focus move through every interactive element? (Buttons, links, inputs, dropdowns?)
Are there any elements where focus gets stuck or skips unexpectedly?

What to look for:

If you can't see focus, that's a problem. The page fails WCAG 2.4.13 immediately.
If focus jumps around randomly (skips to the footer, then back to the nav), there's a tabindex problem.
If you reach an element and focus disappears, there's a z-index or visibility bug.

Quick fix: If focus is invisible, the site probably has outline: none; in the CSS. That needs to be removed or replaced with a visible style.

Step 2: The "Where Am I?" Test (2 minutes)

While you're tabbing through, ask yourself: Can I tell where focus is?

This is different from step 1. It's not "does focus exist"—it's "is it obvious enough?"

If the focus indicator is a 1px gray line on a gray background, technically it exists. But in practice, you can't see it. That's a failure.

Pass criteria:

You can see the focus indicator without squinting.
The focus indicator has decent contrast (at least 3:1 ratio against the background).
It's at least 2px thick or surrounded by spacing (like a 3px box-shadow).

Quick fix: If focus is hard to see, add this to your CSS:

*:focus-visible {
  outline: 3px solid #0066ff;
  outline-offset: 2px;
}

Not perfect, but it works as a baseline.

Step 3: The Button Activation Test (2 minutes)

Keep tabbing. When you reach a button, press Enter. When you reach a button-like link, press Enter too.

Questions:

Does the button activate? (Page submits, modal opens, action completes?)
Do you need to press Space instead of Enter? (Shouldn't happen—buttons should respond to Enter.)
What about toggle buttons or checkboxes? Do they respond to Space?

What's broken:

A button that requires clicking, doesn't respond to Enter → failure
A custom <div role="button"> that doesn't respond to keyboard → failure
A form input that requires mouse interaction → failure

Quick reference:

<button> and <a> → Enter
<input type="checkbox"> and <input type="radio"> → Space (and Arrow keys for radio groups)
<input type="submit"> → Enter

Step 4: The Modal Dialog Test (3 minutes)

If your site has a modal (popup, dialog, overlay), test it.

Tab into the modal:

Does focus enter the modal?
Can you tab through all the buttons/inputs inside the modal?

Escape to close:

Press Escape. Does the modal close?
After it closes, does focus return to the element that opened it? (Not always required, but it's nice.)

Focus trap:

If you Tab to the last button in the modal, does Tab again wrap back to the first button? (This is called a focus trap—it prevents you from tabbing out to the page behind.)
Focus traps are okay if they're intentional (some accessibility guidelines recommend them for modals). But you need to be able to close with Escape.

Test scenario:
Open a modal. Tab through every element. Press Escape. Does the modal close? Good. Now open it again and try to Tab out of it using the last button. If you can't escape without pressing Escape, that's a trap. It might be intentional, but it should be documented or clearly closable.

Step 5: The Dropdown & Menu Test (3 minutes)

If you have navigation menus or dropdown selects, test them.

Navigation menu with submenus:

Tab to the menu trigger.
Does the menu open automatically? (Should, or should require Enter.)
Can you Arrow-key down to submenu items?
Arrow-left and Arrow-right to navigate between menus?
Escape to close?

Native HTML <select> dropdown:

Tab to it. Arrow-key down to see options. Very smooth.

Custom dropdowns built with <ul> and JavaScript:

This is where bugs hide. Test Tab to open, Arrow keys to navigate, Enter to select, Escape to close.

What's broken:

Custom dropdown that requires clicking to open (arrow keys don't work) → failure
Dropdown menu that disappears when you blur it, trapping you if you Tab into it → bad pattern

Step 6: The Form Completion Test (3 minutes)

Fill out a form entirely using only your keyboard.

Tab through each field.
Type in text inputs.
Tab to checkboxes and press Space to check them.
Tab to radio buttons and use Arrow keys to select.
Tab to a submit button and press Enter.

Questions:

Can you reach every input?
Can you check/uncheck everything?
Can you submit the form?
Do error messages appear? If so, can you navigate to them?

What's broken:

A required field that's keyboard-inaccessible (hidden <input> with no label) → failure
A form that auto-submits on blur → annoying and potentially broken
A date picker that requires a mouse click to open → failure (should allow keyboard or Tab to an input)

Quick tip: Check that every <input> has an associated <label>:

<!-- Good -->
<label for="email">Email</label>
<input type="email" id="email" />

<!-- Bad -->
<input type="email" placeholder="Email" />

Step 7: The Skip Link Test (1 minute)

This is the fastest test. Reload the page and press Tab immediately.

Does a skip link appear? Something like "Skip to main content"?

If yes, click it. Does it take you to the main content, skipping the navigation?

If no, that's a miss. You should have one. It takes 30 seconds to add.

Add a skip link:

<a href="#main-content" class="skip-link">Skip to main content</a>

<nav>
  <!-- navigation -->
</nav>

<main id="main-content">
  <!-- content -->
</main>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: white;
  padding: 8px;
  text-decoration: none;
}

.skip-link:focus {
  top: 0;
}

The Issues You'll Find (And How to Fix Them)

Issue 1: No Focus Indicator (Most Common)

Symptom: You Tab and can't see where focus is.

Cause: CSS has outline: none; or box-shadow: none;

Fix:

/* Remove this: */
outline: none;

/* Replace with visible focus (or don't remove it at all) */
:focus-visible {
  outline: 3px solid #0066ff;
  outline-offset: 2px;
}

Issue 2: Focus Getting Lost

Symptom: You Tab through a page, focus disappears somewhere in the middle.

Cause: JavaScript is setting focus to a hidden element, or z-index is hiding focus.

Fix: Use dev tools to inspect. Check if the focused element is hidden or has display: none. If it does, don't let focus go there. Add JavaScript to skip hidden elements:

element.addEventListener('focus', () => {
  if (element.style.display === 'none') {
    nextElement.focus();
  }
});

Issue 3: Tabindex Chaos

Symptom: You Tab and jump around the page in weird order (jumps to footer, back to header, etc.).

Cause: HTML has tabindex="2", tabindex="5", tabindex="1" in random order.

Fix: Delete all positive tabindex values. Use only tabindex="-1" (remove from tab order) or no tabindex at all. Let the browser handle order based on HTML structure.

<!-- ❌ Don't do this -->
<button tabindex="3">Third</button>
<button tabindex="1">First</button>
<button tabindex="2">Second</button>

<!-- ✅ Do this (leave out tabindex) -->
<button>First</button>
<button>Second</button>
<button>Third</button>

Issue 4: Modal Without Escape

Symptom: Modal opens, you Tab through buttons, but can't close with Escape.

Cause: Modal doesn't listen for Escape key.

Fix:

document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') {
    closeModal();
  }
});

Issue 5: Custom Interactive Element Without Keyboard Handler

Symptom: You Tab to a custom <div> that looks like a button, but Enter doesn't work.

Cause: It's missing keyboard event listeners.

Fix:

const customButton = document.querySelector('[role="button"]');

customButton.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    customButton.click();  // Trigger the click handler
  }
});

Or better: just use a real <button> element.

Issue 6: Hidden Focus Indicator

Symptom: Focus exists, but it's invisible (1px, same color as background, etc.).

Cause: CSS is too minimal or background color is the same.

Fix:

/* ❌ Invisible */
button:focus {
  outline: 1px solid #ccc;  /* Gray on gray = invisible */
}

/* ✅ Visible */
button:focus {
  outline: 3px solid #0066ff;  /* Blue on any background = visible */
  outline-offset: 2px;
}

The Audit Checklist (Your Quick Reference)

Print this. Use it. Update it as you find issues.

Keyboard Navigation Audit

[ ] Tab moves focus through the page in logical order
[ ] Focus indicator is visible on every element
[ ] Focus indicator has adequate contrast (3:1 minimum)
[ ] All buttons respond to Enter key
[ ] All toggles/checkboxes respond to Space key
[ ] Form can be filled entirely with keyboard
[ ] Modal closes with Escape key
[ ] Dropdown/menu navigable with Arrow keys
[ ] Skip link appears on Tab and works
[ ] Focus doesn't get lost in hidden elements
[ ] No positive tabindex values (chaos)
[ ] Custom interactive elements have full keyboard support

Things I Always Find Broken

After testing hundreds of sites, here's what I see constantly:

outline: none; without replacement — Most common. Developers remove outlines for aesthetics and forget to add focus styling.
Modal that doesn't close with Escape — Second most common. Looks polished, completely breaks keyboard users.
Tabindex all over the place — Someone tried to fix tab order with tabindex="2" and now it's a maze.
Icon-only buttons with no aria-label — Keyboard users can Tab to them, but don't know what they do.
Custom select dropdowns that don't use Arrow keys — Built with JavaScript, requires mouse or clicking.
Focus trap without escape in a modal — You get stuck. Only way out is Escape or clicking outside.

How to Document Your Findings

When you find issues, note them somewhere. Here's a simple template:

## Keyboard Navigation Test — [Date]

### Pass
- Focus indicators visible and clear
- Form submission works with keyboard
- Skip link present

### Fail
- Modal lacks Escape key handler (2026-04-06)
- Dropdown menu requires click to open (2026-04-06)

### Warnings
- Focus indicator very thin (meets minimum, could be stronger)

Share this with your team. It's quick, actionable, and non-judgmental.

The Real Value

Here's the thing about keyboard testing: it takes 20 minutes and catches issues that automated tools miss. A linter won't tell you that your focus trap is a pain to use. A scanner won't know that your custom dropdown is unusable without a mouse.

Your fingers will.

So grab your keyboard, put your mouse aside, and actually try to use your site the way millions of people do every day. You'll be shocked at what you find. And once you fix those issues, your site will work better for everyone—not just keyboard users.

Priya Nair is a frontend developer and accessibility advocate based in Amsterdam. She spends way too much time testing sites with just her keyboard and thinks you should too. Her favorite debugging tool is her Tab key.

ARIA Labels Done Wrong: The Most Common Mistakes I See in Production Code

Priya Nair — Thu, 09 Apr 2026 10:32:01 +0000

ARIA Labels Done Wrong: The Most Common Mistakes I See in Production Code

Meta: ARIA is powerful but dangerous when misused. Here are the 7 mistakes I see constantly—and how to fix them.

Keyword: ARIA labels accessibility mistakes common

Tags: #accessibility #aria #wcag #webdev #a11y

The Golden Rule of ARIA (And Why Most People Break It)

Before we talk about mistakes, let me say this clearly:

No ARIA is better than bad ARIA.

ARIA (Accessible Rich Internet Applications) is a powerful toolset for filling accessibility gaps. But when you use it wrong—and I mean really wrong—it makes things worse for screen reader users, not better.

I've audited hundreds of codebases. I'd estimate 70% of the ARIA I see is either unnecessary or broken. And when a screen reader user encounters broken ARIA, they don't get a degraded experience. They get a confusing one.

So here's the deal: I'm going to walk you through the most common mistakes I see, why they're problems, and how to fix them. By the end, you'll know when to use ARIA and when to just use HTML.

Mistake 1: aria-label on a Div Instead of Using Semantic HTML

This is the #1 mistake. By far.

The pattern: Someone needs a button. Instead of using <button>, they use a styled <div> and add aria-label.

Why it's wrong: A <div> is invisible to screen readers and keyboard navigation. No amount of ARIA can change that. You're building an accessibility shim on top of an inaccessible foundation.

Bad example:

<!-- ❌ This is broken, even with aria-label -->
<div 
  aria-label="Submit form" 
  class="button"
  onclick="submitForm()"
>
  Submit
</div>

<!-- What a screen reader hears: "Submit" (as text, not a button) -->
<!-- What keyboard users can do: Nothing (not focusable) -->

Good example:

<!-- ✅ Use semantic HTML -->
<button onclick="submitForm()">Submit</button>

<!-- OR if you need a link styled as a button: -->
<a href="/submit" role="button">Submit</a>

<!-- Screen reader: "Submit, button" -->
<!-- Keyboard: Focusable with Tab, activatable with Enter -->

Why it matters: Screen reader users need to know it's a button. Keyboard users need to be able to reach it with Tab and activate it with Enter or Space. A bare <div> does neither. ARIA's role="button" partially helps, but you still need to add keyboard listeners manually:

// If you insist on using a div (you shouldn't):
const fakeButton = document.querySelector('[role="button"]');

fakeButton.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    fakeButton.click();
  }
});

One-liner: Use <button>, <a>, <input> before you even think about aria-label.

Mistake 2: aria-label Duplicating Visible Text

This one wastes screen reader users' time.

The pattern: You have a button with visible text. You add aria-label with the same text.

Bad example:

<!-- ❌ Redundant -->
<button aria-label="Click to download file">
  Download
</button>

<!-- Screen reader: "Click to download file, button" (verbose, redundant) -->

Why it's wrong: If the button text is clear, you don't need aria-label. Screen readers already announce the text. You're just making them say it twice.

Good example:

<!-- ✅ Let the text speak for itself -->
<button>Download</button>

<!-- OR, if you need to clarify: -->
<button>Download Invoice PDF</button>

<!-- Screen reader: "Download Invoice PDF, button" (clear, not redundant) -->

When aria-label IS necessary: When you have an icon-only button (see Mistake 3).

One-liner: Don't use aria-label to repeat visible text. Use it to clarify invisible intent.

Mistake 3: Icon-Only Buttons Without aria-label (Or ARIA)

This is the flip side of Mistake 2. You have a button with only an icon. No text. No ARIA. Screen readers have no idea what it does.

Bad example:

<!-- ❌ Icon-only, no label -->
<button class="close-button">
  <i class="icon-x"></i>
</button>

<!-- Screen reader: "Button" (what button? who knows?) -->

<!-- ❌ Or worse: -->
<button class="hamburger">
  <svg viewBox="0 0 24 24" width="24" height="24">
    <line x1="3" y1="6" x2="21" y2="6" />
    <line x1="3" y1="12" x2="21" y2="12" />
    <line x1="3" y1="18" x2="21" y2="18" />
  </svg>
</button>

<!-- Screen reader: "Button" (again, meaningless) -->

Good example:

<!-- ✅ Icon + aria-label -->
<button aria-label="Close dialog" class="close-button">
  <i class="icon-x"></i>
</button>

<!-- Screen reader: "Close dialog, button" (clear) -->

<!-- ✅ Icon + aria-label + title (tooltip bonus) -->
<button aria-label="Open navigation menu" class="hamburger" title="Menu">
  <svg viewBox="0 0 24 24" width="24" height="24">
    <line x1="3" y1="6" x2="21" y2="6" />
    <line x1="3" y1="12" x2="21" y2="12" />
    <line x1="3" y1="18" x2="21" y2="18" />
  </svg>
</button>

<!-- Screen reader: "Open navigation menu, button" -->
<!-- Hover tooltip: "Menu" -->

Real-world checklist:

[ ] Is the button icon-only (no text)? If yes, add aria-label.
[ ] Does the aria-label describe what happens? If yes, you're good.
[ ] Do sighted users also understand? (Can't rely on icon alone.)

One-liner: Every icon-only button needs aria-label, aria-labelledby, or text inside the button.

Mistake 4: aria-labelledby Pointing to an ID That Doesn't Exist

This is a silent killer. No error. No warning. Just broken accessibility.

Bad example:

<!-- ❌ ID doesn't exist -->
<h2 id="form-title">Account Settings</h2>

<!-- Later... -->
<form aria-labelledby="nonexistent-id">  <!-- Wrong ID! -->
  <label>Email</label>
  <input type="email" />
</form>

<!-- Screen reader: "Form" (no context) -->

Good example:

<!-- ✅ ID exists and is used correctly -->
<h2 id="form-title">Account Settings</h2>

<form aria-labelledby="form-title">  <!-- Correct ID -->
  <label>Email</label>
  <input type="email" />
</form>

<!-- Screen reader: "Account Settings, form" (context clear) -->

How to debug: Open Chrome DevTools → Accessibility panel. It'll warn you if an ID is broken.

One-liner: Always check that the ID in aria-labelledby actually exists in your HTML.

Mistake 5: role="button" on a Div Without Keyboard Handling

This is the classic "I tried to fix it but didn't finish" pattern.

Bad example:

<!-- ❌ Has role, but no keyboard support -->
<div role="button" onclick="doSomething()">
  Click me
</div>

<!-- Screen reader: "Click me, button" (sounds accessible) -->
<!-- Keyboard user: Tabs right past it (not focusable) -->

Good example:

<!-- ✅ Full keyboard support -->
<div 
  role="button" 
  tabindex="0"  <!-- Make it focusable -->
  onclick="doSomething()"
  onkeydown="handleKeydown(event)"  <!-- Handle keyboard -->
>
  Click me
</div>

<script>
  function handleKeydown(event) {
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault();
      doSomething();
    }
  }
</script>

<!-- OR, even better: -->
<button onclick="doSomething()">Click me</button>

The real talk: If you're adding role="button", you're probably doing something wrong. You should be using a <button>. role="button" is for when you have a very good reason to not use HTML buttons (like custom styling that breaks them, which is rare).

One-liner: If you use role="button", you must also add tabindex="0" and keyboard event listeners. (But really, just use <button>.)

Mistake 6: Hiding Content With aria-hidden="true" That Users Can Still Reach

This one creates a horrible experience: keyboard users can reach an element, but screen readers can't see it.

Bad example:

<!-- ❌ aria-hidden but still focusable -->
<button aria-hidden="true" onclick="doSomething()">
  Hidden Action
</button>

<!-- Screen reader: Ignores the button entirely -->
<!-- Keyboard user: Tabs to it, tries to interact, gets confused -->

When this happens: Usually with decorative elements that accidentally got tabindex, or off-canvas menus that aren't fully hidden.

Good example:

<!-- ✅ Truly hidden: not visible, not focusable, not announced -->
<div 
  aria-hidden="true"
  style="display: none;"  <!-- Remove from document flow -->
>
  Decorative icon
</div>

<!-- ✅ OR: Off-canvas menu that's actually invisible -->
<nav 
  style="position: fixed; left: -300px;"  <!-- Off-screen -->
  aria-hidden="true"
>
  Menu items
</nav>

<!-- ✅ OR: Use visibility + aria-hidden for keyboard access but screen reader hiding -->
<div 
  style="visibility: hidden;"
  aria-hidden="true"
>
  Invisible to all users
</div>

Test: Inspect the element in DevTools. Is it visible? Is it focusable? If both are true but aria-hidden="true" is set, that's a problem.

One-liner: Only use aria-hidden="true" on elements that are actually invisible/non-interactive.

Mistake 7: Dynamic Content Updates Not Announced (Missing aria-live)

A screen reader user is on your page. New content loads via JavaScript. The screen reader has no idea. User keeps reading old content.

Bad example:

<!-- ❌ Content updates, but no announcement -->
<div id="notifications">
  <!-- Initially empty -->
</div>

<script>
  // New notification arrives
  const notification = document.createElement('div');
  notification.textContent = 'Order #12345 shipped!';
  document.getElementById('notifications').appendChild(notification);

  // Screen reader: *crickets* (no announcement)
</script>

Good example:

<!-- ✅ Content updates AND is announced -->
<div id="notifications" aria-live="polite" aria-atomic="true">
  <!-- Initially empty -->
</div>

<script>
  const notification = document.createElement('div');
  notification.textContent = 'Order #12345 shipped!';
  document.getElementById('notifications').appendChild(notification);

  // Screen reader: "Order #12345 shipped!" (announced immediately)
</script>

<!-- ✅ Or, for urgent updates: -->
<div id="alerts" aria-live="assertive" role="alert">
  <!-- Errors, warnings, urgent messages -->
</div>

<script>
  // This gets announced immediately, interrupting other content
  document.getElementById('alerts').textContent = 'Your session will expire in 2 minutes.';
</script>

aria-live options:

aria-live="polite" — Announce when convenient (after current speech)
aria-live="assertive" — Announce immediately (interrupts current speech)
role="alert" — Shorthand for aria-live="assertive" aria-atomic="true" (errors, warnings)
role="status" — Shorthand for aria-live="polite" aria-atomic="true" (status updates)

Real-world examples:

Form validation errors → use role="alert"
"Saved successfully" message → use role="status"
Real-time notifications → use aria-live="polite"

One-liner: If content loads dynamically, wrap it in aria-live so screen readers know it's there.

How to Test: Chrome DevTools

Here's the fastest way to catch most ARIA mistakes.

Open your site in Chrome.
Open DevTools (F12).
Go to Elements tab.
Right-click any element → Inspect accessibility properties.
Look at the Computed Name section.

What you're checking:

Does the element have a name? (If it's interactive, it should.)
Is the name what you intended? (Not "button" or blank.)
Are there warnings? (Red warning icon = problem.)

Example:

Element: <button>
Computed Name: "Submit"
Role: button
Warnings: None ✓

---

Element: <div role="button" aria-label="close">
Computed Name: "close"
Role: button
Warnings: None ✓

---

Element: <button aria-label="nonexistent-id">
Computed Name: (empty)
Role: button
Warnings: ⚠️ aria-labelledby points to non-existent element

Testing With a Real Screen Reader

If Chrome DevTools isn't enough, test with an actual screen reader.

On Mac: VoiceOver is built-in. Turn it on: System Preferences → Accessibility → VoiceOver. Press Ctrl+Option+U to start.

On Windows: NVDA is free. Download from nvaccess.org.

Listen for:

Does the button announcement sound right? (Not just "button," but "submit button" or "close dialog"?)
Can you navigate to all interactive elements?
Do new notifications get announced?

It takes 10 minutes to learn the basics. Highly worth it.

The Quick Fix Checklist

Running through a codebase? Use this:

[ ] No <div role="button"> without tabindex="0" and keyboard handlers
[ ] Every aria-label / aria-labelledby has a real target
[ ] Icon-only buttons have aria-label or text
[ ] No aria-hidden="true" on focusable elements
[ ] Dynamic content has aria-live or role="alert" / role="status"
[ ] ARIA attributes only add information, not replace semantic HTML
[ ] Form fields have associated <label> elements

ARIA Violations I See Most

After auditing 200+ projects:

aria-label duplicating text (70% of aria-label misuse)
role="button" without keyboard (30% of role misuse)
aria-hidden hiding interactive content (25% of aria-hidden issues)
Missing aria-live on dynamic updates (50% of single-page apps)
aria-labelledby pointing to nothing (15% of aria-labelledby)

The Real Rule

Here's how to think about ARIA:

ARIA is for semantics and live regions. Not for fixing broken HTML.

If you're tempted to use ARIA, ask yourself first:

Is there a semantic HTML element that does this? (Usually yes.)
Is the content actually hidden/dynamic? (If not, probably doesn't need ARIA.)
Are screen reader users getting accurate information? (Test it.)

Most of the time, better HTML solves the problem faster than ARIA ever could.

Resources (All Free, Official)

MDN ARIA documentation — developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
WAI-ARIA Authoring Practices Guide — w3.org/WAI/ARIA/apg
ARIA in HTML Spec — w3.org/TR/html-aria

These aren't light reading, but they're authoritative. Bookmark them.

The Closing Truth

ARIA is a powerful tool for bridging the gap between modern web apps and assistive technology. But it's a tool for filling gaps, not building on nothing.

Master semantic HTML first. Learn ARIA second. Test with actual screen readers third.

When you do that, you'll stop making these mistakes. And your sites will work better for everyone.

Priya Nair is a frontend developer based in Amsterdam who is genuinely tired of seeing broken ARIA in production. She tests with screen readers regularly and believes that if a feature needs ARIA to work, you probably should have built it differently. When not debugging ARIA, she advocates for better HTML.

ARIA Labels Done Wrong: The Most Common Mistakes I See in Production Code

Priya Nair — Wed, 08 Apr 2026 20:19:59 +0000

ARIA Labels Done Wrong: The Most Common Mistakes I See in Production Code

Meta: ARIA is powerful but dangerous when misused. Here are the 7 mistakes I see constantly—and how to fix them.

Keyword: ARIA labels accessibility mistakes common

Tags: #accessibility #aria #wcag #webdev #a11y

The Golden Rule of ARIA (And Why Most People Break It)

Before we talk about mistakes, let me say this clearly:

No ARIA is better than bad ARIA.

So here's the deal: I'm going to walk you through the most common mistakes I see, why they're problems, and how to fix them. By the end, you'll know when to use ARIA and when to just use HTML.

Mistake 1: aria-label on a Div Instead of Using Semantic HTML

This is the #1 mistake. By far.

The pattern: Someone needs a button. Instead of using <button>, they use a styled <div> and add aria-label.

Why it's wrong: A <div> is invisible to screen readers and keyboard navigation. No amount of ARIA can change that. You're building an accessibility shim on top of an inaccessible foundation.

Bad example:

<!-- ❌ This is broken, even with aria-label -->
<div 
  aria-label="Submit form" 
  class="button"
  onclick="submitForm()"
>
  Submit
</div>

<!-- What a screen reader hears: "Submit" (as text, not a button) -->
<!-- What keyboard users can do: Nothing (not focusable) -->

Good example:

<!-- ✅ Use semantic HTML -->
<button onclick="submitForm()">Submit</button>

<!-- OR if you need a link styled as a button: -->
<a href="/submit" role="button">Submit</a>

<!-- Screen reader: "Submit, button" -->
<!-- Keyboard: Focusable with Tab, activatable with Enter -->

// If you insist on using a div (you shouldn't):
const fakeButton = document.querySelector('[role="button"]');

fakeButton.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    fakeButton.click();
  }
});

One-liner: Use <button>, <a>, <input> before you even think about aria-label.

Mistake 2: aria-label Duplicating Visible Text

This one wastes screen reader users' time.

The pattern: You have a button with visible text. You add aria-label with the same text.

Bad example:

<!-- ❌ Redundant -->
<button aria-label="Click to download file">
  Download
</button>

<!-- Screen reader: "Click to download file, button" (verbose, redundant) -->

Why it's wrong: If the button text is clear, you don't need aria-label. Screen readers already announce the text. You're just making them say it twice.

Good example:

<!-- ✅ Let the text speak for itself -->
<button>Download</button>

<!-- OR, if you need to clarify: -->
<button>Download Invoice PDF</button>

<!-- Screen reader: "Download Invoice PDF, button" (clear, not redundant) -->

When aria-label IS necessary: When you have an icon-only button (see Mistake 3).

One-liner: Don't use aria-label to repeat visible text. Use it to clarify invisible intent.

Mistake 3: Icon-Only Buttons Without aria-label (Or ARIA)

This is the flip side of Mistake 2. You have a button with only an icon. No text. No ARIA. Screen readers have no idea what it does.

Bad example:

<!-- ❌ Icon-only, no label -->
<button class="close-button">
  <i class="icon-x"></i>
</button>

<!-- Screen reader: "Button" (what button? who knows?) -->

<!-- ❌ Or worse: -->
<button class="hamburger">
  <svg viewBox="0 0 24 24" width="24" height="24">
    <line x1="3" y1="6" x2="21" y2="6" />
    <line x1="3" y1="12" x2="21" y2="12" />
    <line x1="3" y1="18" x2="21" y2="18" />
  </svg>
</button>

<!-- Screen reader: "Button" (again, meaningless) -->

Good example:

<!-- ✅ Icon + aria-label -->
<button aria-label="Close dialog" class="close-button">
  <i class="icon-x"></i>
</button>

<!-- Screen reader: "Close dialog, button" (clear) -->

<!-- ✅ Icon + aria-label + title (tooltip bonus) -->
<button aria-label="Open navigation menu" class="hamburger" title="Menu">
  <svg viewBox="0 0 24 24" width="24" height="24">
    <line x1="3" y1="6" x2="21" y2="6" />
    <line x1="3" y1="12" x2="21" y2="12" />
    <line x1="3" y1="18" x2="21" y2="18" />
  </svg>
</button>

<!-- Screen reader: "Open navigation menu, button" -->
<!-- Hover tooltip: "Menu" -->

Real-world checklist:

[ ] Is the button icon-only (no text)? If yes, add aria-label.
[ ] Does the aria-label describe what happens? If yes, you're good.
[ ] Do sighted users also understand? (Can't rely on icon alone.)

One-liner: Every icon-only button needs aria-label, aria-labelledby, or text inside the button.

Mistake 4: aria-labelledby Pointing to an ID That Doesn't Exist

This is a silent killer. No error. No warning. Just broken accessibility.

Bad example:

<!-- ❌ ID doesn't exist -->
<h2 id="form-title">Account Settings</h2>

<!-- Later... -->
<form aria-labelledby="nonexistent-id">  <!-- Wrong ID! -->
  <label>Email</label>
  <input type="email" />
</form>

<!-- Screen reader: "Form" (no context) -->

Good example:

<!-- ✅ ID exists and is used correctly -->
<h2 id="form-title">Account Settings</h2>

<form aria-labelledby="form-title">  <!-- Correct ID -->
  <label>Email</label>
  <input type="email" />
</form>

<!-- Screen reader: "Account Settings, form" (context clear) -->

How to debug: Open Chrome DevTools → Accessibility panel. It'll warn you if an ID is broken.

One-liner: Always check that the ID in aria-labelledby actually exists in your HTML.

Mistake 5: role="button" on a Div Without Keyboard Handling

This is the classic "I tried to fix it but didn't finish" pattern.

Bad example:

<!-- ❌ Has role, but no keyboard support -->
<div role="button" onclick="doSomething()">
  Click me
</div>

<!-- Screen reader: "Click me, button" (sounds accessible) -->
<!-- Keyboard user: Tabs right past it (not focusable) -->

Good example:

<!-- ✅ Full keyboard support -->
<div 
  role="button" 
  tabindex="0"  <!-- Make it focusable -->
  onclick="doSomething()"
  onkeydown="handleKeydown(event)"  <!-- Handle keyboard -->
>
  Click me
</div>

<script>
  function handleKeydown(event) {
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault();
      doSomething();
    }
  }
</script>

<!-- OR, even better: -->
<button onclick="doSomething()">Click me</button>

One-liner: If you use role="button", you must also add tabindex="0" and keyboard event listeners. (But really, just use <button>.)

Mistake 6: Hiding Content With aria-hidden="true" That Users Can Still Reach

This one creates a horrible experience: keyboard users can reach an element, but screen readers can't see it.

Bad example:

<!-- ❌ aria-hidden but still focusable -->
<button aria-hidden="true" onclick="doSomething()">
  Hidden Action
</button>

<!-- Screen reader: Ignores the button entirely -->
<!-- Keyboard user: Tabs to it, tries to interact, gets confused -->

When this happens: Usually with decorative elements that accidentally got tabindex, or off-canvas menus that aren't fully hidden.

Good example:

<!-- ✅ Truly hidden: not visible, not focusable, not announced -->
<div 
  aria-hidden="true"
  style="display: none;"  <!-- Remove from document flow -->
>
  Decorative icon
</div>

<!-- ✅ OR: Off-canvas menu that's actually invisible -->
<nav 
  style="position: fixed; left: -300px;"  <!-- Off-screen -->
  aria-hidden="true"
>
  Menu items
</nav>

<!-- ✅ OR: Use visibility + aria-hidden for keyboard access but screen reader hiding -->
<div 
  style="visibility: hidden;"
  aria-hidden="true"
>
  Invisible to all users
</div>

Test: Inspect the element in DevTools. Is it visible? Is it focusable? If both are true but aria-hidden="true" is set, that's a problem.

One-liner: Only use aria-hidden="true" on elements that are actually invisible/non-interactive.

Mistake 7: Dynamic Content Updates Not Announced (Missing aria-live)

A screen reader user is on your page. New content loads via JavaScript. The screen reader has no idea. User keeps reading old content.

Bad example:

<!-- ❌ Content updates, but no announcement -->
<div id="notifications">
  <!-- Initially empty -->
</div>

<script>
  // New notification arrives
  const notification = document.createElement('div');
  notification.textContent = 'Order #12345 shipped!';
  document.getElementById('notifications').appendChild(notification);

  // Screen reader: *crickets* (no announcement)
</script>

Good example:

<!-- ✅ Content updates AND is announced -->
<div id="notifications" aria-live="polite" aria-atomic="true">
  <!-- Initially empty -->
</div>

<script>
  const notification = document.createElement('div');
  notification.textContent = 'Order #12345 shipped!';
  document.getElementById('notifications').appendChild(notification);

  // Screen reader: "Order #12345 shipped!" (announced immediately)
</script>

<!-- ✅ Or, for urgent updates: -->
<div id="alerts" aria-live="assertive" role="alert">
  <!-- Errors, warnings, urgent messages -->
</div>

<script>
  // This gets announced immediately, interrupting other content
  document.getElementById('alerts').textContent = 'Your session will expire in 2 minutes.';
</script>

aria-live options:

aria-live="polite" — Announce when convenient (after current speech)
aria-live="assertive" — Announce immediately (interrupts current speech)
role="alert" — Shorthand for aria-live="assertive" aria-atomic="true" (errors, warnings)
role="status" — Shorthand for aria-live="polite" aria-atomic="true" (status updates)

Real-world examples:

Form validation errors → use role="alert"
"Saved successfully" message → use role="status"
Real-time notifications → use aria-live="polite"

One-liner: If content loads dynamically, wrap it in aria-live so screen readers know it's there.

How to Test: Chrome DevTools

Here's the fastest way to catch most ARIA mistakes.

Open your site in Chrome.
Open DevTools (F12).
Go to Elements tab.
Right-click any element → Inspect accessibility properties.
Look at the Computed Name section.

What you're checking:

Does the element have a name? (If it's interactive, it should.)
Is the name what you intended? (Not "button" or blank.)
Are there warnings? (Red warning icon = problem.)

Example:

Element: <button>
Computed Name: "Submit"
Role: button
Warnings: None ✓

---

Element: <div role="button" aria-label="close">
Computed Name: "close"
Role: button
Warnings: None ✓

---

Element: <button aria-label="nonexistent-id">
Computed Name: (empty)
Role: button
Warnings: ⚠️ aria-labelledby points to non-existent element

Testing With a Real Screen Reader

If Chrome DevTools isn't enough, test with an actual screen reader.

On Mac: VoiceOver is built-in. Turn it on: System Preferences → Accessibility → VoiceOver. Press Ctrl+Option+U to start.

On Windows: NVDA is free. Download from nvaccess.org.

Listen for:

Does the button announcement sound right? (Not just "button," but "submit button" or "close dialog"?)
Can you navigate to all interactive elements?
Do new notifications get announced?

It takes 10 minutes to learn the basics. Highly worth it.

The Quick Fix Checklist

Running through a codebase? Use this:

[ ] No <div role="button"> without tabindex="0" and keyboard handlers
[ ] Every aria-label / aria-labelledby has a real target
[ ] Icon-only buttons have aria-label or text
[ ] No aria-hidden="true" on focusable elements
[ ] Dynamic content has aria-live or role="alert" / role="status"
[ ] ARIA attributes only add information, not replace semantic HTML
[ ] Form fields have associated <label> elements

ARIA Violations I See Most

After auditing 200+ projects:

aria-label duplicating text (70% of aria-label misuse)
role="button" without keyboard (30% of role misuse)
aria-hidden hiding interactive content (25% of aria-hidden issues)
Missing aria-live on dynamic updates (50% of single-page apps)
aria-labelledby pointing to nothing (15% of aria-labelledby)

The Real Rule

Here's how to think about ARIA:

ARIA is for semantics and live regions. Not for fixing broken HTML.

If you're tempted to use ARIA, ask yourself first:

Is there a semantic HTML element that does this? (Usually yes.)
Is the content actually hidden/dynamic? (If not, probably doesn't need ARIA.)
Are screen reader users getting accurate information? (Test it.)

Most of the time, better HTML solves the problem faster than ARIA ever could.

Resources (All Free, Official)

MDN ARIA documentation — developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
WAI-ARIA Authoring Practices Guide — w3.org/WAI/ARIA/apg
ARIA in HTML Spec — w3.org/TR/html-aria

These aren't light reading, but they're authoritative. Bookmark them.

The Closing Truth

ARIA is a powerful tool for bridging the gap between modern web apps and assistive technology. But it's a tool for filling gaps, not building on nothing.

Master semantic HTML first. Learn ARIA second. Test with actual screen readers third.

When you do that, you'll stop making these mistakes. And your sites will work better for everyone.

I Audited My Own Portfolio for WCAG 2.2 — Here's What I Found in 30 Minutes

Priya Nair — Wed, 08 Apr 2026 20:15:21 +0000

I Audited My Own Portfolio for WCAG 2.2 — Here's What I Found in 30 Minutes

Meta: I audited my portfolio for WCAG 2.2 and found six critical accessibility issues I'd been ignoring. Here's how to find them in yours.

Keyword: WCAG 2.2 audit checklist developer

Tags: #accessibility #webdev #wcag #frontend

The Moment I Realized I Was Part of the Problem

Last week, I was reviewing accessibility best practices for a client project when it hit me: I haven't formally audited my own portfolio in years. You know, the one I show to potential clients when I talk about how much I care about inclusive design.

Oof.

So I decided to do something radical—actually practice what I preach. I set a timer for 30 minutes, grabbed a couple of free tools, and started poking around. What I found was both humbling and, frankly, pretty typical. And that's exactly why I'm writing this.

The web is broken for accessibility. The WebAIM Million 2025 report shows that 95.9% of websites fail basic WCAG checks. Ninety-five point nine percent. That's not bad luck. That's us. Developers. We did this. Usually without meaning to, usually while thinking about 47 other things, but we did it.

Here's the good news: we can also fix it. And if the EU's Accessibility Act (EAA) being enforced as of June 2025 isn't motivation enough, maybe knowing that your actual users—whether they're blind, colorblind, using only a keyboard, or just on a tiny mobile screen in bad sunlight—will actually be able to use your site, is.

Let me walk you through what I found, how I found it, and how to fix it.

The Tools (All Free, All Good)

Before we dig in, let me be clear: you don't need expensive software.

axe DevTools (browser extension, free) — This is my workhorse. It runs automated accessibility scans and flags issues with severity and WCAG criteria. Chrome, Firefox, Edge. Get it.

WAVE (browser extension, free) — Shows you a visual representation of content structure, labels, and warnings. Slightly different angle than axe, so both are worth running.

Chrome DevTools — Accessibility Tree (built in, free) — Under DevTools → Elements → Accessibility, you can see how your page is parsed by assistive technology. This is eye-opening.

Keyboard testing (your keyboard, free) — Press Tab. See what happens. Try to navigate your entire page without touching the mouse. This matters more than any tool.

That's it. Ten minutes to set up. Let's go.

What I Found: Six Things That Made Me Wince

1. Missing and Terrible Alt Text on Images

The issue: I had a gorgeous hero image on my portfolio landing page. Beautiful. Completely undescribed.

<!-- ❌ What I had -->
<img src="portfolio-hero.jpg" />

<!-- ✅ What I should have -->
<img 
  src="portfolio-hero.jpg" 
  alt="Portfolio website displaying three web design projects with dark theme and gradient accents"
/>

What it means for real users: Blind users get nothing. Screen readers say "image" and move on. Image broken or slow to load? Sighted users see the broken image icon. Blind users see nothing—they don't even know there was supposed to be content there.

The fix: Write alt text that describes the content and purpose of the image. Not poetic. Not alt="beautiful sunset". Useful. What does this image do on your page? If it's decorative, use alt="".

2. Insufficient Color Contrast (The Sneaky One)

My design had a really slick dark gray text on a slightly darker gray background. Very trendy. Very unreadable if you have low vision, color blindness, or are just squinting at your phone in daylight.

axe flagged it: 3.2:1 contrast ratio. WCAG AA requires 4.5:1 for normal text, 3:1 for large text (18px+ or 14px bold+).

/* ❌ What I had (3.2:1 - FAIL) */
.post-date {
  color: #666666;
  background: #1a1a1a;
  font-size: 14px;
}

/* ✅ What I fixed (4.8:1 - PASS) */
.post-date {
  color: #cccccc;
  background: #1a1a1a;
  font-size: 14px;
}

Quick way to check: Use the WebAIM contrast checker (free, no login). Paste your hex codes, see your ratio. Aim for 4.5:1 unless your text is genuinely big.

3. Focus Indicators (The Invisible Tab)

I had removed the default browser focus outline on links because it "looked ugly." Instead, I'd added a subtle :hover effect. Very pretty. Very broken if you only use keyboard.

Someone using a keyboard to navigate my site would Tab onto a link and... see nothing change visually. Where am I? Did that work? Panic.

/* ❌ What I had */
a {
  outline: none; /* THE SIN */
}

a:hover {
  color: #0066ff;
}

/* ✅ What I fixed */
a:focus-visible {
  outline: 3px solid #0066ff;
  outline-offset: 2px;
}

a:hover {
  color: #0066ff;
}

The rule: Never remove the default focus outline without replacing it. :focus-visible is your friend—it shows the outline when using keyboard, but not when clicking with a mouse. Best of both worlds.

4. Unlabelled Form Inputs (The Invisible Ask)

I have a contact form. The form had inputs, but they were only labeled visually—the HTML had no <label> elements.

<!-- ❌ What I had -->
<input type="email" placeholder="Your email" />

<!-- ✅ What I should have -->
<label for="contact-email">Email address</label>
<input type="email" id="contact-email" placeholder="Your email" />

Why this matters: A screen reader user reaches the input field and hears... nothing. They don't know what the field is for. The placeholder disappears when they type. Without a label, they're flying blind.

Even better: If you want to visually hide the label (for design reasons), use CSS:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

<label for="contact-email" class="sr-only">Email address</label>
<input type="email" id="contact-email" placeholder="Your email" />

The label is there for assistive tech. The visual design is unchanged.

5. Keyboard Navigation Trap in My Project Modal

I have a modal that displays project details. You Tab through the form, but when you reach the last button, Tab wraps back to the first button inside the modal—you can't escape without clicking outside or pressing Escape.

This is called focus trap without escape, and it's particularly bad if you're keyboard-only.

// ✅ Simple fix: Handle Tab in the last focusable element
const lastButton = document.querySelector('.modal .btn-close');

lastButton.addEventListener('keydown', (e) => {
  if (e.key === 'Tab' && !e.shiftKey) {
    e.preventDefault();
    document.querySelector('.modal .btn-primary').focus();
  }
});

// OR, better: Use a proper focus trap library behavior
// But here's the core idea—don't trap users in a modal without a clear exit.

Real talk: The best fix is making sure your modal can be closed with Escape (which browsers often handle automatically), and that focus moves back to the trigger element when the modal closes.

6. No Skip Navigation Link

This is the one that made me laugh at myself. I preach about skip links, and mine had zero.

A skip link is a link at the very start of your HTML that says "Skip to main content." It's hidden by default, but visible when you Tab to it. For keyboard-only users, this saves them from Tabbing through your entire navigation menu every single page.

<a href="#main-content" class="skip-link">Skip to main content</a>

<nav>
  <!-- navigation stuff -->
</nav>

<main id="main-content">
  <!-- your actual content -->
</main>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: white;
  padding: 8px;
  text-decoration: none;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}

When you Tab onto it, it slides into view. Click it, and you jump straight to #main-content. Keyboard users say a silent thank you.

WCAG 2.2: What's New and What I Hit

WCAG 2.2 added 9 new criteria in October 2023. I triggered at least two:

Focus Appearance (2.4.13) — That focus indicator I removed? That's criterion 2.4.13. WCAG now demands a visible focus indicator with at least 3:1 contrast against adjacent colors.

Target Size (2.5.8) — Interactive elements should be at least 24px × 24px (or 24px of spacing between them). My social media icons in the footer were 16px. Easy miss. Easy fix.

Both are WCAG AA level. Both are things I didn't know about when I started, but both are important because they make the web usable for more people.

Your Quick-Start Checklist: 10 Minutes

If you only read this far, here's what to do right now:

Install axe DevTools, open your site, run the scan. Note the failures.
Check all images. Does each <img> have useful alt text? (Not alt="image", actual description.)
Test with Tab only. Close your trackpad. Can you navigate your entire site with Tab and Enter? Is focus always visible?
Check form labels. Every input should have a <label> with a matching for attribute.
Test color contrast. Pick your key text colors. Run them through WebAIM's contrast checker. Aim for 4.5:1.

That's it. Thirty minutes, max.

The Thing About Being a Developer Who Cares

I think we fail accessibility not because we're careless, but because the defaults are broken. The web platform doesn't make inclusive design automatic. You have to opt in.

But once you see it—once you understand that real humans depend on this stuff—it becomes harder to ignore. And the good news is that it's not hard. It's just... intentional.

I fixed my six issues in an afternoon. My portfolio loads faster, is more usable for everyone, and I can talk to clients with actual credibility now.

You can too.

Priya Nair is a frontend developer based in Amsterdam. She writes about accessibility, inclusive design, and the occasional CSS rabbit hole. When she's not auditing her own code, you'll find her advocating for the web that works for everyone.