web development Archives /Tag

Why ARIA Alone Won’t Fix Your Website’s Accessibility
ARIA (Accessible Rich Internet Applications) has become a mainstay in modern front-end work, giving us a way to make complex interfaces more usable for people relying on assistive tech. But here’s the catch: despite how widely it’s used now, accessibility issues on the web haven’t actually gone down. In fact, reports like the annual WebAIM Million consistently show that pages using ARIA often rack up more accessibility errors than those that don’t. That’s a red flag—and it raises an important question: if ARIA is meant to improve accessibility, why does more ARIA so often lead to worse outcomes?

What ARIA Is—and What It’s Supposed to Do

At its core, ARIA is just a spec for adding semantic meaning where HTML alone doesn’t cut it. When we build custom UI components—think tab lists, modals, or live regions—ARIA roles and attributes tell screen readers what those elements are, how they behave, and when their state changes.

For example, aria-live lets us announce new content to screen readers without forcing a page reload. aria-label gives an accessible name to elements that don’t have visible text. Using role="tablist" clarifies the relationship between grouped tab controls. When used correctly, these attributes bridge the gap between how something looks visually and how it’s experienced non-visually.

When Is It Necessary?

There are valid cases where ARIA is the right tool—like custom widgets that don’t exist in native HTML, dynamic content that needs to be announced, or modal dialogs that require managing focus. In these edge cases, it can give essential context to assistive tech users. The trick is restraint: only reach for ARIA when HTML alone can’t deliver the behavior you need.

Why It Shouldn’t Be the Default Tool

The W3C’s first rule of ARIA is dead simple: “Don’t use ARIA if you can use native HTML.” There’s a reason for that. Semantic elements like <button>, <nav>, and <input> come with baked-in keyboard support, focus behavior, and screen reader semantics.

Replacing these with <div>s or <span>s and trying to patch on ARIA roles is a recipe for trouble. It adds complexity we have to maintain, and it increases the cognitive load on assistive tech users, who now have to deal with custom keyboard logic or missing states that native elements would have handled out of the box.

Common ARIA Misuse That Breaks Accessibility

Misusing ARIA is the fastest way to make things worse. Some of the most common mistakes we see:
- Redundant ARIA: e.g. adding role="button" on a native <button>, which can confuse announcements.
- Incorrect roles or attributes: like using aria-checked on something that’s not checkable.
- Static ARIA states: setting aria-expanded="true" and never updating it when the element collapses.
- Overriding native behavior : trapping focus or breaking expected tab order.
- Misused aria-hidden: This one’s especially nasty. It hides content from assistive tech, which is fine for decorative icons or offscreen helper text. But if you throw it on meaningful content like links or form controls, it removes them from the accessibility tree entirely. That creates “empty” focusable elements and violates the rule that aria-hidden="true" must never be on focusable items.
Take a link that only has an SVG icon with aria-hidden="true". Visually it looks fine, but to a screen reader, it’s just an empty link with no name. Compare that to a native <button> with either visible text or an aria-label—it automatically conveys its purpose. Misusing it like this doesn’t just fail to help; it strips meaning away.

Why ARIA Usage Correlates with More Errors

The WebAIM Million keeps showing the same trend: pages with ARIA average almost twice as many detectable errors as those without. That doesn’t mean ARIA is inherently bad—it means it’s often used wrong.

Here’s why that happens so often:
- More moving parts: Every ARIA attribute is another thing that has to stay in sync as the UI changes.
- Misunderstood implementation: Developers sometimes add it without fully understanding how screen readers will interpret it. For instance, putting aria-hidden on a logo or nav link effectively removes it from the experience for assistive tech users.
- No real testing: There’s a tendency to assume that if ARIA is present, accessibility is solved. Without testing, it’s easy to miss that it’s actually broken.
The Real Fix: Manual Testing and Developer Discipline

Automated tools are useful for catching low-hanging fruit like missing alt text, color contrast issues, or syntax errors. But they can’t tell you if your ARIA actually works. They’ll detect if aria-expanded is present—but not if it updates correctly when toggled.

Same thing with aria-hidden: they’ll warn you that it’s there, but not if you used it correctly. Maybe the hidden element is decorative (fine) or maybe it’s essential (not fine). Only a human can tell. Most ARIA issues are about behavior and context, which tools can’t judge.

Testing It in the Real World

To know your ARIA implementation works, you’ve got to test it like real users would:
- Keyboard-only navigation: Make sure everything interactive is reachable by tab, focus order makes sense, and keys like Enter, Space, and Arrow keys behave as expected.
- Screen reader testing: Try NVDA on Windows, VoiceOver on macOS, or JAWS if you’re in enterprise. Confirm that roles, labels, and states are being announced correctly—and that hidden content stays hidden without killing important info.
- User testing: If possible, bring in assistive tech users or trained accessibility testers to see how your UI holds up in practice.
Doing this builds confidence that your ARIA-enhanced components are actually usable.

Build a Feedback Loop Into the Dev Process

Accessibility shouldn’t be a post-launch patch job. Bake it into your development flow. Do accessibility checks during code reviews, QA, and design iterations. When you add ARIA, document the behavior you expect, and get feedback from teammates or AT users to verify it works.

Practical Guidelines for Responsible ARIA Use

If you want to use it safely, stick to a few core habits:
- Follow the WAI-ARIA Authoring Practices (APG): They provide vetted patterns and working code examples.
- Use ARIA only when you have to: Lean on semantic HTML first, and treat it as a fallback.
- Test thoroughly: Validate behavior with keyboard and screen readers, not just automated checkers.
- Review aria-hidden usage carefully: Only hide decorative or duplicate content. Never hide focusable items, form controls, or nav links.
- Document your decisions: Leave comments or README notes explaining why it was added and how it’s supposed to work.
- Make accessibility a team effort: It’s not just the job of one dev or QA engineer. Everyone owns it.
ARIA Isn’t a Shortcut—It’s a Responsibility

ARIA is powerful, but it’s not magic. Used carelessly, it creates new barriers and frustrates the very people it’s meant to support. Used deliberately—with a “native first” mindset, real testing, and team buy-in—it can make complex interfaces accessible without breaking usability.

Respect ARIA’s complexity, but don’t fear it. Real accessibility comes from thoughtful use of semantic HTML, strategic ARIA when it’s actually needed, and consistent real-world testing.

If you want to level up your accessibility practices and cut risk, 216digital offers ADA briefings built specifically for dev teams. Schedule one today and start building better, more inclusive code.
Greg McNeil

September 12, 2025

How-to Guides, Legal Compliance

Accessibility, ARIA, keyboard accessibility, WCAG, web developers, web development, Website Accessibility
Shift Happens—But Not On Focus
You press Tab into the first field of a form, and suddenly the page submits. Or you click into a dropdown and, without warning, a new window pops up. Frustrating, right? Now imagine how much more disruptive that is for someone who relies on a screen reader or uses only a keyboard. Sudden shifts don’t just annoy—they break concentration, cause errors, and force users to start over.

That’s the purpose of WCAG’s Success Criterion 3.2.1 On Focus. It makes sure that receiving focus doesn’t trigger unexpected changes. In short: don’t move the user, reload a page, or submit a form just because something got focus. Users should always stay in control.

In this article, we’ll unpack SC 3.2.1, look at common pitfalls, explore best practices, and share testing strategies so your site feels consistent, trustworthy, and usable.

Understanding Success Criterion 3.2.1 – On Focus

The official wording says: When any user interface component receives focus, it does not initiate a change of context.

What this really means is that putting focus on an element—whether by tabbing, shift-tabbing, or clicking—should not be treated as an automatic “go” button.

A change of context includes things like:
- Submitting a form when a field receives focus
- Opening a modal or new window on focus
- Navigating to a new page when a menu item gains focus
- Programmatically moving focus somewhere else the moment you land on an element
This rule is designed to stop those surprises. Changes should only happen when users take action—pressing Enter, clicking a button, or making a choice—not just by landing on something.

Why On Focus Matters

Predictable focus builds trust. Users know where they are, what’s happening, and how to move forward without being thrown off track.

For users with cognitive or visual disabilities, avoiding sudden shifts prevents confusion. For those navigating with a keyboard, a smooth and logical tab order makes it possible to move efficiently through content. Screen readers also benefit from a stable focus path, since consistency allows the technology to announce content clearly. And people with motor impairments are spared the frustration of accidentally triggering submissions or navigations they didn’t intend.

But accessibility isn’t just about a specific group. Predictability benefits everyone. Consistent behavior builds trust and lowers friction, making your site feel polished and respectful of users’ time and effort.

Common Pitfalls (and Why They Break On Focus)

Despite the clear intent of SC 3.2.1, developers often run into familiar traps. A few of the most common include:
- Auto actions on focus: Submitting a form, opening a modal, or swapping pages the instant an input or link gets focus.
- Focus jumps: Using scripts that automatically call element.focus() on load or on focus, dragging the user to an unexpected spot.
- Navigation on focus: Menus that redirect as soon as an item is focused, rather than waiting for activation.
- Broken tab order: Overuse of tabindex—especially with values greater than 0—can create confusing and illogical navigation paths.
- Inconsistent patterns: Mixing models, where some elements act on focus while others require activation, leads to unnecessary confusion.
All of these problems do the same thing: they break user flow, create confusion, and increase errors.

