DEV Community: a11ySolutions

Your Website Has an Index. AI Agents Can't Navigate Without It.

a11ySolutions — Fri, 10 Jul 2026 13:36:21 +0000

Try finding one specific fact in a 400-page book with no index. You'll get there eventually, page by page. You'll also waste time, get tired, and maybe give up before you find it.

With an index, the experience changes completely: check the table of contents, jump to the right chapter, done.

Web pages have their own index. It's called the accessibility tree, and it's the structure both screen readers and AI agents use to navigate a site. Neither of them sees your rendered layout. They see the tree.

The tree is built from code decisions
Every part of the tree maps to something you write:

Headings give the page a table of contents. A logical h1 to h3 hierarchy tells the user, or the agent, what's on the page and in what order.

Labels explain what controls do. A button that reads "Submit" in context means nothing out of context. aria-label="Submit booking request" carries the meaning with it.

Alt text is the only description of an image that exists in the tree. Empty alt on a meaningful image means the image doesn't exist for anyone reading the tree.

Link text says where an action leads. "Click here" is a dead end when you can't see the surrounding layout.

What happens when the tree is broken

Here's the part that gets oversimplified. A broken tree doesn't always mean the agent fails outright. Often it means the agent brute-forces its way through, and that's worth understanding.

Without headings, the agent can't jump to the right section. It has to process the entire page to orient itself.

Without labels, it can't know what a control does. It has to guess and act. Sometimes it catches the mistake and retries; sometimes it never realizes it clicked the wrong thing. Research on web agents documents both behaviors: grounding errors where agents fail to identify the intended element, and agents getting stuck in loops without recovering.

Without semantic buttons and real links (looking at you, div with an onclick), it can't reliably identify what's interactive at all.

Sometimes the agent still completes the task. But every extra step adds latency, adds compute, and adds error surface: the wrong button, the wrong field, the task that silently ends up half done. Finding the information is not the same as completing the task. And completing it late, with errors, or halfway isn't completing it either.

Exactly like the book with no index. You might find the page. You arrived late, tired, and with no guarantee you read the right one.

The usual suspects

The tree almost never breaks for exotic reasons. It breaks on the basics:

Divs styled to look like buttons, with no role and no keyboard handling. Pages with no heading hierarchy, just styled text. Meaningful images with empty or missing alt attributes. Links with no href, wired entirely through JavaScript click handlers. Custom form controls that never expose their state.

Each one is a small decision at code review time. Together they decide whether your site is navigable by anything that isn't a sighted human with a mouse.

This is not a new standard

Nobody needs "AI readiness" guidelines. The spec already exists: semantic HTML, proper heading structure, real labels, real buttons, real links, keyboard operability. It's WCAG, applied to a new class of user.

Which means teams that already treat accessibility as core engineering practice didn't prepare for AI agents. They built for humans correctly, and the agents inherited the benefit.

One line of CSS that breaks keyboard accessibility sitewide and two other patterns we keep finding in audits

a11ySolutions — Wed, 01 Jul 2026 10:09:18 +0000

Last week we ran accessibility audits across multiple sites. Different industries, different tech stacks, different teams.

The same three problems kept showing up.

Not similar problems. The exact same patterns, reproduced independently, causing the same failures for keyboard users and screen reader users across every site we reviewed.

That's what makes these worth documenting. When something appears consistently across unrelated projects, it's not a coincidence, it's an industry-wide gap in how accessibility gets implemented.

This article covers the three patterns, the exact code behind each one, and the fix. No abstractions.

PATTERN 1 — One line of CSS that removes focus indicators sitewide
Heading: The most common keyboard accessibility failure we see: outline: none

This is the one that surprises people the most, because it's so small.

A developer adds this somewhere in the global stylesheet, usually to clean up the default browser focus ring, which can look inconsistent across browsers:

a:focus {
outline: none;
}

button:focus {
outline: 0;
}

Sometimes it's scoped to a component. Sometimes it's applied globally. Either way, the result is the same: every keyboard user navigating your site loses their only visual indicator of where they are on the page.

Tab still works. Focus is still moving. The user just can't see it.

For someone navigating with a keyboard due to a motor disability, this is the equivalent of removing the cursor from a mouse user's screen. They can keep clicking, but they have no idea where.

