DEV Community: Priya Nair

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.

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.

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.