How to Achieve Compliance (and Design a Better Experience)

Preventing these issues comes down to designing focus behavior intentionally and sticking to a few reliable practices.

From there, keep a few best practices in mind:
- Be thoughtful with focus management. If you use element.focus(), do it to genuinely help the user (for example, moving focus into an opened dialog) and respect lifecycle rules.
- Preserve the natural tab order whenever possible. Use tabindex="0" only when necessary to include custom controls, and avoid positive values.
- Be cautious with ARIA. Roles like menu, menuitem, tab, and dialog come with built-in interaction expectations. If you implement them, follow the complete pattern—or stick with native controls.
- Keep patterns consistent. Buttons should submit, links should navigate, and tabs should switch panels only when activated. Uniformity across components builds confidence.
Small details make a big difference. For example, always include a “Skip to main content” link that becomes visible on focus, and ensure it works correctly by pointing to a landmark or an element with tabindex="-1". Likewise, don’t rely on hover or color changes alone to signal interactivity; provide clear focus styles that work for both keyboard and touch users.

Testing Strategies for On Focus

Testing is where theory meets practice. A few methods will quickly reveal whether your site is compliant:

Manual testing
- Tab through every interactive element. Nothing should submit, navigate, or open on focus alone.
- Shift+Tab backward to confirm the reverse path is just as stable.
- Use Enter or Space to activate controls—only then should real actions occur.
- In DevTools, run document.querySelector('#el').focus() and verify that no context change happens.
Assistive Technology Testing

Screen readers like NVDA (Windows) and VoiceOver (macOS/iOS) are essential. Navigate with Tab, rotor, and quick keys to check that focus remains predictable. On mobile, connect an external keyboard and confirm the behavior is consistent with desktop experiences.

Automated Checks

Tools such as Google Lighthouse or WAVE can flag tabindex issues, missing roles, or poor focus order. Automation won’t catch the “surprise factor.” Always back it up with manual and assistive tech testing.

Bad vs. Good: Concrete Examples

Bad: Form Submits on Focus
```
<form action="/submit" method="post">
  <label for="name">Name:</label>
  <input id="name" type="text" onfocus="this.form.submit()">
</form>
```
Issue: The form submits as soon as the field gains focus—a clear violation.

Good: Form Submits Only on Activation
```
<form action="/submit" method="post">
  <label for="name">Name:</label>
  <input id="name" type="text">
  <button type="submit">Submit</button>
</form>
```
Fix: The form submits only when the user explicitly activates the button.

Bad: Navigation on Focus
```
<nav>
  <a href="/pricing" onfocus="window.location=this.href">Pricing</a>
</nav>
```
Good: Navigation Only on Activation
```
<nav>
  <a href="/pricing">Pricing</a>
</nav>
```
Tip: It’s fine to expand a menu on focus for discoverability, but don’t redirect until activation.

Good Example: Custom Control with Predictable Focus
```
<button aria-expanded="false" aria-controls="filters" id="filterToggle">
  Filters
</button>
<div id="filters" hidden>
  
</div>
```
This pattern ensures that nothing happens on focus. Activation (click, Enter, or Space) toggles the state, while ARIA reflects the change.

Frequently Asked Questions

What’s the primary goal of SC 3.2.1 On Focus?
To make sure that receiving focus doesn’t cause unexpected context changes. Users, not scripts, decide when to act.

Is onfocus always forbidden?
Not necessarily. You can use it for subtle cues like highlighting an element. Just don’t trigger navigation, submissions, or new windows.

Can focus ever be moved programmatically?
Yes—if it matches user expectations. For example, moving focus into a modal when it opens, or pointing to an inline error message after a failed form submission, are acceptable.

How should I handle dynamic components like tabs or accordions?
Stick to activation-based behavior. Use arrow keys to move between tabs, but only switch panels when a tab is activated, following WAI-ARIA Authoring Practices.

Build Predictable Experiences (and Trust)

At its core, SC 3.2.1 is about respect. Focus should never feel like a trap door. By preventing context changes on focus, you protect users from confusion, reduce errors, and make your interface feel stable and reliable.

Accessible design isn’t just about checking a box—it builds trust. Predictable interactions show users that their time and attention are valued, whether they’re navigating with a screen reader, a keyboard, or a mouse. And when people can move through your site without fear of surprises, they’re more likely to stay, engage, and return.

If you’re unsure whether your site meets this success criterion—or you’d like expert guidance on weaving accessibility into everyday development—schedule an ADA briefing with 216digital. We’ll review your patterns, coach your team, and help you create consistent, user-friendly experiences that people can rely on.
Greg McNeil

September 8, 2025

How-to Guides, Testing & Remediation

Accessibility, digital accessibility, How-to, keyboard accessibility, On Focus, Web Accessibility, web developers, web development, Website Accessibility
How to Implement Truly Accessible SVG Graphics
SVGs are everywhere—icons, logos, data visualizations, animated illustrations. They’re crisp on any screen, tiny in file size, and easy to style. But here’s the catch: an SVG is only as accessible as you make it. If you don’t give it a name, if you rely on color alone, or if you forget keyboard support, your “perfect” vector can become a roadblock.

This guide gives developers and designers practical steps to build accessible SVG graphics that meet WCAG, work with assistive tech, and still look great.

Understanding SVG Accessibility Fundamentals

SVG (Scalable Vector Graphics) is an XML-based format. Because it’s text-based, you can label it semantically, control it with CSS and JavaScript, and scale it cleanly for magnifiers and high-DPI displays. The benefit? You can transform a standard image into an accessible SVG that supports users with low vision, screen readers, or alternative input devices.

Why SVGs Can Be Great for Accessibility
- Scales cleanly: No blur when a user zooms to 200%+.
- Semantic hooks: You can add <title>, <desc>, and ARIA attributes.
- Keyboard-friendly: With the correct markup, interactive SVGs can be fully operable.
But none of that happens by default. You need to choose the correct pattern and add the right attributes. That’s how you turn a scalable vector into an accessible SVG.

Decorative vs. Informative SVGs: Know the Difference

Decorative SVGs

Remove these visual flourishes (background shapes, dividers) from the accessibility tree so screen readers don’t announce them.
```
<svg aria-hidden="true" focusable="false" width="200" height="50" viewBox="0 0 200 50">
  
</svg>
```
- aria-hidden= "true" hides it from assistive tech.
- focusable= "false" helps older browsers avoid focusing it.
Informative SVGs

These convey meaning (icons that label actions, logos that identify brands, charts that show data). They must have an accessible name and sometimes a longer description.

Common mistakes to avoid:
- No accessible name (the icon is silent to screen readers).
- Meaning conveyed by color only (fails WCAG 1.4.1).
- Interactive graphics that aren’t keyboard operable.
Choosing the Right Pattern: Inline vs. External

Inline SVG (Best for Control and Accessibility)

Inline SVG gives you full control: you can add <title>, <desc>, role, and tie everything together with aria-labelledby.

When to use it: Complex icons, logos with text equivalents, charts, or anything interactive.
```
<svg role="img" aria-labelledby="downloadTitle downloadDesc" viewBox="0 0 24 24">
  <title id="downloadTitle">Download</title>
  <desc id="downloadDesc">Arrow pointing into a tray indicating a download action</desc>
  
</svg>
```
Tip: aria-labelledby lets you explicitly control the accessible name. Screen readers will read the title and then the description when useful.

External SVG via <img src="...">

Use it for simple, non-interactive icons and reusable logos.
```
<img src="/icons/lock.svg" alt="Locked">
```
- Use meaningful alt text.
- If you need a long description (e.g., describing a complex chart), place that adjacent in the DOM and reference it in the surrounding text. You can also wrap the image in a <figure> with a <figcaption> for richer context.
Note: If you rely on <title>/<desc> inside the SVG file itself, those must be authored in the file, not the HTML. You can’t inject them from outside.

Best Practices for Accessible SVGs

Add Accessible Text
- Short label? Use <title> (or alt if using <img>).
- Extra context? Use <desc>, or point to adjacent text with aria-describedby.
```
<figure>
  <svg role="img" aria-labelledby="logoTitle" viewBox="0 0 100 24">
    <title id="logoTitle">Acme Tools logo</title>
    
  </svg>
  <figcaption class="sr-only">Acme Tools, established 1984</figcaption>
</figure>
```
A common pattern for longer descriptions is to reference hidden explanatory text:
```
<p id="chartLongDesc" class="sr-only">
  2025 sales by quarter: Q1 1.2M, Q2 1.5M, Q3 1.4M, Q4 1.8M—Q4 is highest.
</p>
<svg role="img" aria-labelledby="chartTitle" viewBox="0 0 600 400">
  <title id="chartTitle">2025 Sales by Quarter (Bar Chart)</title>
  
</svg>
```
Screen reader–only utility:
```
.sr-only {
  position:absolute !important;
  width:1px;height:1px;
  padding:0;margin:-1px;
  overflow:hidden;clip:rect(0,0,0,0);
  white-space:nowrap;border:0;
}
```
Contrast & Readability