This fails WCAG 2.4.7 (Focus Visible) and WCAG 2.4.11 (Focus Appearance) at the AA level.

The fix:
Don't remove the outline. Style it instead.

css
/* Remove this */
a:focus { outline: none; }
button:focus { outline: 0; }

/* Replace with this */
:focus-visible {
outline: 2px solid #0057b7;
outline-offset: 2px;
}

Using :focus-visible instead of :focus gives you the best of both worlds: the focus indicator appears for keyboard navigation but not for mouse clicks, which is the behavior most design systems want. The browser handles the distinction natively.

Two things to verify after applying this fix: the outline color meets a 3:1 contrast ratio against the adjacent background (WCAG 1.4.11), and the outline is visible against both light and dark backgrounds if your site uses both.

One line caused the problem. One rule fixes it sitewide.

PATTERN 2 — Interactive elements built with the wrong HTML that never enter the tab order

Heading: If it's not natively focusable, keyboard users can't reach it

This one appears most often in navigation components, menus, toggles, icon buttons, where a developer reaches for a <div> or an <a> without an href because it felt like the right container for the visual design.

Here's a real pattern we documented. A hamburger menu trigger built like this:

html
<a class="nav-btn js-nav-btn-menu" data-toggle="dropdown" data-display="static">
<svg width="26" height="26" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M1.71436 14.8571H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
<path d="M1.71436 25.1428H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
<path d="M1.71436 4.57141H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
</svg>
</a>

The problem: an <a> element without an href attribute is not focusable by default. It exists in the DOM, it's visible on screen, it works with a mouse click via JavaScript, but Tab navigation skips it entirely.

The SVG has no role, no accessible name, no keyboard interaction. A keyboard user cannot open the navigation menu at all. On a mobile-first site where this menu is the primary navigation, that's a complete blocker.

This fails WCAG 2.1.1 (Keyboard) at the AA level.

The fix:
Use a native element. It's focusable by default, activatable with Enter and Space, and requires no extra ARIA to work correctly:

html
<button class="nav-btn js-nav-btn-menu" aria-expanded="false" aria-controls="main-nav" aria-label="Open navigation menu">
<svg width="26" height="26" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
<path d="M1.71436 14.8571H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
<path d="M1.71436 25.1428H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
<path d="M1.71436 4.57141H30.2858" stroke="#003680" stroke-width="2" stroke-linecap="round"/>
</svg>
</button>

javascript
const navBtn = document.querySelector('.nav-btn');
const mainNav = document.getElementById('main-nav');

navBtn.addEventListener('click', () => {
const isExpanded = navBtn.getAttribute('aria-expanded') === 'true';
navBtn.setAttribute('aria-expanded', !isExpanded);
mainNav.hidden = isExpanded;

// Update label to reflect current state
navBtn.setAttribute('aria-label',
isExpanded ? 'Open navigation menu' : 'Close navigation menu'
);
});

Three things the fix adds that the original lacked: native keyboard focus, a name that screen readers can announce, and a state (aria-expanded) that tells assistive technology whether the menu is open or closed.

The SVG gets aria-hidden="true" and focusable="false" because the button's aria-label already provides the accessible name, the icon is decorative in this context.

PATTERN 3 — Form controls that are visually present but keyboard-unreachable

Heading: The form field keyboard users cannot interact with — even when it looks completely normal

This pattern is the most damaging from a conversion standpoint, because it appears inside forms — the exact flows where users need to complete a transaction, submit a request, or finish a registration.
The specific case we documented: a date of birth selector in a quote request form. Visually it renders as a date picker. Functionally it's implemented like this:

html

Select date of birth

The

has no tabindex, no role, no keyboard event handlers. Tab skips it. Enter does nothing. The type="hidden" input is intentionally invisible to the browser's accessibility tree.

A keyboard user reaches this step and has no way forward. The form cannot be completed. This fails WCAG 2.1.1 (Keyboard) at the Critical severity level, it's not a degraded experience, it's a complete blocker.

This specific pattern appears frequently in date pickers, custom dropdowns, color pickers, and any component where a developer uses a hidden input to store the value while a custom UI element handles the visual presentation. The custom UI element almost never has keyboard support.

