DEV Community: Priya Nair

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.