Text inside SVGs follows WCAG text contrast:
- Normal text: 4.5:1 minimum
- Large text (18pt/24px regular or 14pt/18.66px bold): 3:1
- Non-text elements (lines, icons, bars): 3:1 (WCAG 1.4.11).
- Keep text readable at zoom levels users commonly use. Consider vector-effect= "non-scaling-stroke" if thin strokes get too thin when scaled.
Don’t Use Color Alone

Color-only encodings (e.g., red vs. green) aren’t enough. Add:
- Patterns or textures on bars/lines.
- Labels or icons with different shapes.
- Legends with clear text.
```
<pattern id="diagonalHatch" patternUnits="userSpaceOnUse" width="8" height="8">
  <path d="M0,8 l8,-8 M-2,2 l4,-4 M6,10 l4,-4" stroke="currentColor" stroke-width="1"/>
</pattern>
<rect x="10" y="10" width="50" height="200" fill="url(#diagonalHatch)"/>
```
Focus and Keyboard Navigation
- Non-interactive SVGs should not be focusable: tabindex= "-1" and/or focusable= "false".
- Interactive controls should use native HTML elements for the focus/keyboard model. Wrap the SVG in a <button> or <a> rather than adding click handlers to the <svg> itself.
```
<button type="button" aria-pressed="false">
  <svg aria-hidden="true" focusable="false" width="20" height="20">
    
  </svg>
  <span class="sr-only">Mute audio</span>
</button>
```
Provide visible focus styles for WCAG 2.4.7 (e.g., clear outline around the button).

Use ARIA Thoughtfully
- Favor semantics you already get from HTML (<button>, <a>, <figure>, <img>).
- When you do label an inline <svg> as an image, role= "img" plus an accessible name (via <title> or aria-labelledby) is usually enough.
- Avoid piling on roles like graphics-document unless you know the support landscape you’re targeting and have tested it. Over-ARIA can confuse screen readers.
Inherit Color Responsively

For icons that should match text color and adapt to themes, use currentColor:
```
<svg role="img" aria-labelledby="checkTitle" width="20" height="20">
  <title id="checkTitle">Success</title>
  <path d="..." fill="currentColor"/>
</svg>
```
Now your icon inherits color from CSS—great for dark mode.

Sprite Systems (<use>) and Symbols

When using a sprite:
```
<svg class="icon" role="img" aria-labelledby="searchTitle">
  <title id="searchTitle">Search</title>
  <use href="#icon-search"></use>
</svg>
```
Important: Don’t rely on titles inside <symbol>—screen readers often skip them when you reference them with <use>. Add the label at the point of use or wrap the icon in a labeled control.

Testing SVG Accessibility: Don’t Skip This Step

Quick Checklist
- Does the SVG have a clear, accessible name?
- Is extra context available via <desc> or aria-describedby if needed?
- Are decorative elements hidden?
- If interactive: Is it reachable by keyboard? Operable with Enter/Space?
- Is the tab order logical?
- Do text and key shapes meet contrast requirements?
- Do animations honor prefers-reduced-motion?
Tools & Methods
- Screen readers: VoiceOver (macOS/iOS), NVDA or JAWS (Windows), TalkBack (Android).
- Keyboard only: Tab, Shift+Tab, Enter, Space, Arrow keys.
- Zoom to 200% and 400% to check readability and hit target sizes.
Common Pitfalls (and Easy Fixes)

Using SVG as a CSS Background for Meaningful Content

Background images can’t have alt text. If it conveys meaning, embed it inline or with <img> and provide an accessible name.

Forgetting to Label Icons

A lock icon without a label is silent. Add <title> to the <svg> or use <img alt= "Locked">.

Overwriting Contrast With Themes

Dark mode CSS might drop your contrast below 3:1 for shapes or 4.5:1 for text—Re-test after theme changes.

Unlabeled Charts

A beautiful chart that’s unlabeled is unusable. Provide a title, a short summary, and a link or reference to the underlying data table.

Interactive SVG Shapes Without Semantics

Don’t attach click handlers to <path> or <g> and call it done. Wrap the icon in a <button> or <a> and use proper ARIA (e.g., aria-pressed) where appropriate.

Practical Patterns You Can Copy

Informative Standalone Icon (Inline SVG)
```
<svg role="img" aria-labelledby="infoTitle infoDesc" viewBox="0 0 24 24">
  <title id="infoTitle">Information</title>
  <desc id="infoDesc">Circle with a lowercase “i” inside</desc>
  
</svg>
```
Decorative Icon Inside a Button (Button Provides the Name)
```
<button type="button">
  <svg aria-hidden="true" focusable="false" width="20" height="20"></svg>
  Save
</button>
```
Chart With Long Description and Data Table
```
<figure>
  <p id="salesDesc" class="sr-only">
    Bar chart showing quarterly sales for 2025: Q1 1.2M, Q2 1.5M, Q3 1.4M, Q4 1.8M.
  </p>
  <svg role="img" aria-labelledby="salesTitle" viewBox="0 0 640 400">
    <title id="salesTitle">2025 Quarterly Sales</title>
    
  </svg>
  <figcaption>Summary of 2025 sales; see table below for details.</figcaption>
</figure>
<table>
  <caption class="sr-only">Detailed sales data for 2025</caption>
<thead><tr><th>Quarter</th><th>Sales</th></tr></thead>
  <tbody>
    <tr><td>Q1</td><td>$1.2M</td></tr>
    <tr><td>Q2</td><td>$1.5M</td></tr>
    <tr><td>Q3</td><td>$1.4M</td></tr>
    <tr><td>Q4</td><td>$1.8M</td></tr>
  </tbody>
</table>
```
Accessibility for Motion and States

If your SVGs animate, respect user preferences:
```
@media (prefers-reduced-motion: reduce) {
  svg .spin { animation: none; }
}
```
For toggles (like mute/unmute), update both the visual state (icon changes) and the accessible state (aria-pressed, live text updates).

Accessible Design is Intentional Design

Accessible SVGs aren’t just about tags and attributes—they’re about clear communication. When you provide an accessible name, avoid color-only meaning, ensure keyboard operation, and include descriptions where needed, you open your visuals to many more people—without sacrificing design or performance.

Start small and build the habit:
- Label every meaningful icon.
- Hide true decoration.
- Test with a screen reader and the keyboard.
- Re-check contrast after style changes.
Accessibility is a practice, not a checkbox. The pay-off is real: better UX, fewer support issues, and stronger compliance.

Need a Second Set of Eyes?

If you want help reviewing your site’s SVGs, charts, and icon systems, schedule an ADA briefing with 216digital. We’ll give you actionable feedback, prioritize fixes, and help you ship accessible SVG patterns that scale across your design system.
Greg McNeil

August 14, 2025

How-to Guides

Accessibility, accessible code, How-to, SVG, Web Accessibility, web developers, web development, Website Accessibility
Lost in Focus? Blame Keyboard Traps
You’ve probably been there. You build a custom modal or some fancy dropdown, tab into it to test, and suddenly you’re stuck. Focus won’t move. The Tab key feels broken, Shift+Tab does nothing, and Escape isn’t helping either. That’s not a bug in your laptop—it’s a keyboard trap.

And honestly? They’re way more common than we like to admit. WebAIM has been flagging them as one of the top accessibility failures for over a decade, and the problem hasn’t really improved. The thing is, you don’t need to be an accessibility specialist to fix them. You just need to understand how they occur, how the Web Accessibility Guidelines (WCAG) addresses them, and how to integrate prevention into your regular workflow. Let’s talk through it, developer to developer.

What Are Keyboard Traps?

A keyboard trap happens when focus moves into a component but can’t get back out using standard keyboard navigation. That usually means Tab and Shift+Tab stop working, Escape is ignored, and the user is stuck.

According to WCAG Success Criterion 2.1.2 (“No Keyboard Trap”), any element that takes focus must also provide a way to exit using only the keyboard. In other words: if your widget can grab focus, it must also let go of it.

For developers, this is more than a compliance checkmark. A trap breaks assumptions about how users move through a page. It disrupts assistive tech like screen readers and can fail QA instantly. Even if the rest of your site is clean, one trap in a modal or custom control can undo the entire user journey.

Who’s Affected (And Why You Should Care)

It’s easy to think of accessibility in the abstract, but keyboard traps create very real roadblocks:
- Motor-impaired users rely on the keyboard because a mouse isn’t practical.
- People with temporary injuries—a broken wrist, for example—may need keyboard-only navigation for weeks.
- Screen reader users follow focus to know where they are. If it never moves, the reader has nothing more to say.
- Developers themselves—many of us use the keyboard for speed. If you’ve ever hit Tab to check your own work and gotten stuck, you know how disruptive it feels.
Bottom line: if your component can trap you, it can trap someone who doesn’t have another option.

So where do these traps usually show up? More often than not, in the places where we customize behavior.

Where Keyboard Traps Hide

Traps aren’t usually intentional. They sneak in where custom code overrides native behavior. Here are the usual suspects:

Modals, Popovers, and Dialogs