The fix:
The trigger needs to be a real interactive element with keyboard support, an accessible name, and ARIA attributes that communicate its current state:

html
id="dob-trigger"
aria-haspopup="dialog"
aria-label="Date of birth, no date selected"
aria-expanded="false">
Select date of birth

type="text"
id="dob-field"
name="dob"
aria-label="Date of birth"
placeholder="MM/DD/YYYY"
autocomplete="bday">

javas
criptconst dobTrigger = document.getElementById('dob-trigger');
const dobField = document.getElementById('dob-field');

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

function onDateSelected(date) {
const formatted = formatDate(date); // e.g. "06/15/1990"
dobField.value = formatted;

// Update the trigger label to reflect selection
dobTrigger.setAttribute(
'aria-label',
Date of birth, ${formatted} selected. Press Enter to change.
);

// Return focus to trigger after selection
dobTrigger.focus();
}

The key principle: whatever value the user selects must be reflected in the accessible name of the trigger, so screen reader users know what they've chosen without having to navigate away from the component.

If you're using a third-party date picker library, check whether it exposes keyboard navigation and ARIA attributes before integrating it. Most don't by default.

WHY THESE THREE KEEP APPEARING
These aren't obscure edge cases. They're the result of three patterns that are extremely common in how front-end development gets prioritized:

The focus indicator gets removed because the default browser outline "looks bad" and replacing it properly gets deprioritized. The accessible name and keyboard support get skipped because the component works visually and passes a quick manual click-through. The form control gets built with a hidden input because that's the easiest way to decouple the visual presentation from the data layer, and accessibility testing never reaches the keyboard interaction path.

None of these are malicious decisions. They're prioritization gaps, and they compound: a site with all three patterns effectively locks out every keyboard user from navigating, finding the menu, and completing a form.

WHAT STATIC SCANNERS WON'T CATCH
axe and Lighthouse will flag missing alt text and low color contrast reliably. They will not catch any of the three patterns above.

The outline: none rule sits in CSS, scanners don't simulate keyboard navigation to verify whether focus is visible. The <a> without href may not trigger a violation depending on how the tool evaluates focusability. The hidden input pattern passes most automated checks because the element is intentionally hidden and the visible trigger has no semantic role to flag.

Manual keyboard testing, Tab through every interactive element, verify focus is visible, verify every control responds to Enter and Space — is the only reliable way to catch these.

If you want to run a quick check on a live URL without a full manual audit, A11yDetector navigates tab by tab and surfaces exactly this class of issue: a11ysolutions.com/detector

Three different sites. Three different stacks. The same three failures.

Keyboard accessibility breaks in predictable ways. The patterns are consistent enough that once you know what to look for, you'll spot them in minutes on almost any site you audit.

The fixes are equally consistent: use semantic HTML, don't suppress focus styles, and test with a keyboard before shipping.

Why your accessibility tree is now your AI strategy

a11ySolutions — Wed, 24 Jun 2026 09:52:42 +0000

Most developers think of accessibility as a checklist. WCAG compliance. Screen reader support. Alt text on images.
That framing is outdated.

Here's what's actually happening in 2026: AI agents like ChatGPT, Gemini, and Perplexity don't read your website the way a sighted user does. They walk your DOM. They parse your ARIA roles, your heading hierarchy, your semantic HTML.

Sound familiar? It should. That's exactly what a screen reader does.
The accessibility tree you build for users with disabilities is the same structure an AI agent relies on to navigate, extract information, and complete tasks on a user's behalf.

95.9% of websites have detectable WCAG failures. (WebAIM, 2026)
That means 95.9% of websites are also partially invisible to AI-driven discovery.

The fix is the same for both:

Semantic HTML first
Correct heading hierarchy
Meaningful alt text
Proper ARIA labels
Keyboard-operable interactions

We explored this in depth with Zammo.ai in a piece we co-authored on why digital accessibility is now also an AI strategy.

https://www.a11ysolutions.com/blog/why-digital-accessibility-is-an-ai-strategy/

How I cut accessibility remediation time by 70% without leaving VS Code

a11ySolutions — Thu, 18 Jun 2026 14:24:38 +0000