A modal with div role="dialog" looks great until focus disappears inside. The fix is to intentionally loop focus only while the modal is open and let Escape close it:
```
function trapFocus(modalEl) {
  const focusable = modalEl.querySelectorAll(
    'a[href], button:not([disabled]), input, textarea, select, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];
  modalEl.addEventListener("keydown", e => {
    if (e.key === "Tab") {
      // If Shift+Tab on first element, wrap back to last
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      }
      // If Tab on last element, wrap back to first
      else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    } else if (e.key === "Escape") {
      // Allow users to close with Escape and return focus
      closeModal();
    }
  });
}
```
This follows WAI-ARIA practices: focus a meaningful element on open, loop safely, and return focus when closing.

Forms and Custom Inputs

Date pickers or masked inputs often intercept arrow keys, Enter, or Tab. Without an Escape handler, the user is locked. Keep event listeners scoped:
```
datePickerEl.addEventListener("keydown", e => {
  switch (e.key) {
    case "ArrowLeft": /* move date */ break;
    case "ArrowRight": /* move date */ break;
    case "Escape":
      // Escape should always close and release focus
      closeDatePicker();
      break;
    default:
      return; // Don’t block Tab or Shift+Tab
  }
});
```
Also keep aria-expanded updated so assistive tech knows when a picker is open or closed.

Media Players

Custom video players sometimes swallow every keydown. Space, arrows, and Tab all get blocked. That’s a recipe for keyboard traps. Instead:
```
playerEl.addEventListener("keydown", e => {
  if (e.key === " " || e.key.startsWith("Arrow")) {
    // Map keys to playback controls (play, pause, seek, etc.)
    e.stopPropagation(); // Stop event bubbling, but don’t block Tab
  }
  // Important: Don’t block Tab!
});
```
For YouTube iframes, use ?disablekb=1 to disable its shortcuts and implement your own accessible ones.

JavaScript-Enhanced Links

Sometimes developers add keydown handlers to links or buttons that override Tab. If you call preventDefault() on Tab, you’ve created a trap.

Rule of thumb: only intercept Space or Enter for activation. Let Tab do its job.

Testing for Keyboard Traps

Automation tools like WAVE or Lighthouse can catch some violations, but many traps slip through. Manual checks are essential:
- Start at the browser address bar.
- Press Tab repeatedly.
- Watch the focus ring. Does it keep moving or stall?
- Use Shift+Tab to go backward.
- Open components like modals, menus, or players. Try Escape. Does it close and return focus?
Build this into your QA flow. Think of it as a “keyboard-only smoke test.” It takes two minutes and can save your users hours of frustration.

Best Practices for Trap-Safe Code

To keep keyboard traps out of your codebase:
- Use native elements whenever possible—buttons, links, selects. They come with keyboard behavior for free.
- Follow ARIA Authoring Practices when building custom components. They define expected key behavior for dialogs, menus, and more.
- Centralize focus-trap utilities. Don’t reinvent it in every modal.
- Document the behavior. A hint like “Press Escape to close” in a dialog helps everyone.
- Add accessibility checks in your Storybook or Cypress tests. Press Tab in your stories. Does it cycle correctly?
A Safe Dropdown in Action

Here’s a minimal example of a dropdown that avoids keyboard traps:
```
<button id="dropdown-trigger" aria-expanded="false" aria-controls="dropdown-menu">
  Options
</button>
<ul id="dropdown-menu" role="menu" hidden>
  <li role="menuitem"><a href="#">Profile</a></li>
  <li role="menuitem"><a href="#">Settings</a></li>
  <li role="menuitem"><a href="#">Logout</a></li>
</ul>
```
With the right ARIA attributes and by leaving Tab behavior untouched, this dropdown stays safe and accessible.

Build Trap Prevention into Your Workflow

Don’t treat accessibility like a last-minute patch. Bake it into your process:
- Add “keyboard-only test” to your pull request checklist.
- Run axe-core or similar tools on staging builds.
- Train QA and PMs to check focus flows during reviews.
- Pair with design: ask early, “How would this work without a mouse?”
These habits don’t just prevent keyboard traps—they build a culture of inclusive development.

Focus on What Matters

Accessibility slips often come from the smallest details—like a single missing Escape handler or an overzealous preventDefault(). But those little choices ripple out into real-world barriers. The upside is, once you start looking for them, traps are one of the easiest things to fix—and the payoff is huge.

If you’re looking to strengthen your accessibility practices and reduce risk, 216digital offers ADA briefings tailored specifically for development teams. These sessions go beyond checklists—they walk through real code examples, explain how WCAG applies in day-to-day work, and give your team a clear roadmap for building components that won’t leave users stuck. It’s a chance to ask questions, get practical guidance, and bring accessibility into your workflow in a way that lasts.

Schedule an ADA briefing today and start building better, more inclusive code.
Greg McNeil

August 4, 2025

How-to Guides

Accessibility, How-to, keyboard accessibility, Keyboard Navigation, Keyboard traps, web developers, web development, Website Accessibility
How to Identify Decorative Images for Accessibility
Images can bring a web page to life—but not all of them need to speak. When it comes to web accessibility, knowing which images are decorative and which are informative is key to creating a cleaner, smoother experience for people using screen readers and other assistive technologies. That’s where alternative text (alt text) comes in.

You probably already use alt text to describe important images. But what about the purely visual ones—those flourishes and background elements? If they don’t add value beyond appearance, they might be decorative images. This article helps you identify which images fall into that category and how to properly mark them, so screen reader users aren’t bogged down by unnecessary noise.

By focusing on even small improvements—like skipping redundant descriptions—you can build better, more respectful websites.

What Makes an Image “Decorative”?

Let’s start with the basics. According to WCAG 2.1 Success Criterion 1.1.1: Non-text Content, all meaningful non-text content must have a text alternative. But decorative images are an exception—they don’t need a description because they don’t carry meaning.

So, what exactly counts as decorative?

Common Decorative Image Types
- Borders, swirls, and flourishes that are strictly for looks
- Icons next to already-labeled buttons (like a phone icon next to the word “Call”)
- Stock photos that add mood or style but aren’t referenced in content
- Repetitive logos or design elements used as dividers or backgrounds
If removing the image doesn’t change the message or function of the page, you’re likely dealing with a decorative image.

Making the Right Call: Informative or Decorative?

It’s not always black and white. Here are a few quick questions to help:
- Does the image convey info that isn’t available in the text?
- Would a user miss out on something if the image was gone?
- Is the image part of an instructional step, chart, or link?
If you answer yes to any of these, the image is probably informative—and it needs descriptive alt text. If not, you may be safe to treat it as decorative.

For a more detailed approach, try W3C’s Alt Decision Tree. It’s a great tool, but don’t worry—no one expects you to follow it like a script. Trust your content instincts too.

Common Mistake Alert: Don’t mark company logos, charts, or instructional images as decorative. If they carry meaning or serve a function, they need proper alt text.

How to Properly Mark Decorative Images in Code

Once you’ve determined that an image is decorative, here’s how to ensure assistive technologies skip over it.

Use an Empty Alt Attribute

This is the most common and widely supported method:
```
<img src="divider.png" alt="">
```
Why does this work? A screen reader will completely ignore the image. This prevents confusion and keeps users focused on meaningful content.

But be careful: don’t skip the alt attribute altogether. Leaving it out may cause screen readers to read the file name—something like “divider-dot-p-n-g”—which is exactly the kind of noise we’re trying to eliminate.

Use role="presentation" or aria-hidden="true"

For SVGs, icons, or complex visual elements that can’t use alt="", try one of these:
```
<svg role="presentation">...</svg>
<img src="swirl.svg" aria-hidden="true">
```
What’s the Difference?
- role= "presentation" tells assistive tech: this element is just for visuals.
- aria-hidden= "true" hides the element from all assistive tech completely.
Choose one—don’t combine them with an empty alt attribute. Using both can confuse the accessibility tree and cause unpredictable results.

Best Practices & Pitfalls to Avoid

To keep your decorative images accessible:
- Use only one method to mark an image as decorative
- Test your implementation using screen reader emulators, WAVE, or Lighthouse
- Avoid using the word “decorative” in the alt text—use an empty alt attribute instead.
- Always include the alt attribute, even if it’s empty.
- Be careful not to hide meaningful images by using aria-hidden="true".
It’s also a good idea to review your CMS settings. Many platforms automatically insert images or fill alt text fields with file names. Stay alert!

Why It Matters: The Impact of Doing It Right

When you handle decorative images properly, you create a better user experience for everyone:
- Less noise for screen reader users, making it easier to navigate pages
- A clearer focus on important content and messages
- Reduced cognitive load, especially for users with visual or cognitive disabilities
- Cleaner code that’s easier to maintain and optimize
Bonus: It can even help with SEO by making your site more semantic and purposeful.

Real users have reported better experiences when extra, repetitive images are removed from their screen reader journey. It’s a small step with a big payoff.

Beyond Alt Text: Decorative Images Are Just One Part

Identifying and labeling decorative images is one part of a much larger accessibility picture. But it’s a foundational step.

Teams should regularly audit content—especially in environments where new images are often added, like blogs or e-commerce templates. Ask yourself: are new images truly meaningful, or just visual noise?

Also, remember: accessibility isn’t one person’s job. It’s a shared responsibility. Designers, devs, marketers, and content creators all play a role in making digital experiences more inclusive.

And if you’re using modern frameworks like React or Vue, be sure your components handle decorative images correctly and out of the box. A simple alt=”” on a reusable image tag can save a lot of friction.

Keep Image Accessibility Intentional

To recap: If an image is purely decorative, mark it so that screen readers skip over it. Use an empty alt="", or where needed, role= "presentation" or aria-hidden= "true". Don’t mix methods, and always test your work.

Improving how you handle decorative images might seem like a small detail, but it’s a powerful way to respect your users and refine your site’s accessibility. Thoughtful design isn’t just about how a site looks—it’s about how it feels to navigate.

Need a second pair of eyes on your accessibility implementation?

Schedule an ADA accessibility briefing with 216digital. Our experts can help you identify gaps, offer hands-on guidance, and take the guesswork out of inclusive design—so your digital experiences work better for everyone.
Greg McNeil

June 23, 2025

How-to Guides

How-to, Image Alt Text, WCAG, WCAG Compliance, web developers, web development
Build Accessibility In, Don’t Bolt It On
A brand-new website can feel polished and future-proof—right up until someone with a screen reader runs into a dead-end menu or a keyboard user can’t tab past the hero banner. Suddenly the “finished” project is back on the operating table, costing hours (and budget) you’d already spent elsewhere.

When accessibility planning is woven into the first brainstorm—alongside color palettes, user flows, and content themes—those last-minute scrambles disappear. Decisions get crisper, code stays cleaner, and every visitor, regardless of ability, enjoys the same smooth path through your pages.

Think of accessibility less as decorative trim and more as the blueprint that holds the whole structure together. Start with it, build on it, and you’ll launch faster, spend less, and welcome more people from day one.

What Does “Bolting It On” Look Like?

Many organizations treat accessibility like a retrofit. The site is already built, the design is approved, and the content is live. Only then does someone say, “Wait—what about screen reader support? What about color contrast? What if this form can’t be used with a keyboard?”

Now you’re in damage control. Fixing accessibility issues post-launch can require rewriting code, redesigning components, and delaying updates. Even worse, you may be stuck with baked-in barriers that are difficult or costly to correct. For example:
- Rebuilding menus that were designed without keyboard navigation in mind
- Rewriting interactive components that don’t support screen readers
- Replacing an entire color palette because contrast ratios fail WCAG
Accessibility planning means thinking about inclusion as you sketch wireframes, select a CMS, or build your first component. It means your developers write semantic HTML, your designers test color contrast before finalizing a palette, and your content creators write with clarity and structure.

When accessibility planning is part of the DNA of your project, you get better results—faster and with fewer surprises.

Accessibility Planning = Smart, Strategic Design

Now imagine the opposite scenario: your team is starting a new project or redesign. Right at the beginning, you ask:
- Who are our users, and what diverse needs do they have?
- Are we designing this interface to be usable without a mouse?
- Can our color and font choices work for users with low vision or dyslexia?
- Are we writing alt text for images, and using descriptive link text?
- Is this form easy to complete using assistive technology?
These questions don’t slow you down. They guide your decisions from the ground up.

Accessibility planning means thinking about inclusion as you sketch wireframes, select a CMS, or build your first component. It means your developers write semantic HTML, your designers test color contrast before finalizing a palette, and your content creators write with clarity and structure.

When accessibility is part of the DNA of your project, you get better results—faster and with fewer surprises.

6 Stages Where Accessibility Belongs

Here’s how to build accessibility into your process, stage by stage:

1. Discovery and Strategy

Before any code or design work begins, include accessibility planning as a strategic priority. Define your target users, including those with disabilities. Document accessibility goals and requirements as part of your project scope.

Make accessibility a deliverable—not an afterthought.

2. UX and Visual Design

Design with inclusivity in mind. That means:
- High contrast color palettes
- Clear visual hierarchy
- Large, legible typography
- Components that look good and function well with assistive tech
- Clear focus indicators and logical navigation
Don’t assume visual design is just aesthetics—it impacts usability for everyone.

3. Content Creation

Content creators play a major role in accessibility planning. They should:
- Use descriptive headings and meaningful subheadings
- Write clear, concise link text (“Download the annual report” instead of “Click here”)
- Provide transcripts or captions for audio and video
- Write meaningful alt text for important images
Training your content team on accessibility saves hours of rewriting down the road.

4. Front-End Development

This is where accessibility really comes alive. Developers should use:
- Semantic HTML (correct use of <nav>, <button>, <label>, etc.)
- ARIA labels only when needed—not as a shortcut for poor structure
- Keyboard operability for all interactive elements
- Logical tab order and skip navigation links
Accessibility-friendly code isn’t just better for screen readers—it’s more resilient, scalable, and SEO-friendly too.

5. Testing and QA

Accessibility testing isn’t just automated. While tools like Lighthouse, or WAVE help flag obvious issues, real users and manual testing are critical.
- Test with screen readers like NVDA or VoiceOver
- Navigate your site using only a keyboard
- Check forms for proper labels and error handling
- Test responsiveness and zoom up to 200%
Bring in users with disabilities if possible. Their feedback is irreplaceable.

6. Launch and Maintenance

Accessibility doesn’t stop at launch. It’s an ongoing effort. As you add new features or content, revisit your accessibility standards. Schedule regular audits. Monitor legal developments. Consider automated tools like a11y.Radar for early issue detection.

The Human Side of Accessibility

It’s easy to talk about accessibility in technical terms, but at its core, it’s about people.

Think about someone using a screen reader to access your site. Or someone with motor limitations who can’t use a mouse. Or someone dealing with temporary impairments—a broken wrist, eye strain, or even just a noisy environment where audio isn’t practical.

Building accessibility in from the start isn’t about compliance for its own sake. It’s about treating all users with dignity. It’s about believing that digital spaces should work for everyone, regardless of ability.

Common Pitfalls to Avoid

Even with good intentions, teams can fall into these traps:
- Assuming accessibility is only the developer’s job: Accessibility is a shared responsibility across design, content, and engineering.
- Waiting until the QA phase: Accessibility can’t be “tested in” at the end. It must be designed and developed.
- Relying too much on overlays or plugins: Widgets don’t fix inaccessible code. In some cases, they create more problems than they solve.
- Failing to document decisions: Keep a living accessibility checklist. It helps ensure continuity across teams and updates.
Why It Pays Off

Here’s what you gain when you build accessibility in from day one:
- Faster development: Fewer reworks, cleaner code
- Lower costs: Avoid costly redesigns and retrofits
- Happier users: Better usability for everyone, not just people with disabilities
- Improved SEO: Accessibility often overlaps with search best practices
- Reduced legal risk: Stay ahead of ADA and state-level laws like Colorado HB 21-1110
- Stronger brand reputation: Inclusion signals leadership and care
Most importantly, you build a digital presence that welcomes, respects, and serves more people exactly like the web was meant to work.

No Ifs, Ands, or Bugs—Just Accessibility Plans

Accessibility doesn’t belong on a post-launch checklist or in a future phase that never quite gets prioritized. It belongs at the table from day one—when you’re mapping out user journeys, designing components, and writing your very first lines of code.

By making accessibility planning a core part of your workflow, you avoid costly rework, improve overall quality, and create digital experiences that serve more people, more effectively. It’s not about adding more to your plate—it’s about building smarter from the start.

If you’re ready to move from fixing to future-proofing, 216digital can help. Our phased accessibility services are designed to meet you where you are, guide your team, and strengthen your site’s foundation for the long haul. Let’s make accessibility part of how you build—every time.
Greg McNeil

June 20, 2025

Testing & Remediation

Accessibility, Accessibility Remediation, Accessibility testing, Web Accessibility, Web Accessibility Remediation, web development
Descriptive Page Titles for Better Accessibility
If you’ve ever had 15 tabs open at once (and let’s be honest—who hasn’t?), you know how frustrating it is to click around trying to remember which one is which. When the titles are clear, you can find what you’re looking for in a second. When they’re not, it’s a guessing game.

For users who rely on screen readers or who live with cognitive or memory challenges, vague titles aren’t just annoying. They’re a real barrier. That’s where descriptive page titles come in. They make a huge difference in helping all users navigate the web more easily, and they support your site’s overall usability and accessibility—without requiring a major overhaul.

Best of all, it’s one of the simplest changes you can make that still packs a serious punch. A good page title improves orientation, reduces confusion, boosts your SEO rankings, and even helps reduce legal risk under the Americans with Disabilities Act (ADA). All with a few well-chosen words.

What WCAG 2.4.2 Actually Requires

Under WCAG 2.4.2—a Level A requirement in the Web Content Accessibility Guidelines (WCAG)—every web page must have a title that clearly describes its topic or purpose. It’s one of the most fundamental accessibility requirements, but it’s also one of the most overlooked.

Simply having a <title> tag isn’t enough. What’s inside that tag matters. A vague or generic title—like “Home” or “Untitled”—does little to help users understand what the page is actually about. It’s a bit like labeling all your folders “Stuff”—no one can navigate that efficiently, especially not users relying on assistive technologies.