The problem

Every time I found an accessibility issue in a PR review, the same thing happened: tab out to the WCAG docs, figure out the right fix, come back to the code, apply it, re-verify. For every single issue.

It wasn't hard work. It was repetitive work. And it was eating hours every sprint.

What we built

A11yResolver is a VS Code extension that brings that entire loop inside the editor.

It runs as an AI agent. It flags WCAG issues in context, not as static linting, but understanding the component and what it produces. Then it suggests a standards-based fix you can review as a diff and apply with one click.

The two modes

Issues Resolver Fast — the everyday one. Missing labels, non-semantic buttons, form field associations, basic keyboard support. Quick iteration, lower cost.

Issues Resolver Expert — for the harder stuff. Focus traps, dynamic ARIA states, live regions, complex multi-step flows. More reasoning power for the edge cases.

Start with Fast. Switch to Expert when it can't fully resolve something.

What surprised me

It validates fixes through real browser interaction, not just code analysis. It actually simulates keyboard navigation and checks that focus management works correctly. That's the part most tools skip.

Setup

Install from the VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=A11YSolutions.a11y-resolver-vscode-chat
Open the A11yResolver panel from the sidebar
Add your OpenRouter API key (stored in VS Code secrets, never sent to A11ySolutions)
Point it at any component

Your own API key means you pay the token cost directly, no markup, no subscription for the AI part. Free during beta.

Results

In the projects where we've tracked it: 50–70% less time on repetitive remediation. The gain isn't speed, it's not doing the work twice.

Try it

→ VS Code Marketplace
→ Full demo
→ Product page

Questions welcome in the comments.

Your accessibility fixes are good. But do you know what they're worth?

a11ySolutions — Fri, 29 May 2026 10:43:23 +0000

YI put together a visual breakdown of this concept as a LinkedIn carousel — check it out here before diving into the full article.our accessibility fixes are good. But do you know what they're worth?

The audit is not the full picture

You've run the audit. Fixed the contrast ratios. Added the missing alt text. Resolved the keyboard trap on that modal that's been broken for six months.

WCAG compliance is checked. The report is clean.

And then someone from product or leadership asks:

"Great, but what did that actually do for the business?"

Most developers don't have a good answer to that question. Not because the work isn't valuable, it is, but because no one built the bridge between the technical fix and the business outcome.

This article is that bridge.

The drop-offs your analytics will never show you

Accessibility failures are invisible to standard tracking. They happen before the click, before the form event fires, before any tracker registers them.

A broken focus trap on a modal. A form that doesn't announce errors to screen readers. A date picker that keyboard users simply can't complete.

These aren't just WCAG failures. They're conversion failures.

The math is straightforward

What changes when you improve accessibility is the effective conversion rate — because you're removing friction that was silently blocking a portion of your users from completing the flow.

Industry studies consistently show conversion uplifts in the range of 10–14% after focused accessibility remediation on critical flows. Support ticket volume drops. Abandonment in key steps decreases.

We built a free ROI calculator that takes exactly those inputs and returns a projected revenue impact based on verified industry data.

👉 Calculate the ROI of your accessibility work

No sign-up. No pitch. Just your number.

Why this matters beyond the ticket

If you're a developer who cares about accessibility, and if you're reading this, you probably do — you already know the work is worth doing.

But knowing how to communicate its value to a product manager, a CTO, or a leadership team is a different skill. And it's one that determines whether accessibility stays a priority after the first audit, or gets deprioritized when the next quarter's roadmap fills up.

Run the calculator before your next sprint review. Share the number with your product lead. It's a two minute exercise that can change how accessibility is resourced on your team.

The takeaway

Accessibility fixes reduce friction. Reduced friction improves conversion. Improved conversion is measurable revenue.

The chain is direct. Most teams just never close the loop.

Now you can.

👉 a11ysolutions.com/roi-calculator

3 accessibility failures we find in every fintech onboarding flow.

a11ySolutions — Tue, 26 May 2026 09:54:50 +0000

We audited several fintech onboarding flows this quarter. Different companies, different stacks, different teams.

Same three issues. Every time.

None of them appeared in automated scans. All of them showed up in the first 30 minutes of expert review. Here's what they are and how to fix them.