This is especially important for screen reader users. Page titles are often read aloud as soon as a page loads or when switching between browser tabs. That brief moment of context helps them know exactly where they are. Similarly, sighted users benefit from meaningful titles when scanning through multiple open tabs or saving bookmarks for later reference.

Who Benefits from Descriptive Page Titles?

The short answer? Everyone. But here’s how it really plays out for different types of users:
- Screen reader users hear the page title as their first introduction. A vague or incorrect title can throw them off or force them to dig deeper than necessary.
- People with cognitive or memory challenges rely on titles to quickly understand whether a page is relevant. A well-written title can prevent information overload and reduce frustration.
- Mobility-impaired users benefit because they can avoid unnecessary clicks or key presses if the title tells them they’re on the wrong page.
- Everyone else—yes, even those without disabilities—appreciates descriptive page titles for the sheer convenience. Clear titles make it easier to navigate tabs, scan bookmarks, and share links confidently.
When a title says exactly what a page delivers, no one has to guess. That’s good usability—and that’s what accessibility is really about.

Common Title Mistakes (And How to Fix Them)

Even with the best intentions, many websites still fall into title traps. Let’s look at a few common problems:
- Too Vague: Titles like “Home” or “Blog” don’t help much when you’re trying to tell one tab from another.
- Reused Titles: When every blog post or account page is titled the same—like “Monthly Statement”—users lose their place quickly.
- Doesn’t Match the Page: If your title says “Pricing,” but the page is about features or FAQs, that mismatch causes confusion.
- Overloaded for SEO: You’ve seen these: “Best Home Trim Vinyl Windows Outdoor Accessories 2025 Guide.” They’re trying to do too much and end up helping no one.
Better Examples

Consider replacing generic titles with more descriptive ones. For example, swap “Blog Post” with “How to Write Descriptive Page Titles.” You might also change “Services” to “Real World Accessibility | 216digital,” or “Contact” to “Contact Us – 216digital Web Team.”

These small edits bring clarity, build trust, and boost both accessibility and SEO

Accessibility and SEO: They Work Together

There’s a common myth that writing for accessibility hurts SEO—but that couldn’t be further from the truth. In fact, descriptive page titles are a perfect example of how accessibility and SEO can work in harmony.

Search engines love pages with relevant, concise, and unique titles. So do people. That means when you follow accessibility best practices, you’re also improving your site’s visibility and user engagement.

Tips for Great Titles
- Keep them between 30–60 characters so they don’t get cut off in search results or browser tabs.
- Use primary keywords naturally, not awkwardly.
- Try using a pattern like: [Page Topic] | [Brand Name].
So, “About” becomes “About Our Team | 216digital” and “Pricing” becomes “Website Accessibility Pricing | 216digital.”

It’s easy to see how small tweaks can have a big payoff.

How to Improve Your Titles—Step by Step

Here’s a quick plan to help you get your titles in shape:

Audit Your Site

Use automated tools to spot missing, duplicate, or unusually long titles. But don’t stop there—manual review is key to catching vague or misleading language that tools might miss.

Apply a Simple Template

Keep it consistent across your site: “[Page Topic] | [Brand]” works for most needs and helps build recognition.

Loop in Your Team

Content creators, developers, designers, and SEO specialists should all care about good descriptive page titles. Make it a shared goal—not an afterthought.

Add it to Your Checklist

Whether you’re launching a new blog post, updating a product page, or doing a site redesign, reviewing the title tag should be part of the process every time.

The Risks of Getting It Wrong

Ignoring this part of accessibility can lead to bigger problems. WCAG 2.4.2 is part of ADA compliance, and missing or misleading titles are often among the first things flagged in accessibility audits. If you’re not in compliance, you could be vulnerable to lawsuits—and nobody wants that.

But beyond legal risk, failing to use descriptive page titles sends the wrong message. It suggests your site wasn’t built with every user in mind. And that hurts brand trust more than you might think.

Final Thoughts: Titles That Work for Everyone

It’s easy to overlook something as small as a page title. But when you take a step back, you’ll see that descriptive page titles affect every part of your site—from how users find you, to how they feel while browsing, to whether they come back at all.

This one fix can make your site more usable, more discoverable, and more inclusive—without blowing up your workflow or budget. That’s what we call a smart move.

Ready to Take Action?

Want help reviewing your site for accessibility wins like this one? Schedule an ADA briefing with 216digital. We’ll show you how small changes like descriptive page titles can lead to big improvements in compliance, usability, and user trust—no pressure, no hard sell.

Let’s build a web that works for everyone—starting with the title.
Greg McNeil

June 18, 2025

How-to Guides

Accessibility, How-to, Page Titles, WCAG, WCAG Compliance, Web Accessibility, web developers, web development, Website Accessibility
WordPress Accessibility: Common Pitfalls & Fixes
WordPress gives developers a head start with accessibility—but it’s just that: a start. While the platform includes solid foundations like semantic markup and keyboard-friendly admin features, building an experience that works for everyone still requires thoughtful decisions on our part. As developers, we’re in a unique position to go beyond the basics, spotting the small oversights that can create big barriers for users.

In this guide, we’ll walk through some of the most common accessibility missteps we see in WordPress projects—along with practical fixes you can implement right away. Whether you’re refactoring an old theme or launching something new, these insights are meant to help you create experiences that are not just compliant, but genuinely inclusive.

Misuse of Heading Structures for Visual Styling

It’s easy to reach for <h2> or <h3> tags to style text because they’re built into most WordPress themes with bold and larger font sizes. But when headings are used purely for visual emphasis—not structure—you end up distorting the page’s semantic outline.

Why It Matters

Screen reader users often rely on heading navigation to scan and jump between sections. If headings are skipped, out of order, or misused, the page becomes harder to understand, and key content may get missed entirely.

How to Fix It
- Use CSS for Styling: Apply styles using classes or inline styles, not heading tags. In Gutenberg, you can use blocks with custom styles or reusable blocks instead of jumping heading levels.
- Follow a Logical Heading Hierarchy: Begin with one <h1> per page (usually the title), then use <h2> for top-level sections, <h3> for subsections, and so on.
- Audit Your Work: Use tools like WAVE or the Google Lighthouse Accessibility Report to evaluate your heading structure and flag potential misuses before they go live.
Overreliance on Theme Defaults for Color Contrast

Many developers trust their WordPress theme’s default color scheme to do the heavy lifting—but while a palette may look good visually, it doesn’t mean it’s accessible. Default colors often fail to meetWCAG 2.1 AA standards, especially for body text and buttons.

Accessibility Risk

Poor color contrast is a major barrier for users with low vision or color blindness. If your text blends into the background, you’re excluding readers—sometimes without realizing it.

Practical Fixes
- Test Contrast Ratios: Use WebAIM’s Contrast Checker or the Color Contrast Analyzer to validate text against its background.
- Override Theme Defaults: Most modern themes offer customization options via the Customizer or Full Site Editing. Make small adjustments—lighten text, darken backgrounds—to meet or exceed the 4.5:1 minimum contrast ratio.
- Offer User Controls: Consider giving users the ability to switch to high-contrast mode with plugins like “WP Accessibility.” This gives more control to your users while improving inclusivity.
Improper List Markup Practices

It’s not unusual to see developers create the appearance of a list using <div> tags, line breaks, or other non-semantic methods—especially in custom blocks or page builders commonly used in WordPress.

Why It’s a Problem

Screen readers rely on semantic tags like <ul>, <ol>, and <li> to announce that a list exists, how many items are in it, and how items relate to each other. Without this structure, users lose context.

Best Practices
- Use Native List Markup: If it’s a list—code it as a list. Use <ul> for unordered lists and <ol> for ordered ones. Wrap each list item in <li>.
- Handle Nesting Thoughtfully: For sub-lists, nest another <ul> or <ol> inside an <li>. Screen readers will announce the nested structure properly.
- Test Your Output: Run accessibility audits or inspect the DOM to ensure list structures are coded semantically, especially when using custom Gutenberg blocks or page builders.
Neglecting Contextual Relevance in Alt Text

WordPress auto-generates alt text from image file names if authors don’t supply one. That’s how you end up with images labeled “IMG_4829.jpg”—which isn’t helpful to anyone.

Why It Matters

Alt text should describe why the image is there, not just what it looks like. If the image provides important context, instructions, or emotion, a generic label fails users who rely on screen readers.

What Developers Can Do
- Write Purpose-Driven Alt Text: If the image is showing a concept, outcome, or step in a process, describe that context directly. For example, “Screenshot of the plugin settings menu with Accessibility Mode enabled.”
- Avoid Phrases Like “Image of…” Screen readers already announce the presence of an image. Jump straight into the relevant description.
- Use Empty Alt for Decorative Images: For visuals that are purely aesthetic and add no informational value, use alt="" so assistive tech knows to skip it entirely.
Overuse and Misapplication of ARIA Attributes

ARIA is a powerful toolset—but like any tool, misuse can cause more harm than good. Adding roles and attributes without understanding their implications can break screen reader behavior or clutter the accessibility tree.

The Real Cost

Improper ARIA use can confuse assistive technologies, interfere with default behaviors, and even make components harder—not easier—to use. Overengineering is just as dangerous as under-engineering.