Issue #1 — Email field with no visible label

The field looks fine visually. There's placeholder text that says "Enter your email." But there's no <label> element connected to it.

For a screen reader user, the field is either announced without context or skipped entirely.

The fix:

If you can't modify the label structure, use aria-label as a fallback:

How to test with NVDA + Chrome:
Tab into the field. NVDA should announce "Email address, edit text." If it announces only "edit text" or nothing, you have this issue.

Issue #2 — Password validation that disappears
The error message appears when the user types a weak password, then vanishes after a second. Sighted users catch it. Users with low vision or screen readers miss it entirely.

The fix is to use aria-live so assistive technology announces the message when it appears:

Then inject the validation message into that container via JavaScript. The screen reader will announce it automatically.

How to test:
Trigger the validation error. If NVDA doesn't announce the message out loud, you have this issue.

Issue #3 — Continue button unreachable via Tab on mobile
The button exists in the DOM. It looks tappable. But keyboard and switch access users on mobile can't reach it because focus order is broken or the element isn't natively focusable.

The fix:
Use a native <button> element instead of a styled <div> or <span>. Native buttons are focusable and keyboard-operable by default.

If you must use a custom element, add tabindex="0" and handle keyboard events explicitly.

How to test:
On mobile, connect a Bluetooth keyboard. Tab through the form. If you can't reach the Continue button, you have this issue.

Quick checklist before you ship an onboarding flow

Every input has a visible, connected <label>
Error messages use aria-live or role="alert"
All interactive elements are reachable via Tab
No action depends exclusively on placeholder text
The flow is testable with NVDA or VoiceOver in under 10 minutes

These issues don't show up in automated scans.
Automated tools check structure. They don't simulate how a real user navigates with a screen reader, a keyboard, or a switch device. That's what expert audits are for.

If you want to know whether your onboarding has these issues, start here.

Your accessibility fixes are good. But do you know what they're worth?

a11ySolutions — Thu, 21 May 2026 09:04:28 +0000

I put together a visual breakdown of this concept as a LinkedIn carousel -https://www.linkedin.com/feed/update/urn:li:activity:7463121450070212609 before diving into the full article.

The audit is not the full picture

You've run the audit. Fixed the contrast ratios. Added the missing alt text. Resolved the keyboard trap on that modal that's been broken for six months.

WCAG compliance is checked. The report is clean.

And then someone from product or leadership asks:

Great — but what did that actually do for the business

Most developers don't have a good answer to that question. Not because the work isn't valuable, it is, but because no one built the bridge between the technical fix and the business outcome.

This article is that bridge.

The drop-offs your analytics will never show you

Here's something worth understanding about accessibility failures: most of them are invisible to standard tracking.

When a screen reader user hits a form that doesn't announce validation errors, they don't trigger an error event. They just stop. When a keyboard user encounters a focus trap inside a modal they can't escape, there's no rage click, no heatmap signal, no session recording that captures what happened.

They leave. Quietly. Before your funnel even starts.

This is the category of lost revenue that never appears in any dashboard, and it's directly caused by inaccessible components.

A broken aria-live region. A missing role="alert". A date picker built without keyboard support. A checkout button that's visually styled but not semantically a button.

These aren't edge cases. They're patterns that repeat across almost every production codebase.

Accessibility barriers are conversion failures

The framing matters here.

When you fix a focus management issue, you're not just passing a WCAG 2.1 success criterion. You're removing a barrier that was preventing a subset of your users from completing a critical task, booking, purchasing, registering, submitting.

That subset is larger than most teams assume. It includes users with permanent disabilities, but also users on keyboard-only setups, users with temporary injuries, power users who tab through forms, and older users who rely on larger text and higher contrast.

When that barrier is removed, task completion goes up. And task completion is conversion.

The technical fix and the business outcome are the same event, most teams just never measure them together.

How to calculate what your accessibility work is actually worth

This is where it gets concrete.

The variables that determine the revenue impact of accessibility remediation are the same variables your analytics team already tracks:

Monthly traffic, conversion rate, average order value, and industry sector.

What changes when you improve accessibility is the effective conversion rate, because you're removing friction that was silently blocking a portion of your users from completing the flow.

We built a free ROI calculator that takes exactly those inputs and returns a projected revenue impact based on verified industry data, not generic estimates, but numbers calibrated to your traffic, your conversion rate, and your sector.

👉 Calculate the ROI of your accessibility work -https://www.a11ysolutions.com/roi-calculator/

No sign-up. No pitch. Just your number.

Why this matters beyond the ticket
If you're a developer who cares about accessibility, and if you're reading this, you probably do, you already know the work is worth doing.

The ROI calculator doesn't replace your expertise. It gives your work a language that the rest of the organization understands.

Run it before your next sprint review. Share the number with your product lead. It's a two-minute exercise that can change how accessibility is resourced on your team.

The takeaway

Accessibility fixes reduce friction. Reduced friction improves conversion. Improved conversion is measurable revenue.

The chain is direct. Most teams just never close the loop.

Now you can.

👉 https://www.a11ysolutions.com/roi-calculator/

Accessible error messages: the patterns that work across JAWS, NVDA and VoiceOver

a11ySolutions — Mon, 18 May 2026 11:36:38 +0000

You added aria-live="assertive". You set aria-invalid="true". You tested in Chrome with a mouse.

The error message works perfectly.

Then a JAWS user fills out your form and hears... nothing useful. Or worse,they hear the error, but by the time they navigate back to the field, the message is gone.

Two real cases from audits that show exactly where this breaks.

Case 1: The toast that disappeared before the user could act
An e-learning platform displayed validation errors as auto-dismissing toasts with data-delay="8000". Eight seconds sounds reasonable until you map what a screen reader user actually needs to do: hear the announcement, understand the error, navigate back to the field, correct it, re-submit. On a complex form, that's not enough time, and the message was gone before they could act.

WCAG failure: SC 2.2.1 — Timing Adjustable. Any time limit must be removable or adjustable. An 8-second toast carrying critical error information fails outright.

Fix: don't use auto-dismissing toasts for errors. Toasts work for redundant, low-stakes notifications. Not for information the user needs to act on. Display errors inline, adjacent to the field, and keep them visible until the user corrects the input.

Case 2: The error that vanished when focus left the field
A form showed the error while the field was focused, but an onblur listener hid the container the moment the user tabbed away. The screen reader announced only "invalid entry." No explanation, no guidance.

Two bugs in one component. First, the message disappeared on blur, so any user who tabbed to the next field and back found it gone. Second, there was no aria-describedby linking the error text to the input,so even when the message was visible, JAWS and NVDA had no reason to read it on focus.

With aria-describedby in place, JAWS, NVDA and VoiceOver all read the error automatically when the field receives focus. Remove the blur handler. Errors should persist until the user successfully corrects the field.

Both bugs come down to the same root cause: errors that aren't persistent and aren't programmatically connected to their field. Fix those two things and you cover the vast majority of screen reader failure modes on form validation.

What patterns are you using for error handling? Curious if anyone's hit edge cases with VoiceOver + Safari on iOS, that combination still has quirks worth discussing.

Focus indicators that fail WCAG 1.4.11: real cases and exact fixes

a11ySolutions — Wed, 13 May 2026 08:52:26 +0000

What is a focus indicator — and why does WCAG regulate it?

When a user navigates a website using a keyboard, they need to know where they are on the page at all times. The focus indicator is the visual signal that answers that question: the outline, highlight, or state change that appears on the element currently receiving keyboard focus.

WCAG Success Criterion 1.4.11 (Non-text Contrast) requires that the visual presentation of UI components, including focus and hover indicators, has a contrast ratio of at least 3:1 against adjacent colors.

Without a sufficient focus indicator:

Keyboard-only users lose their place on the page.
Users with low vision cannot perceive the current focus state.
The product fails a Level AA audit, the standard required by the EAA, ADA, and EN 301 549.

Below are three real cases from accessibility audits, extracted from a structured issue bank. No simulated data. No approximations.

Case 1 — Login page: Dropdown focused/hovered option
Component: "Tipo de documento" dropdown — focused and hovered option state
Audit type: Color Contrast · Priority: High

What was found:
When the dropdown expanded and the user hovered or focused an option, the selected state was communicated only through a light grey background. There was no outline or other indicator with sufficient contrast.