Smarter ARIA Use
- Favor Native HTML First: If you’re building a checkbox, <input type="checkbox"> with an associated <label> is far more reliable than using a <div> with ARIA roles and states.
- Use ARIA Only When Required: If you’re building a custom interactive widget (like a tabbed interface or menu), consult the ARIA Authoring Practices Guide. Choose correct roles and manage keyboard interactions accordingly.
- Test Your Implementation: Use screen readers like NVDA or VoiceOver to verify that ARIA is behaving as expected. Pay attention to focus, announcements, and interaction patterns.
Overlooking Keyboard Navigation and Focus Management

Many developers unintentionally design for mouse users first. But for users relying on keyboards—whether due to preference, disability, or temporary injury—keyboard accessibility is critical.

Key Accessibility Concerns
- No Visible Focus Indicators: Removing browser outlines with outline: none; without providing alternatives leaves users lost.
- Custom Components Not Keyboard-Aware: Modals, sliders, dropdowns, and carousels built from scratch often lack proper keyboard event handling and focus management.
Developer-Friendly Fixes
- Ensure Focus Visibility: Style focused elements clearly using CSS, like :focus { outline: 2px solid #000; }. Customize this to match your theme, but don’t remove it entirely.
- Handle Keyboard Events: For custom components, add keydown or keyup listeners to handle Enter, Escape, and Arrow keys appropriately. Don’t rely on click events alone.
- Do Keyboard-Only Testing: Regularly test your site using only the keyboard. Tab through each interactive element and verify focus moves logically, without skipping important controls.
What True Accessibility Looks Like in WordPress

Accessibility isn’t a checklist—it’s a mindset. When we write clean, semantic code, ensure visual clarity, and support every way a user might interact with our sites, we’re not just doing right by WCAG—we’re doing right by our users. The real goal is to build experiences that work for everyone, without assumptions about how people navigate the web.

As WordPress developers, we have powerful tools and a vibrant ecosystem at our disposal. Let’s use them with care and intention. Keep testing, stay curious, and don’t hesitate to dig deeper. And if you’re looking to strengthen your accessibility efforts, 216digital offers ADA compliance briefings tailored to development teams. We’re here to support your work—because inclusive development is better development.
Greg McNeil

June 10, 2025

How-to Guides, Legal Compliance

Accessibility, How-to, WCAG, Web Accessibility, web developers, web development, Website Accessibility, WordPress
Up and Coming ARIA Implementation
Web accessibility is always evolving. Keeping up isn’t just beneficial—it’s crucial. Accessible Rich Internet Applications (ARIA) help developers build experiences that are usable by everyone, especially those with disabilities. As web standards advance, new ARIA attributes and roles emerge. Recently, ARIA 1.3 has introduced several notable features developers should start adopting now.

Many of these are still in what could be called the “infrastructure stage”—they’re well-defined and available, but support across assistive tech and browsers remains inconsistent. That’s precisely why now is the time to pay attention. Understanding emerging ARIA implementation ensures your projects remain inclusive, user-friendly, and future-proof.

This article explores fresh ARIA implementation options, their current support levels, and how developers can practically integrate them into real-world workflows.

New and Noteworthy ARIA Attributes

aria-errormessage

Effective error messaging can significantly enhance usability. The ARIA implementation of aria-errormessage connects specific error messages to input fields when aria-invalid="true" is active. Unlike aria-describedby, this explicitly identifies the message as an error, and it’s only announced when the field is invalid—streamlining feedback for screen reader users.

Support: Strong across JAWS, NVDA, and iOS VoiceOver. More limited in other environments.

Example
```
<label for="email">Email:</label>
<input type="email" id="email" aria-invalid="true" aria-errormessage="emailError">
<span id="emailError">Please enter a valid email address.</span>
```
aria-description

This attribute supplements existing descriptive labels by offering additional, programmatically available context that isn’t always visible on screen. It’s ideal for providing hints that enhance usability without cluttering the UI. For example, use aria-description="You are here:" to add orientation to breadcrumb navigation.

Support: Currently handled well by NVDA and iOS VoiceOver; other screen readers may ignore it or misinterpret its purpose.

Example
```
<button aria-label="Download" aria-description="Downloads the current report in PDF format.">Download</button>
```
aria-details

The ARIA implementation of aria-details links an element to rich, supplementary content—replacing the outdated and poorly supported longdesc. It’s perfect for enhancing understanding of charts, data tables, and complex graphics.

Support: Announced in some screen readers, but there’s currently no direct navigation path from the referenced element to the details content—limiting usability in production environments.

Example
```
<img src="chart.png" alt="Sales Chart" aria-details="chartDetails">
<div id="chartDetails">
  <p>This chart shows sales data from Q1 to Q4, highlighting growth trends.</p>
</div>
```
aria-keyshortcuts

Keyboard accessibility remains critical for many users. The ARIA implementation of aria-keyshortcuts lets developers document expected key commands directly in markup, making interfaces easier to learn and navigate via screen readers.

Important note: This does not create functionality—it simply advertises the shortcut to assistive tech.

Support: Fairly robust in Chrome and Edge; less so in Firefox and mobile platforms.

Example
```
<button aria-label="Mute" aria-keyshortcuts="Ctrl+M">Mute</button>
```
aria-placeholder

This attribute serves as a screen-reader-friendly version of the native placeholder attribute, particularly useful for custom form controls like div[contenteditable]. Unlike native placeholders, the text won’t be announced after the field is filled, avoiding redundancy.

Support: Surprisingly consistent across JAWS, NVDA, VoiceOver, and TalkBack.

Example
```
<div contenteditable="true" role="textbox" aria-placeholder="Enter your comment here..."></div>
```
Emerging ARIA Roles Enhancing Semantic Meaning

Editorial and Collaborative Roles

Roles like role="mark", role="comment", and role="suggestion" provide semantic meaning in collaborative environments—useful in rich text editors, document workflows, and feedback tools.
- mark: Highlights text.
- comment: Marks feedback or user-generated discussion.
- suggestion: Flags proposed edits or changes.
Support: Varies widely. role="mark" is gaining traction due to its alignment with <mark>. Others are still emerging.

Example
```
<p>The final decision was <span role="suggestion">to postpone the launch</span> until next quarter.</p>
```
Technical and Temporal Roles

New semantic roles such as role="code" and role="time" help describe technical or time-based content when native elements like <code> or <time> aren’t feasible—particularly in component-based frameworks.

Support: Minimal at present but useful for long-term semantic clarity.

Example
```
<div role="code">const sum = (a, b) => a + b;</div>
<div role="time" datetime="2025-06-06T13:49:19-04:00">June 6, 2025, 1:49 PM EDT</div>
```
role=”image”

This is functionally equivalent to role="img" but offers a clearer, natural-language alternative. While it doesn’t change behavior, it can improve code readability and naming consistency across projects.

Example
```
<div role="image" aria-label="Company Logo">
  <img src="logo.png" alt="">
</div>
```
Practical Implementation Considerations

Assessing Support Across Assistive Technologies

Not every ARIA implementation feature enjoys uniform support. The ecosystem includes screen readers like JAWS, NVDA, VoiceOver, TalkBack, and browsers like Chrome, Edge, Firefox, and Safari. Always test your ARIA implementations across a matrix of platforms and devices. What works well in one may fail silently in another.

Tested Environments (May 2025)
- Windows 11: JAWS, NVDA, Narrator
- macOS Sequoia: VoiceOver
- iOS 18.4: VoiceOver (Safari)
- Android 15: TalkBack (Chrome)
Support varies—stay informed and test often.

Best Practices for Adoption
1. Use semantic HTML first. ARIA should enhance—not replace—native elements.
2. Progressively enhance. Build baseline functionality, then layer in ARIA attributes where they add real value.
3. Test with real users. Automated tests only go so far. Gather feedback from people who use assistive tech every day.
4. Implement gracefully. Ensure content degrades without breaking if ARIA features aren’t supported.
5. Stay proactive. Keep track of ARIA spec updates and screen reader changelogs.
Conclusion

Web accessibility isn’t static. Staying ahead of emerging ARIA implementation trends helps developers build experiences that are not just compliant, but genuinely inclusive. Attributes like aria-errormessage, aria-description, and editorial roles like role="comment" signal the future of accessible interaction.

Many of these features may still be waiting for widespread support—but early adoption by thoughtful developers will shape best practices and standards moving forward.

To lead with confidence in this evolving space, consider scheduling an ADA briefing with 216digital. Their accessibility experts can help you implement forward-looking ARIA features in a way that’s both robust and user-first—positioning your organization as a leader in inclusive design.
Greg McNeil

June 6, 2025

How-to Guides

Accessibility, ARIA, How-to, WCAG, WCAG Compliance, web developers, web development
ARIA Alert 101: Loud, Clear, and Accessible
If you’ve built interactive web apps, you know how crucial timely feedback is for a good user experience. But here’s something developers often overlook: what about users who rely on assistive technologies like screen readers? For them, getting real-time notifications isn’t just convenient—it’s essential. That’s exactly why understanding how to use an ARIA alert matters.

This guide breaks down what ARIA alerts are, how they work, where they shine, and how to implement them correctly—without overwhelming users or creating redundant announcements.

What Exactly Is an ARIA Alert?

An ARIA alert is your app’s way of tapping a screen reader user on the shoulder. By using role="alert", you’re signaling that the content inside that element is critical and should be announced immediately—without needing to move focus or interaction.

Technically, role="alert" behaves the same as setting aria-live="assertive" and aria-atomic="true". That means:
- The content update will be read aloud right away.
- The entire updated region will be announced, not just the changed portion.
Use it when urgency matters—like an error message or a warning about a session timeout.

How ARIA Alerts Actually Work (And Why They Can Be Tricky)

For an ARIA alert to trigger, it must announce a change. If you statically load a message with no updates, nothing will happen—even if you’ve assigned role="alert".

Here’s the trick: the alert container must exist in the DOM when the page loads, and its content must change dynamically. You can do this by:
- Inserting new text into the container.
- Revealing text that was previously hidden with CSS (e.g., display: none → display: block).
A reliable pattern is to preload an empty alert container, then inject or unhide content as needed. This ensures assistive tech is “watching” the region.

Real-World Scenarios for Using ARIA Alerts

Let’s look at some common, effective use cases:
- Form validation: “Oops! Please enter a valid email.”
- Session timeouts: “You’ll be logged out in 1 minute.”
- Connection issues: “Unable to save changes—check your connection.”
Here’s an updated practical implementation using best practices:
```
<div role="alert" aria-live="assertive" aria-atomic="true" id="email-alert"></div>
<form id="contactForm">
  <label for="email">Email:</label>
  <input type="email" id="email-input" placeholder="Enter email">
  <button type="submit" onclick="validateEmail(event)">Submit</button>
</form>
<script>
function validateEmail(event) {
  event.preventDefault();
  const email = document.getElementById('email-input').value;
  const alertBox = document.getElementById('email-alert');
  alertBox.textContent = ''; // Clear previous message
  if (!email.includes('@')) {
    // Trigger update
    alertBox.textContent = 'Please provide a valid email address.';
  }
}
</script>
```
Pro tip: Clearing the alert content first helps some screen readers recognize the change reliably.

alert vs. alertdialog: Know the Difference

Use role="alert" for passive, immediate notifications that require no interaction. But if your message needs a user response—like confirming an action or acknowledging a warning—role="alertdialog" is a better fit.

It shifts focus into the alert and keeps the user there until they respond—perfect for time-sensitive prompts.

When Another Role Fits Better

ARIA alerts aren’t the only live region role. Use the right tool for the right job:
- Use role="status" for passive, non-urgent updates, such as “Settings saved.”
- When presenting chat logs or continuously updating feeds, apply role="log".
- Countdowns or ticking clocks are best served with role="timer".
- For moving text like stock tickers or news crawls, assign role="marquee".
This prevents alert fatigue and keeps your UI meaningful and calm.

Best Practices for ARIA Alerts

To ensure your ARIA alert implementation actually helps users, keep these principles in mind:
- Avoid using aria-live="assertive" on top of role="alert" — it’s redundant and may cause double announcements.
- Don’t assign role="alert" to the trigger (like a button); apply it to the message container.
- Avoid focusing the alert — screen readers will announce it automatically.
- Leave the container empty at first — content must be injected or toggled dynamically to trigger an announcement.
Here’s an example using a hidden alert message:
```
<div role="alert">
  <span id="error-message" style="display:none; color:red;">Please provide a valid email address.</span>
</div>
<script>
function submitForm(event) {
  event.preventDefault();
  const emailField = document.getElementById('email');
  const errorMessage = document.getElementById('error-message');
  if (!emailField.value || !emailField.value.includes('@')) {
    errorMessage.style.display = 'block';
  } else {
    errorMessage.style.display = 'none';
    alert('Form submitted successfully');
  }
}
</script>
```
Common Pitfalls (and How to Fix Them)
- Too many alerts: It’s tempting to ARIA-ify everything, but overusing alerts overwhelms users. Use sparingly and meaningfully.
- Alerts that vanish too quickly: Follow WCAG 2.2.3 (AAA) recommendations and give users enough time to absorb information—especially at slower screen reader speeds.
- Missing initial DOM presence: Screen readers may not monitor the alert region if developers add it after the page loads and it wasn’t in the initial DOM.
- Static content: No matter the role, alerts only fire when content updates. Don’t forget to trigger a change—whether inserting, revealing, or replacing content.
Advanced Tips to Polish Your ARIA Alerts

Reuse One Container

Don’t overcomplicate things with multiple regions. Instead, keep a single reusable alert container:
```
const alertContainer = document.getElementById('reusable-alert');
alertContainer.textContent = '';
setTimeout(() => {
  alertContainer.textContent = 'Your session will expire soon!';
}, 50);
```
The slight delay ensures screen readers detect the change.

Hidden Alerts for Assistive Tech Only

Sometimes, users with screen readers need information that sighted users don’t. You can use visually hidden alerts to serve that audience without affecting your UI:
```
<div role="alert" class="visually-hidden">
  Background task completed successfully.
</div>
```
This preserves visual clarity while maintaining inclusivity.

Testing: Manual Beats Automated

While tools like Lighthouse are helpful, automated testing can’t catch everything. To verify ARIA alert functionality:
- Use screen readers directly (NVDA, JAWS, VoiceOver).
- Test updates dynamically—don’t rely on static behavior.
- Confirm timing, visibility, and repeatability.
Get feedback from real users whenever possible.

Make Critical Updates Count With ARIA Alerts

An ARIA alert isn’t just a technical fix—it’s a way to respect your users’ need for timely, clear communication. When implemented well, it’s like adding a layer of empathy to your UI. You’re saying, “Hey, I’ve got your back—even if you can’t see what’s on the screen.”

If you’re unsure whether your alerts are firing at the right moments—or want expert help ensuring your digital experience is accessible—connect with the team at 216digital. We offer accessibility audits, developer guidance, and hands-on remediation services tailored to your site.

Let’s make accessibility loud, clear, and effective—together.
Greg McNeil

June 5, 2025

How-to Guides

Accessibility, ARIA, ARIA alert, How-to, web developers, web development, Website Accessibility

What ARIA Is—and What It’s Supposed to Do

When Is It Necessary?

Why It Shouldn’t Be the Default Tool

Common ARIA Misuse That Breaks Accessibility

Why ARIA Usage Correlates with More Errors

The Real Fix: Manual Testing and Developer Discipline

Testing It in the Real World

Build a Feedback Loop Into the Dev Process

Practical Guidelines for Responsible ARIA Use

ARIA Isn’t a Shortcut—It’s a Responsibility

Understanding Success Criterion 3.2.1 – On Focus

Why On Focus Matters

Common Pitfalls (and Why They Break On Focus)

How to Achieve Compliance (and Design a Better Experience)

Testing Strategies for On Focus

Manual testing

Assistive Technology Testing

Automated Checks

Bad vs. Good: Concrete Examples

Bad: Form Submits on Focus

Good: Form Submits Only on Activation

Bad: Navigation on Focus

Good: Navigation Only on Activation

Good Example: Custom Control with Predictable Focus

Frequently Asked Questions

Build Predictable Experiences (and Trust)

Understanding SVG Accessibility Fundamentals

Why SVGs Can Be Great for Accessibility

Decorative vs. Informative SVGs: Know the Difference

Decorative SVGs

Informative SVGs

Choosing the Right Pattern: Inline vs. External

Inline SVG (Best for Control and Accessibility)

External SVG via <img src="...">

Best Practices for Accessible SVGs

Add Accessible Text

Contrast & Readability

Don’t Use Color Alone

Focus and Keyboard Navigation

Use ARIA Thoughtfully

Inherit Color Responsively

Sprite Systems (<use>) and Symbols

Testing SVG Accessibility: Don’t Skip This Step

Quick Checklist

Tools & Methods

Common Pitfalls (and Easy Fixes)

Using SVG as a CSS Background for Meaningful Content

Forgetting to Label Icons

Overwriting Contrast With Themes

Unlabeled Charts

Interactive SVG Shapes Without Semantics

Practical Patterns You Can Copy

Informative Standalone Icon (Inline SVG)

Decorative Icon Inside a Button (Button Provides the Name)

Chart With Long Description and Data Table

Accessibility for Motion and States

Accessible Design is Intentional Design

Need a Second Set of Eyes?

What Are Keyboard Traps?

Who’s Affected (And Why You Should Care)

Where Keyboard Traps Hide

Modals, Popovers, and Dialogs

Forms and Custom Inputs

Media Players

JavaScript-Enhanced Links

Testing for Keyboard Traps

Best Practices for Trap-Safe Code

A Safe Dropdown in Action

Build Trap Prevention into Your Workflow

Focus on What Matters

What Makes an Image “Decorative”?

Common Decorative Image Types

Making the Right Call: Informative or Decorative?

How to Properly Mark Decorative Images in Code

Use an Empty Alt Attribute

Use role="presentation" or aria-hidden="true"

What’s the Difference?

Best Practices & Pitfalls to Avoid

Why It Matters: The Impact of Doing It Right

Beyond Alt Text: Decorative Images Are Just One Part

External SVG via `<img src="...">`

Sprite Systems (`<use>`) and Symbols

Use `role="presentation"` or `aria-hidden="true"`