The CSS driving the problem:

.css-1kwd9xn-option {
background-color: rgb(241, 244, 244); /* #F1F4F4 */
color: rgb(0, 43, 69);
font-size: 14px;
font-weight: normal;
}

A ratio of 1.1:1 means the focused state is virtually indistinguishable from the default state. For a user with low vision navigating with a keyboard, the dropdown is effectively unusable.

The fix:
Replace the near-white background with a grey that achieves the required 3:1 threshold against the white page background.
css/* Before /
.css-1kwd9xn-option {
background-color: rgb(241, 244, 244); / ratio 1.1:1 — FAIL */
}

/* After /
.css-1kwd9xn-option:hover,
.css-1kwd9xn-option:focus {
background-color: #939393; / ratio 3.0:1 against #FFFFFF — PASS */
}

Case 2 — Login page: Password digit field borders
Component: Input field boundaries — digit fields for password entry
Audit type: Color Contrast · Priority: Medium

What was found:

The password entry screen used a series of individual digit input fields. Each field had only a bottom border as its visible boundary — the indicator that communicates "this is an input". That border failed the 3:1 contrast requirement against the white background.

WCAG 1.4.11 applies not only to focus rings but to any visual indicator that communicates the presence or boundary of an interactive component. A field border that a user cannot see means they cannot locate the input.

The fix:
Use a darker grey for the border that maintains the visual style while meeting the threshold.

css/* Before /
.password-digit-field {
border-bottom: 1px solid #CCD5DA; / ratio 1.48:1 — FAIL */
}

/* After /
.password-digit-field {
border-bottom: 1px solid #8094A3; / ratio 3.14:1 — PASS */
}

Case 3 — Account page: Radio button borders
Component: Radio button visual boundaries — payment method selection
Audit type: Color Contrast · Priority: Low

What was found:
A payment method selection screen presented a group of radio buttons for choosing between credit cards. The unchecked radio buttons used a light grey border to indicate their boundary. That border failed 3:1 against the white background.

When radio button borders are invisible, users with low vision cannot detect that a selectable option is present. This is a form usability failure, not just an aesthetic one: invisible controls block task completion.

The fix:
css/* Before /
.sc-radio-field-label:before {
border: 0.0625rem solid #C2CFD6; / ratio 1.59:1 — FAIL */
}

/* After /
.sc-radio-field-label:before {
border: 0.0625rem solid #949494; / ratio 3.03:1 — PASS */
}

What these three cases have in common
All three failures share the same root cause: grey UI elements on white backgrounds, where the grey is not dark enough to reach 3:1.

This pattern is extremely common in design systems that prioritize subtle, minimal aesthetics. The visual result feels clean. The accessibility result is that a significant portion of users cannot perceive the interface.

None of these fixes required redesigning the component. Each required changing one CSS color value.

Focus indicators failing WCAG 1.4.11: real cases and exact fixes

a11ySolutions — Tue, 12 May 2026 11:48:12 +0000

Focus indicators failing WCAG 1.4.11: real cases and exact fixes
What is a focus indicator?

A focus indicator is the visual signal that shows keyboard users which interactive element is currently focused.

WCAG 2.1 SC 1.4.11 (Non-text Contrast) regulates focus indicators because users navigating with a keyboard must clearly perceive where focus is located.

The minimum required contrast ratio for visible focus indicators is 3:1 against adjacent colors.

Why static accessibility tools often miss these issues

Most static accessibility scanners cannot reliably detect focus indicator failures because the :focus or :focus-visible state only exists during actual keyboard interaction.

To properly validate focus indicators, manual testing with the keyboard is required.

Usually:

Tab
Shift + Tab
Browser DevTools
Contrast analyzers
Real accessibility audit cases

Case 1 — Tourism company
The primary search button had a focus indicator with a contrast ratio below 3:1.

Problem

Keyboard users could technically navigate to the button, but the visible focus state was too subtle to perceive clearly.

WCAG failure
SC 1.4.11 — Non-text Contrast
Fix

Use a high-contrast outline with :focus-visible.

:focus-visible {
outline: 2px solid #FFFFFF;
outline-offset: 2px;
}

Case 2 — Educational platform

The “Login” button changed from #02959F to #027279 when focused.

Problem

Contrast between both visual states was only 1.57:1.

The component relied exclusively on color to communicate focus.

WCAG failures
SC 1.4.11 — Non-text Contrast
SC 1.4.1 — Use of Color
Fix

Add a visible outline independent of color changes.

:focus-visible {
outline: 2px solid #FFFFFF;
outline-offset: 2px;
}

Case 3 — Same platform

The “Remember me” checkbox used a black focus indicator (#212529) over a dark background (#1D191C).

Problem

Contrast ratio:

1.12:1

The focus state became nearly invisible.

Fix

Replace the focus indicator with:

outline: 2px solid #0297A2;
Results
4.92:1 against background
3.79:1 against adjacent colors

WCAG compliant.

How to test focus indicators properly

Recommended setup:

Chrome or Firefox
Keyboard navigation only
Colour Contrast Analyser (CCA)
Optional: NVDA or VoiceOver

Testing steps:

Navigate using only Tab
Verify focus is always visible
Measure contrast of the focus indicator
Validate zoom and dark mode scenarios
Quick production checklist

Before release, ask:

Can focus be identified immediately?
Does the indicator reach at least 3:1 contrast?
Does the state rely only on color changes?
Is focus still visible in dark mode?
Is it visible at 200% zoom?

Focus indicators are one of the most commonly overlooked accessibility failures in production systems, especially because many automated tools cannot fully detect them.

And yet, for keyboard users, they are critical navigation cues.

css #accessibility #wcag #webdev #a11y #focusvisible

Keyboard traps: what they are, how to reproduce them, and how to fix them

a11ySolutions — Mon, 11 May 2026 08:01:00 +0000

Definition of a keyboard trap according to WCAG 2.1 SC 2.1.2:

“If keyboard focus can be moved to a component using a keyboard interface, then focus can be moved away from that component using only a keyboard interface.”

Why can’t static accessibility tools detect it?

Because detecting a keyboard trap requires actual keyboard navigation — typically using the Tab key.

Real case (educational platform):

The login form contained a keyboard trap. When users activated the “Login” button with empty required fields, keyboard focus was completely lost. Keyboard only users could no longer identify where to continue.

Problematic HTML:

<input type="submit" name="commit" value="Entrar" class="btn btn-xchool btn-block mt-4" data-disable-with="Enviando...">

Solution:

Programmatically move focus to the error message’s “Close” button using focus().

Tested with Chrome + NVDA.

5 ARIA mistakes that make accessibility worse, not better

a11ySolutions — Wed, 06 May 2026 08:34:27 +0000

There's a rule in accessibility that doesn't get enough attention:

No ARIA is better than bad ARIA.

Adding ARIA attributes without understanding them doesn't help assistive tech, it actively misleads it. Here are the mistakes I find most often in real audits:

1. role="button" on a div — without keyboard support
If you give something a button role, screen readers announce it as a button.
Users expect to activate it with Space or Enter.
If your div only handles onClick, keyboard users get announced a button they can't press. Use <button>. That's what it's there for.

2. aria-label that duplicates visible text — badly
<button aria-label="Click here to submit the form">Submit</button>
Screen readers read the aria-label, ignoring "Submit". Now your button is "Click here to submit the form", verbose, inconsistent, and confusing in a list of controls.
If the visible label is accurate, you don't need aria-label.

3. aria-hidden="true" on focusable elements
Hiding something from the accessibility tree while leaving it focusable creates a ghost, keyboard users can tab to it, but screen readers announce nothing. That's worse than not hiding it at all.

4. aria-live on everything
aria-live="assertive" interrupts whatever the screen reader is doing to announce the update. Useful for critical alerts. Catastrophic for
status messages, loading indicators, or anything non-urgent.
Most of the time, aria-live="polite" is what you want, or nothing at all.

5. Decorative icons without aria-hidden
An icon inside a button with no aria-hidden forces screen readers to
announce the SVG path or file name alongside the button label.
<svg aria-hidden="true"> is two words. Use them.

No ARIA is better than bad ARIA.
Before reaching for it, ask if a native HTML element solves it first.

What ARIA mistakes do you see most in code reviews?