DEV Community: Denis Omerovic

React Accessibility Issues That Audits Keep Finding in Next.js

Denis Omerovic — Fri, 30 Oct 2026 07:14:45 +0000

Originally published at AccessGuard.

You inherit a React or Next.js build. The markup looks tidy, the components are typed, and Lighthouse is green. Then somebody tabs through it with a screen reader running, and the page changes without a word, a menu cannot be opened from the keyboard, and the "Saved" message never gets read out.

None of that is a markup typo. These are failures that come from how single page apps work: the browser no longer loads a new page, so everything it used to do for free on a page load is now your code's job. This guide lists what audits of React and Next.js sites keep finding, the WCAG criterion each one breaks, and the fix.

1. Route changes nobody hears

On a normal website, clicking a link loads a new document. The screen reader announces the new page title, and focus starts at the top. With client side routing, the URL changes and the content swaps, but the browser sees no page load. A screen reader user who pressed Enter on a link can be left on the same spot with no idea anything happened.

What Next.js does for you

Next.js ships a route announcer by default. Its documentation says it "looks for the page name to announce by first inspecting document.title, then the <h1> element, and finally the URL pathname" (Next.js docs, Accessibility). So the most common Next.js failure here is not a missing announcer. It is every page sharing one title, such as "Acme" on every route, so the announcer reads the same word after every click.

// Broken: every route has the same title, so every navigation announces "Acme"
export const metadata = { title: "Acme" };

// Fixed: a unique title per page, set in each page or layout (App Router)
export const metadata = { title: "Pricing - Acme" };

A plain React app with a client side router does not get an announcer from React itself. Check what your router provides, and if it provides nothing, add a visually hidden live region that receives the new page title after each navigation.

Where focus should land

The Next.js docs describe an announcement, not a focus move. Announcing the page helps, but focus can still sit on a link in a navigation that is no longer relevant, or fall back to the top of the document. WCAG 2.4.3 Focus Order asks that focus moves in an order that "preserves meaning and operability" (W3C, Understanding 2.4.3). A common, predictable fix is to move focus to the new page's main heading after a route change:

// Fixed: after navigation, move focus to the page heading
"use client";
import { useEffect, useRef } from "react";
import { usePathname } from "next/navigation";

export function PageHeading({ children }) {
  const ref = useRef(null);
  const pathname = usePathname();
  useEffect(() => { ref.current?.focus(); }, [pathname]);
  return <h1 ref={ref} tabIndex={-1}>{children}</h1>;
}

tabIndex={-1} lets the heading take focus from script without adding it to the tab order. Pick one rule and apply it on every route.

2. div onClick and the button it should have been

JSX makes it easy to put onClick on anything, so audits keep finding clickable divs, spans and icons. A mouse user cannot tell the difference. A keyboard user cannot reach the element, and a screen reader does not announce it as a control. That fails 2.1.1 Keyboard and 4.1.2 Name, Role, Value, which requires that for every user interface component "the name and role can be programmatically determined" (W3C, Understanding 4.1.2).

// Broken: no focus, no Enter or Space, announced as plain text
<div className="card__toggle" onClick={toggle}>
  <ChevronIcon />
</div>

// Fixed: a real button, with a name and its state
<button type="button" className="card__toggle" onClick={toggle}
        aria-expanded={open} aria-label="Show details">
  <ChevronIcon aria-hidden="true" />
</button>

Adding role="button" and tabIndex={0} to the div is the long way round: you then have to handle Enter and Space yourself, and the next developer will forget one of them. A native button does it all. If the thing goes somewhere, it should be a link instead; our guide on button vs link accessibility has the rule for choosing.

Start with shared components: one <IconButton> built on a div repeats the failure on every page, and one fix clears them all.

3. Styling by ARIA state, not by a separate state variable

A quieter bug: the component tracks isOpen in React state, sets a class from it, and sets aria-expanded from something else, or forgets to set it at all. The panel looks open, but a screen reader says "collapsed". 4.1.2 also requires that states set by the user can be programmatically determined, so a mismatch is a failure, not a nicety.

The fix is to make the ARIA attribute the single source the styling reads from. If the CSS keys off aria-expanded, the visual state and the announced state cannot drift apart, because a missing attribute shows up as a visual bug that someone will notice.

/* Broken: the look depends on a class the ARIA attribute never sees */
.disclosure--open .disclosure__icon { rotate: 180deg; }

/* Fixed: the look depends on the attribute screen readers read */
.disclosure__button[aria-expanded="true"] .disclosure__icon { rotate: 180deg; }

The same idea works with class-variance-authority (CVA) and Tailwind, which is a common setup in Next.js projects. Instead of a CVA variant like open: { true: "rotate-180" } driven by a prop, put the state on the element and let the classes respond to it. Tailwind has variants for ARIA attributes, such as aria-expanded: and aria-selected:, and data-* variants for libraries that expose a data-state attribute (Tailwind docs, states).

// Broken: the variant and aria-expanded are set separately and can disagree
const trigger = cva("trigger", { variants: { open: { true: "bg-muted" } } });
<button className={trigger({ open: isOpen })}>Menu</button>

// Fixed: one value sets aria-expanded, and the classes read the attribute
const trigger = cva("trigger aria-expanded:bg-muted");
<button className={trigger()} aria-expanded={isOpen}>Menu</button>

4. Modals, portals and the focus that escapes them

React modals are usually rendered with createPortal into the end of document.body. The React docs warn that with portals "you may need to manage keyboard focus so that the user can move the focus in and out of the portal in a natural way", and point to the WAI-ARIA modal pattern (React docs, createPortal). Audits keep finding three gaps:

Focus does not move in. The dialog opens, but focus stays on the button behind it. The WAI-ARIA pattern says focus moves to an element inside the dialog when it opens (W3C APG, dialog (modal) pattern).
Focus escapes. Tab walks out of the dialog into the page behind it. The pattern says Tab and Shift+Tab cycle inside the dialog, and Escape closes it.
Focus does not come back. On close, focus drops to the top of the page instead of returning to the element that opened the dialog.

The native <dialog> element handles more of this than most custom components. MDN notes that with showModal(), the rest of the page is made inert by the browser, Escape closes the dialog, and focus moves to the first focusable element inside it (MDN, dialog element). Returning focus on close is still worth testing by hand.

// Broken: a div overlay in a portal, with no focus handling
{open && createPortal(<div className="modal">{children}</div>, document.body)}

// Fixed: native dialog opened with showModal, focus returned on close
function Modal({ open, onClose, title, children }) {
  const ref = useRef(null);
  const opener = useRef(null);
  useEffect(() => {
    if (open) { opener.current = document.activeElement; ref.current.showModal(); }
    else if (ref.current?.open) { ref.current.close(); opener.current?.focus(); }
  }, [open]);
  return (
    <dialog ref={ref} onClose={onClose} aria-labelledby="modal-title">
      <h2 id="modal-title">{title}</h2>
      {children}
    </dialog>
  );
}

One more portal detail that surprises people: React events from a portal bubble through the React tree, not the DOM tree, so a click inside the modal can trigger an onClick on a parent component that is nowhere near it on the page (React docs, createPortal caveats). If closing a modal also fires a click behind it, this is usually why. Our guide to accessible modals covers the dialog pattern in full.

5. Live regions that are added too late

React apps are full of async state: "Saving...", "Added to cart", "3 results", form errors after submit. The usual fix is aria-live, and the usual bug is rendering the live region at the same moment as its message:

// Broken: the region and its text appear in the same render, often silent
{saved && <p aria-live="polite">Changes saved</p>}

// Fixed: the region is always there, only its text changes
<p role="status" aria-live="polite">{saved ? "Changes saved" : ""}</p>

MDN explains why: assistive technologies "will generally only announce dynamic changes in the content of a live region", so you should "establish the live region before updating its content", and "the most reliable way to ensure that live regions are registered is to include them in the initial markup" (MDN, ARIA live regions). In React terms: render the container unconditionally, and change only what is inside it. MDN also notes that role="alert" gets special handling and is generally announced even when injected, which is why it works for urgent errors but should not be used for routine status. Our guide to role="status" and role="alert" goes deeper.

6. What jest-axe and @axe-core/playwright catch, and what they miss

Adding axe to your tests is worth doing. It catches missing names, invalid ARIA, missing labels and similar problems on every build. Deque, which maintains axe-core, reports that 57.38% of issues found in first-time audits of its customers could be found with automated testing (Deque, automated testing coverage). The rest needs a person.

Two tool details matter for React projects:

jest-axe runs in JSDOM, which does not render. Its README says "color contrast checks do not work in JSDOM so are turned off in jest-axe" (jest-axe on GitHub). Component tests will never flag contrast.
@axe-core/playwright runs in a real browser, so it sees rendered styles. Playwright's own docs still say "automated testing cannot detect all types of WCAG violations" (Playwright docs, accessibility testing).

Four things from this guide that a passing axe run does not prove:

Where focus goes after a route change. axe checks one state of the page, not what happens between two.
Whether a live region actually speaks. axe can see the attribute, not whether the region existed before the text arrived.
Whether a modal traps and returns focus. That is behaviour across key presses, which needs a scripted or manual test.
Whether a clickable div is a control. Click handlers attached by React are not visible as HTML attributes, so a rule that reads the markup cannot see them. Look for them in code review, or use a check that tests the rendered page for clickable elements that are not controls.

For the first three, a short keyboard test by hand on each key template finds most of it in minutes.

How to explain this to a client or a manager

Keep it to one sentence per finding: "When someone navigates the site with a keyboard or a screen reader, the page changes without telling them", "the menu button cannot be opened without a mouse", "the save confirmation is shown but never read out". Then say where the fix lives. Most of these are fixed once in a shared component or layout, not page by page, which makes the estimate smaller than the finding list suggests.

Be clear that automated checks, ours included, find many problems but cannot confirm a site conforms to WCAG. The behaviours in this guide need a person with a keyboard to sign them off.

Checklist before you audit a React or Next.js build

Every route has a unique, descriptive title, and you know whether your router announces changes.
One agreed rule for where focus lands after navigation, applied everywhere.
Search the code for onClick on div, span, li and svg, and start with shared components.
Styles for open, selected and pressed states read aria-* or data-state attributes, not a separate class.
Modals move focus in, keep it in, close on Escape and return it to the opener.
Live regions are rendered on first load and only their text changes.
axe runs in a real browser in CI, and a person tests the behaviour it cannot.

To see what a rendered page fails right now, run a free accessibility scan: AccessGuard runs automated WCAG 2.2 AA checks in a real browser, so it sees what your React code actually renders. For focused checks, check a page for controls a keyboard cannot reach or see, and check a page for broken ARIA.

EAA Accessibility Statement Requirements: What to Publish

Denis Omerovic — Wed, 28 Oct 2026 07:14:15 +0000

Originally published at AccessGuard.

A client sells online in the EU, someone has read that the European Accessibility Act needs "an accessibility statement", and the job lands on whoever looks after the website. Then the search starts for the official template, and there isn't one. The EAA tells a service provider what information to publish, not what the page has to look like.

This guide covers what the directive actually asks for, a structure you can reuse on any site, how to describe conformance without promising more than your testing supports, and how to keep the statement true after the next release.

What the EAA actually asks for

The obligation sits in two places in Directive (EU) 2019/882. Article 13(2) says service providers "shall prepare the necessary information in accordance with Annex V and shall explain how the services meet the applicable accessibility requirements." The same paragraph adds three conditions:

the information is available to the public "in written and oral format";
it is available "in a manner which is accessible to persons with disabilities";
it is kept "for as long as the service is in operation".

Annex V then says where it goes and what it contains. The provider includes the information "in the general terms and conditions, or equivalent document". Where applicable, that information contains:

a general description of the service in accessible formats;
descriptions and explanations needed to understand how the service operates;
a description of how the relevant accessibility requirements in Annex I are met by the service.

Annex V point 3 adds one more thing that most published statements skip: the provider "shall provide information demonstrating that the service delivery process and its monitoring ensure compliance". In plain words, say how you keep it accessible, not only how accessible it was on the day you checked.

For a website, the Annex I requirement you are describing is the one in Section III: making websites and mobile apps "accessible in a consistent and adequate way by making them perceivable, operable, understandable and robust". Those are the four principles of WCAG, which is why every statement ends up talking about WCAG criteria.

Three things the directive does not do: it does not prescribe a page title, a fixed set of headings, or a conformance label. The measures have applied since 28 June 2025 (Article 31(2)), and each member state's transposing law can add its own detail, so check the national law for every country the service is provided in. Microenterprises providing services are exempt from the service requirements under Article 4(5); the guide to whether the EAA applies walks through that test.

Why people expect a template

Public sector sites in the EU do have one. Commission Implementing Decision (EU) 2018/1523 sets a model accessibility statement under the Web Accessibility Directive, with mandatory sections for compliance status, non-accessible content, how the statement was prepared, feedback and contact details, and the enforcement procedure. It was written for public bodies, not shops or banks, but its structure is sound, and borrowing it is the easiest way to cover everything Annex V asks for.

The sections a usable statement has

Combine Annex V, the public sector model and the W3C WAI guidance on accessibility statements and you get a structure that works for a store, a booking site or a SaaS app:

SectionWhat goes in itWhy


ScopeWhich domains, apps and flows the statement coversA statement that covers "the website" is vague when checkout runs on a third party domain
About the serviceA short plain description of what the service does and how a customer uses itAnnex V points 1(a) and 1(b)
Standard appliedThe standard and level you test against, for example WCAG 2.2 Level AAAnnex V point 1(c) and point 2
Conformance statusYour honest assessment, in one sentenceThe part people overclaim most
Known limitationsEach open failure in plain words, with the criterion and a workaroundUsers need the workaround more than the criterion number
How we test and keep it accessibleTesting methods, dates, and the process that catches regressionsAnnex V point 3
Feedback and contactAt least two ways to reach a person, and a response timeThe route users actually take
EscalationThe national authority responsible for checking servicesTells users where to go if you do not answer
DatesWhen the statement was prepared and last reviewedShows whether anyone still maintains it

Link the statement from the footer of every page and from the terms and conditions, since Annex V names that document. The page itself has to be accessible: a statement published as a scanned PDF fails the very requirement it describes. If you do provide a PDF, run it through the PDF accessibility checker first.

W3C publishes a free accessibility statement generator. It makes a good first draft; add the Annex V service description and the monitoring section yourself.

How to state conformance without overclaiming

The most common mistake is one confident sentence: "This website is fully compliant with WCAG 2.2 AA." It is almost never supported by the testing behind it. Full conformance means every page and every criterion passes, and an automated scan cannot tell you that. Automated tools catch many failures, but a large share of WCAG criteria need a person to judge, such as whether alt text is meaningful or whether focus order makes sense. The accessibility audit checklist separates what tools catch from what needs a person.

Use the three levels from the public sector model, because they map honestly onto real sites:

Fully conforms: only after a full audit, automated and manual, found no open failures in scope.
Partially conforms: the right answer for most sites. Some content does not yet meet the standard, and you list it.
Does not conform: most of the site fails, or you have not tested it. Say so and give a date for the work.

Also name what you tested and how. "Tested on 14 October 2026 with automated checks on 40 key pages and a manual keyboard and screen reader pass of checkout" is a claim someone can check. "Regularly audited by experts" is not.

A worked example with open failures

Here is honest wording for a fictional store with three known problems. Adapt the names, dates and findings to your own audit; do not copy the findings.

<!-- Broken: an overclaim the audit does not support -->
<h2>Conformance status</h2>
<p>Our website is 100% accessible and fully compliant
   with the European Accessibility Act.</p>

<!-- Fixed: a status the audit supports, with the gaps listed -->
<h2>Conformance status</h2>
<p>shop.example.com partially conforms to WCAG 2.2 Level AA.
   Partially conforms means some content does not yet meet
   the standard. The known problems are listed below.</p>

<h2>Known limitations</h2>
<ul>
  <li>The size guide opens in a pop-up that keyboard users
      cannot close without reloading the page (WCAG 2.1.2).
      The same table is on each product page under "Sizes".
      Planned fix: December 2026.</li>
  <li>Some older product photos have no text description
      (WCAG 1.1.1). We are adding descriptions to the
      remaining photos, newest products first.</li>
  <li>The delivery date picker cannot be used with a screen
      reader (WCAG 4.1.2). You can type the date instead,
      or choose a date with our support team.</li>
</ul>

Each item says what fails in plain words, gives the criterion, offers a workaround and says when it gets fixed. If you cannot commit to a date, say what you are doing instead. A dated promise you miss makes the statement untrue.

Avoid writing "compliant with the European Accessibility Act" at all. The law is met or not met by the service, and that is decided by the authorities responsible for checking services, not by your own page. Describe the standard you test against and the results, and let that speak.

The feedback and escalation route

The second common mistake is a statement with no way to report a problem, or one that sends people to a contact form that is itself inaccessible. A usable feedback section has:

an email address that reaches a person, not only a form;
a phone number, which also covers the "oral format" in Article 13(2) for people who cannot read the page;
a stated response time, such as "we reply within five working days";
an offer to provide information in another format on request.

Then name where people can escalate. Each member state designates authorities responsible for checking that services comply, and a user who gets no answer from you should be able to find them from your page. Look up the authority in the transposing law for each country you sell in and link it by name. Check the form you send people to with the form label checker and the keyboard and focus checker before you publish.

Decide who reads those messages. An unmonitored feedback address turns a fixable bug into a complaint to an authority.

Keeping the statement true after the next release

Article 13(3) requires procedures so the service "remains in conformity" as it changes, and it names changes to the service, to the requirements and to the harmonised standards. A statement is accurate for the build you tested. Every release, theme update and new plugin can make it false.

Standards are moving too. ETSI published EN 301 549 V4.1.1 in September 2026, and its web clauses now point at WCAG 2.2. As the EN 301 549 v4.1.1 guide explains, no version is cited in the Official Journal under the EAA yet. If a statement names WCAG 2.1 or EN 301 549 V3.2.1, review whether that is still the standard you test against.

Build the review into the work you already do:

On every release: rescan the pages the release touched and check whether any new failure belongs in "Known limitations".
When a limitation is fixed: remove it from the statement in the same deploy, so the list stays honest in both directions.
At least once a year: repeat the manual pass, update the "last reviewed" date, and reread the national law for changes. The public sector model asks for a yearly review too.

Automated monitoring helps with the first item. AccessGuard, for example, rescans the pages you add on a daily, weekly or monthly schedule and alerts you to new failures, which tells you when the statement needs a new line. It runs automated WCAG 2.2 AA checks, so it cannot confirm conformance on its own; the manual pass still decides what the statement says.

Checklist before you publish

Scope names every domain and app the statement covers, including third party checkout.
The service is described in plain words (Annex V point 1).
The standard and level are named, and the status matches the audit: usually "partially conforms".
Every known failure is listed in plain words, with the criterion, a workaround and a plan.
The testing method and date are stated, and so is the process that catches regressions (Annex V point 3).
Email and phone reach a person, with a response time.
The national authority for escalation is named and linked for each country.
The page is linked from every footer and from the terms and conditions, and the page itself passes a scan.
Someone owns the review on each release and once a year.

Before you write the limitations section, find out what is actually open. Run a free accessibility scan on the pages that matter most, then do the manual pass for what a scan cannot judge. The statement is only as honest as the testing behind it.

Elementor Accessibility: What Audits Find and How to Fix It

Denis Omerovic — Mon, 26 Oct 2026 07:20:01 +0000

Originally published at AccessGuard.

An Elementor site looks finished long before its markup is. Somebody dragged in a Heading widget, picked a size that looked right, linked a card, dropped in an icon for Instagram, and published. Every one of those choices writes HTML, and most of the accessibility failures on an Elementor site come from widget settings, not from code anybody typed.

That is good news if you have just inherited one, from a client, a former freelancer or your own past self. Most fixes are a setting in the panel, not a rebuild. The catch is where those settings live: the worst failures sit in Theme Builder templates, and fixing pages one at a time never reaches them. This guide covers where Elementor sites fail, the fix for each, and an order to work in.

Where Elementor sites fail

Run an automated scan on a typical Elementor page and the findings cluster in a few places:

Headings chosen for their size, so the outline skips levels or has three H1s.
Links with no name: icon widgets, social icons and image links with nothing a screen reader can read.
Nested links inside cards, where the whole container is a link and the button inside it is another.
Menus, tabs and accordions that work with a mouse and only partly with a keyboard.
Contrast from global colors that were picked in a design file and never checked.

The first four are covered below. You can see which of them a page has in about a minute with a free accessibility scan, which is a good way to start before you open the editor.

Heading tag versus heading size

Elementor's Heading widget has two separate controls that people treat as one. The HTML Tag setting offers "H1 to H6, Div, Span, or Paragraph", and the font size lives in Typography (Elementor Heading widget docs). The tag is what a screen reader announces and what people navigate by. The size is only how it looks.

When an editor picks H2 because it is the right size for a footer tagline, or H5 for a card title because H3 looked too big, the outline stops describing the page. That fails 1.3.1 Info and Relationships: the visual structure says one thing and the markup says another.

<!-- Broken: tags chosen by size -->
<h2 class="elementor-heading-title">Trusted by local businesses</h2> <!-- a tagline, not a section -->
<h5 class="elementor-heading-title">Our services</h5>              <!-- the real section heading -->

<!-- Fixed: tags follow the outline, Typography handles the size -->
<p class="elementor-heading-title">Trusted by local businesses</p>
<h2 class="elementor-heading-title">Our services</h2>

The fix is in the widget panel: set HTML Tag to the level the content needs, then set the size in Typography so the design does not change. Text that should look like a heading but is not one (a tagline, a big number, a quote) gets Paragraph or Div. Each page needs one H1, usually the page title, and levels should step down in order.

Elementor's own Accessibility Assistant flags exactly these cases: a missing H1, more than one H1 and a heading that skips a level, with an option to "Keep the visual style but remove the semantic heading role" (Elementor help). Our headings and landmarks checker shows the outline of any page, and the guide to heading structure covers the rules in detail.

Icon-only buttons and nested links inside cards

Links and buttons with no name

An Icon widget or Social Icons widget with a link and no text produces a link that a screen reader announces as "link" and nothing else. The same happens with an image linked to a page when the image has no alt text. Both fail 2.4.4 Link Purpose (In Context) and 4.1.2 Name, Role, Value.

<!-- Broken: an icon link with no accessible name -->
<a class="elementor-icon" href="https://instagram.com/example">
  <svg aria-hidden="true">...</svg>
</a>

<!-- Fixed: the link says where it goes -->
<a class="elementor-icon" href="https://instagram.com/example"
   aria-label="Example Bakery on Instagram">
  <svg aria-hidden="true">...</svg>
</a>

You do not need code for this. Widgets with a Link field have a gear icon that opens Custom Attributes, which take a key|value format (Elementor custom link attributes). Enter aria-label|Example Bakery on Instagram and the attribute lands on the link. For linked images, write alt text in the media library that describes the destination. Our link text checker lists what a link name has to do to count.

The card that is a link with a link inside it

Elementor lets you make a whole container clickable: in Additional Options, set HTML Tag to "a (link)" (Elementor docs). It is the quickest way to build a clickable card, and it is where nested links come from. Elementor's own warning is plain: "When linking a container, the child elements within the container should NOT be linked themselves. Nesting <a> tags will cause issues."

The HTML standard does not allow an a element inside another a, or any interactive element such as a button inside a link (HTML standard, the a element). Browsers repair the invalid markup in different ways, so a screen reader may hear the whole card as one long link, and a keyboard user may tab to two stops that go to the same place.

<!-- Broken: a linked container with a linked button inside -->
<a class="e-con" href="/services/catering">
  <h3>Catering</h3>
  <p>Breakfast and lunch for offices of 10 to 200.</p>
  <a class="elementor-button" href="/services/catering">Read more</a>
</a>

<!-- Fixed: one link, named by the heading -->
<div class="e-con">
  <h3><a href="/services/catering">Catering</a></h3>
  <p>Breakfast and lunch for offices of 10 to 200.</p>
</div>

In Elementor, the fix is one of two things. Either link the container and remove the link from every child (the button can stay as a visual cue), or leave the container as a div and link the heading. The second is easier to understand with a screen reader, because the link name is the card title instead of every word in the card. Elementor's docs say version 3 of the editor will not stop you from nesting links, so check every card template, not only the ones built recently (Elementor nested links).

Menus, tabs and accordions

Interactive widgets are where a site can pass an automated scan and still fail a keyboard user, so these need a hand test. Unplug the mouse, press Tab from the top of the page, and check that every menu item, tab and accordion panel can be reached, opened and closed, with a visible focus ring the whole way (2.1.1 Keyboard, 2.4.7 Focus Visible). Our guide to testing keyboard accessibility by hand walks the full pass.

Menus

Elementor has improved its menus over several releases, so the version installed matters. Version 3.13 made the mobile menu toggle work with Enter and Space as well as a click (Elementor 3.13 notes). Version 3.16 gave the Menu widget a menubar role, menuitem roles, arrow key navigation and Escape to close, based on the ARIA Authoring Practices (Elementor 3.16 notes). Version 3.23 added a Menu Name control for labelling each menu (Elementor 3.23 notes). An inherited site that has not been updated in a while may have none of this.

Two checks after updating. First, a menubar role promises application-style behaviour: arrow keys between items, Enter or Space to open a submenu and Escape to close it. Test that all of it works, because the W3C's own navigation example notes that "Typical site navigation does not need all the keyboard interactions specified by the menu and menubar pattern" and uses simpler disclosure buttons instead (W3C disclosure navigation example). Second, when a page has more than one menu (header, footer, a sidebar), give each a distinct Menu Name so screen reader users can tell them apart. The navigation menus guide covers what good looks like.

Tabs and accordions

Tabs and accordions look alike and behave differently. An accordion header is a button that reports whether its panel is open (aria-expanded), and each one is a Tab stop (W3C accordion pattern). A tab list is one Tab stop, with arrow keys moving between tabs and the selected tab marked with aria-selected (W3C tabs pattern). Open the page with your browser's accessibility inspector and check that the Elementor widget exposes those states, then test the keys. If an FAQ was built from Toggle or Accordion widgets with headings inside the panels, check the heading levels there too. The guide to accordions and tabs has the markup for both.

What the accessibility widget does not fix

Many Elementor sites also run Elementor's own accessibility plugin, now listed on WordPress.org as Web Accessibility (formerly Ally). On 26 October 2026 it showed 500,000+ active installations and a rating of 2.9 out of 5 from 162 ratings (WordPress.org plugin page).

It does two different things, and it helps to keep them apart. The Accessibility Assistant scans pages and guides you through fixes, such as the heading fixes above, and those fixes change the page. The usability widget gives visitors a floating menu to resize text, change contrast and similar adjustments. That changes how the page looks for one visitor; it does not add a missing label, name an icon link or untangle a nested link.

The plugin is honest about this. Its description says it "is not a substitute for a thorough accessibility audit" and "is NOT intended to completely make your website legally compliant." The same is true of every automated tool, ours included: automated checks find many problems, but they cannot confirm a site conforms to WCAG. If a client believes the widget took care of accessibility, our piece on accessibility overlays explains the difference in plain terms.

A fix order for an inherited site

Work from the templates that appear everywhere down to individual pages, so each fix reaches as many pages as possible.

Update Elementor and the theme on a staging copy, so you are fixing the current widgets and not ones that have since changed.
Scan a sample of pages: the home page, one of each template type and the pages with forms. Save the results so you can show what changed.
Fix the Theme Builder header and footer. They appear on every page, so the menu, logo link and social icons fixed here are fixed site wide.
Fix global colors and typography in Site Settings, checking each text and background pair for contrast.
Fix single, archive and loop item templates: card links, heading levels in post titles, image alt text in featured images.
Fix pages one by one: heading tags, icon links, tabs and accordions, forms.
Test by hand with the keyboard and a screen reader, then rescan the same pages and compare.

Next steps

Run a free scan on the home page and one inner page to see which of these failures the site has.
Check the outline of each template with the headings and landmarks checker and every icon link with the link text checker.
Search your card templates for linked containers with linked children.
Keyboard test every menu, tab set and accordion after updating Elementor.
For the rest of the WordPress stack (form plugins, theme CSS, media library), see WordPress accessibility issues and fixes.

When you explain this to a client or a manager, the short version is: most of it is settings, not a rebuild, and the templates come first because one fix there reaches every page.

WCAG 2.2 vs 2.1: What Changed and What to Re-Test

Denis Omerovic — Fri, 23 Oct 2026 07:14:05 +0000

Originally published at AccessGuard.

If your site was built or audited against WCAG 2.1 and someone now asks for WCAG 2.2, the good news is that the gap is small and well defined. WCAG 2.2 keeps every WCAG 2.1 success criterion except one, adds nine new ones, and changes nothing about color contrast. This guide covers only the difference: what was added, what was removed, which of it applies at Level AA, and what a team that already meets 2.1 has to re-test.

Every level and quotation below comes from the WCAG 2.2 Recommendation (current edition dated 12 December 2024) and its Comparison with WCAG 2.1 section. If you want the full list of Level A and AA criteria instead, use our WCAG 2.2 checklist.

The short answer

The W3C published WCAG 2.2 as a Recommendation on 5 October 2023, according to its own What's new in WCAG 2.2 page. The Recommendation describes the relationship in one sentence: "WCAG 2.2 builds on and is backwards compatible with WCAG 2.1, meaning web pages that conform to WCAG 2.2 are at least as accessible as pages that conform to WCAG 2.1."

In practice that means three things:

Nine criteria were added. Six of them are Level A or AA, so they count for an AA target. Three are AAA.
One criterion was removed: 4.1.1 Parsing.
Everything else is the same. The W3C says the 2.0 and 2.1 success criteria "are essentially the same in 2.2, with one exception", and that exception is Parsing.

So a site that meets WCAG 2.1 AA is not starting over. It needs to pass six additional checks.

Did color contrast change in WCAG 2.2?

No. This is the question people search for most often, so here is the plain answer. The two contrast criteria at Level AA are the same in both versions:

1.4.3 Contrast (Minimum), AA: text needs a contrast ratio of at least 4.5:1, or 3:1 for large text.
1.4.11 Non-text Contrast, AA: the visual parts needed to identify controls and their states, and the parts of graphics needed to understand them, need at least 3:1 against adjacent colors.

Both were already in WCAG 2.1 (1.4.11 was added in 2.1) and neither changed in 2.2. If your text and controls passed contrast under 2.1, they pass under 2.2. You can confirm a page with our color contrast checker, and our guide to contrast requirements explains the ratios in detail.

The new criterion that touches contrast is 2.4.13 Focus Appearance, and it is Level AAA. It asks that a visible focus indicator be at least as large as a 2 CSS pixel thick perimeter of the component and have a contrast ratio of at least 3:1 between the focused and unfocused states. Because it is AAA, it is not part of an AA target. It is still a good design rule for focus outlines, and it is the reason many teams now use a solid 2 pixel outline.

The nine new criteria and their levels

CriterionLevelWhat it asks, in plain words

2.4.11 Focus Not Obscured (Minimum)AAA focused element is not entirely hidden by content the author added, such as a sticky header or cookie banner.
2.4.12 Focus Not Obscured (Enhanced)AAANo part of the focused element is hidden.
2.4.13 Focus AppearanceAAAThe focus indicator is big enough and contrasts 3:1 with its unfocused state.
2.5.7 Dragging MovementsAAAnything done by dragging can also be done with a single pointer without dragging, unless dragging is essential.
2.5.8 Target Size (Minimum)AAClick and tap targets are at least 24 by 24 CSS pixels, or have enough space around them, with listed exceptions.
3.2.6 Consistent HelpAHelp such as contact details or a chat link, when repeated across pages, appears in the same relative order.
3.3.7 Redundant EntryAInformation the user already entered in the same process is filled in or offered for selection, not typed again.
3.3.8 Accessible Authentication (Minimum)AALogging in does not require a cognitive function test, like remembering a password or solving a puzzle, unless an alternative or a helper is available.
3.3.9 Accessible Authentication (Enhanced)AAAAs 3.3.8, but without the object recognition and personal content exceptions.

For an AA target, the six that matter are 2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7 and 3.3.8. For a deeper explanation of each one with examples, see our breakdown of the nine WCAG 2.2 criteria.

What was removed: 4.1.1 Parsing

WCAG 2.1 had 4.1.1 Parsing at Level A. It asked for complete start and end tags, correct nesting, no duplicate attributes and unique IDs. WCAG 2.2 marks it "Obsolete and removed", with this note: "Assistive technology no longer has any need to directly parse HTML. Consequently, these problems either no longer exist or are addressed by other criteria."

The W3C also edited WCAG 2.1 itself. The current WCAG 2.1 Recommendation (dated 6 May 2025) adds a note that 4.1.1 "should be considered as always satisfied for any content using HTML or XML". So even under 2.1, an HTML validator error is no longer a Parsing failure.

That does not make markup errors harmless. A duplicate id can still break a real relationship, and then the failure belongs to another criterion, usually 1.3.1 Info and Relationships or 4.1.2 Name, Role, Value:

<!-- Broken: two inputs share id="email", so the second label points at the wrong field -->
<label for="email">Billing email</label>
<input id="email" type="email" autocomplete="email">
<label for="email">Shipping email</label>
<input id="email" type="email">

<!-- Fixed: unique ids, so each label names its own field -->
<label for="billing-email">Billing email</label>
<input id="billing-email" type="email" autocomplete="email">
<label for="shipping-email">Shipping email</label>
<input id="shipping-email" type="email">

One more detail from the Recommendation: authors who are required by policy to conform to WCAG 2.0 or 2.1 "may need to continue to test and report 4.1.1". If a contract or procurement form lists 4.1.1, answer it, and explain the W3C note.

What a team that meets 2.1 has to re-test

Here is the upgrade work for a site that already meets WCAG 2.1 AA, ordered by where failures usually turn up.

Sticky headers, footers and banners (2.4.11)

Tab through every template with the cookie banner open and closed. If a focused link scrolls under a fixed header and disappears completely, it fails. The usual fix is one line of CSS:

/* Broken: focused items scroll underneath a 72px fixed header */
.site-header { position: fixed; top: 0; height: 72px; }

/* Fixed: the browser keeps focused and scrolled-to items clear of the header */
html { scroll-padding-top: 80px; }

Our keyboard and focus checker covers tab order and focus on a page, and how to test keyboard accessibility by hand walks through the manual pass.

Small targets (2.5.8)

Icon buttons, pagination links, close buttons and social icons are the usual suspects. A target under 24 by 24 CSS pixels can still pass if the spacing exception applies, and links inside a sentence are exempt. Run the target size checker on your busiest templates, and read our guide to the 24 pixel rule for the exceptions.

Drag interactions (2.5.7)

List every slider, sortable list, map, kanban board and file drop zone. Each needs a way to do the same thing with clicks or taps alone, such as up and down buttons on a sortable list or a "choose file" button next to the drop zone.

Login, sign-up and password reset (3.3.8)

Check that password fields allow paste and password managers (no autocomplete="off" on them), that one-time codes can be pasted, and that any CAPTCHA has an alternative that does not rely on a puzzle. Our guide to accessible forms covers the field markup.

Multi-step forms (3.3.7)

Walk through checkout, booking and application flows. If step three asks for an address the user typed in step one, offer a "same as billing" checkbox or fill it in.

Help links (3.2.6)

If the header or footer has a contact link, phone number or chat button on several pages, make sure it sits in the same order relative to the rest of the page on each one. Templates usually get this right; one-off landing pages are where it slips.

Which version should you target?

Some rules still name WCAG 2.1. In the United States, the Department of Justice rule for state and local governments under ADA Title II adopted WCAG 2.1 Level AA (Federal Register, 89 FR 31320); our post on the Title II deadline extension has the dates. In Europe, the new EN 301 549 V4.1.1 points its web requirements at WCAG 2.2, as we explain in what changed in EN 301 549 V4.1.1.

Because 2.2 is backwards compatible, you do not have to choose. The W3C says "sites which conform to WCAG 2.2 also conform to WCAG 2.1", and its Working Group "recommends that sites adopt WCAG 2.2 as their new conformance target, even if formal obligations mention previous versions". Building to 2.2 AA covers a 2.1 AA requirement too.

What to tell a manager or a client

Something like this works: "WCAG 2.2 is the current version. It keeps everything from 2.1, drops one outdated rule, and adds six requirements at our level, mostly about focus, tap targets, dragging and logins. Contrast rules did not change. We will test those six on our main templates and fix what fails." That is accurate, short and does not overpromise.

A note on tools: automated checks, ours included, can flag many of these problems, but they cannot confirm that a site conforms to any version of WCAG. Several of the new criteria, such as Consistent Help and Redundant Entry, depend on how pages and processes behave, so a person still has to look.

Upgrade checklist: WCAG 2.1 AA to 2.2 AA

Keep your 2.1 results. Contrast, alt text, headings, labels and the rest carry over unchanged.
Drop 4.1.1 Parsing from your 2.2 report, but keep fixing duplicate ids that break labels or ARIA references.
Tab through each template with sticky elements visible (2.4.11).
Measure small icons and links against 24 by 24 CSS pixels (2.5.8).
Give every drag action a click or tap alternative (2.5.7).
Allow paste and password managers on login and reset forms (3.3.8).
Remove repeated questions in multi-step forms (3.3.7).
Keep help links in the same order across pages (3.2.6).
Update your accessibility statement and reports to say WCAG 2.2 AA.

Want a starting point? Run a free accessibility scan on your home page and one key template. AccessGuard runs automated WCAG 2.2 AA checks in a real browser, including target size and focus checks, and shows which failures need a person to confirm.

Button vs Link Accessibility: The Choice That Breaks Keyboards

Denis Omerovic — Wed, 21 Oct 2026 07:16:40 +0000

Originally published at AccessGuard.

A designer hands over a mockup with a blue "Add to cart" pill and an underlined "Show more" link. A developer builds both as whatever is quickest: an <a href="#"> for one, a <div onclick> for the other. The page looks right, and it passes a mouse test. Then a keyboard user tabs straight past the cart, and a screen reader announces "link" for something that never goes anywhere.

Choosing between a button and a link is one of the cheapest accessibility decisions on a site, and one of the most common things an audit flags. This guide covers what each element promises, what breaks when you swap them, how to fix a clickable div, and how to explain the finding to a client or a manager.

What each element promises

The element you choose is a promise about two things: how it behaves with a keyboard, and what a screen reader says about it. The WAI-ARIA Authoring Practices put the difference plainly: "The types of actions performed by buttons are distinctly different from the function of a link" (W3C APG, button pattern).

Link (<a href>)Button (<button>)

What it doesGoes somewhere: another page, a section, a fileDoes something: submits, opens, toggles, adds, deletes
Keys that activate itEnterEnter and Space
Screen reader announces"Link""Button"
Browser extrasOpen in new tab, copy address, history, shows in a screen reader's links listCan submit a form, can be disabled

A simple test: if the address bar should change, or the user might want to open it in a new tab, it is a link. If it changes something on the current page, it is a button.

Enter, Space and what breaks when you swap them

The APG link pattern gives a link one key: Enter "executes the link and moves focus to the link target" (W3C APG, link pattern). The button pattern gives a button two: both Space and Enter "activates the button" (W3C APG, button pattern). Native HTML elements do this for you. Swap them, and the behaviour goes with the element, not the design.

A link used as a button

<!-- Broken: announced as a link, Space scrolls the page instead of opening the menu -->
<a href="#" onclick="openMenu(); return false;">Menu</a>

<!-- Fixed: a button that says what it controls -->
<button type="button" aria-expanded="false" aria-controls="site-menu">Menu</button>

Problems with the broken version: a screen reader user hears "link, Menu" and expects to go somewhere. Pressing Space, which people use for buttons, scrolls the page. If the script fails, href="#" jumps to the top. And "open in new tab" opens a copy of the same page.

A button used as a link

<!-- Broken: navigation hidden in a script, no address to open or share -->
<button type="button" onclick="location.href='/pricing'">See pricing</button>

<!-- Fixed: a real link, styled however the design needs -->
<a href="/pricing" class="button">See pricing</a>

This one is less harmful for keyboards, because the button still works, but it drops out of the screen reader's list of links, cannot be opened in a new tab and is not a link search engines can follow: Google says it "can follow your links only if they use proper <a> HTML element with an href attribute" (Google Search Central).

A link with no href

An <a> with no href is not a link at all. The HTML standard says that without an href "the element represents a placeholder link" (HTML Living Standard), and browsers do not put it in the tab order. Click handlers on it work with a mouse and nothing else.

Fixing a div with an onclick

The most common version of this failure is a div or span with a click handler. It looks like a control and acts like one with a mouse, but a keyboard cannot reach it and a screen reader announces it as plain text. That fails WCAG 2.1.1 Keyboard, which requires that "all functionality of the content is operable through a keyboard interface", and usually WCAG 4.1.2 Name, Role, Value, because nothing tells assistive technology it is a control.

<!-- Broken: no focus, no role, no keyboard activation -->
<div class="add-to-cart" onclick="addToCart(42)">Add to cart</div>

<!-- Fixed: a native button gets focus, Enter, Space and its role for free -->
<button type="button" class="add-to-cart" onclick="addToCart(42)">Add to cart</button>

Two details catch people out:

Set type="button". Inside a form, a button with no type is a submit button. MDN warns that a button not meant to submit should have type="button", "Otherwise, they will try to submit form data" (MDN, the button element).
Reset the styles, not the element. Developers often avoid <button> because of its default look. A few lines of CSS remove that:

/* Fixed: a button that looks like plain text, with focus still visible */
.button-reset {
  background: none;
  border: 0;
  padding: 0;
  font: inherit;
  color: inherit;
  cursor: pointer;
}

.button-reset:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 2px;
}

Why role="button" plus tabindex is the last resort

You can make a div behave like a button with ARIA, but you have to rebuild everything the browser would have given you:

<!-- Works, but only with the script below. Use a real button if you can. -->
<div role="button" tabindex="0" class="add-to-cart">Add to cart</div>

// Every one of these lines is something <button> already does
el.addEventListener("click", addToCart);
el.addEventListener("keydown", (event) => {
  if (event.key === "Enter") addToCart();
  if (event.key === " ") event.preventDefault(); // stop the page scrolling
});
el.addEventListener("keyup", (event) => {
  if (event.key === " ") addToCart();
});

And you still have no disabled state, no form submission, and a component that breaks the first time someone edits the markup and drops the script. The W3C's guidance on ARIA says the same as its first rule: if a native HTML element already has the semantics and behaviour you need, use it instead of adding a role to something else (Using ARIA, first rule). Keep this pattern for markup you genuinely cannot change, such as a third-party widget.

When a link should look like a button

Design and semantics are separate decisions. A "Start free trial" call to action that goes to a signup page is a link, even if it is a big coloured pill. Give it a .button class and keep the <a href>. A "Show more" control that expands text on the same page is a button, even if it is styled as underlined text.

The APG notes that a link-styled element acting as a button can take role="button", but says "a better solution is to adjust the visual design so it matches the function and ARIA role" (W3C APG, button pattern). In practice that means: pick the element by what it does, then style it, and keep a visible focus style on both.

Whichever you choose, give it a name that makes sense on its own. An icon-only button needs an accessible name, and a link's text should say where it goes. Our guide to ARIA attributes covers when ARIA helps and when it gets in the way, and you can check a page for links that do not say where they go.

What an audit flags and how to explain it to a client

Automated tools find the clearest cases: elements with click handlers that are not controls, links with no href, and controls with no accessible name. Our free keyboard and focus checker looks for clickable divs and spans that a keyboard cannot reach, along with removed focus styles. What a tool cannot judge is intent: whether a real <a href> that runs a script should have been a button. That takes a person, so pair the scan with a keyboard test by hand.

When you report it, skip the jargon. Something like this works for a manager or a client:

"Some of the controls on the site, including the add to cart button and the menu toggle, only work with a mouse. People who use a keyboard or a screen reader cannot use them, and so cannot buy. The fix is to build them with the standard HTML button element, which takes a developer minutes per control and does not change how the site looks."

That framing is accurate and gives the person paying for the work a reason to prioritise it: the broken controls tend to sit on the pages that matter most, such as navigation, checkout and forms.

Checklist

Run a free scan on your home page, a product or service page and the checkout or contact form.
Replace every div or span with a click handler with a <button type="button">.
Replace every <a> with no href, or with href="#" and a script, with a button.
Replace every button that only changes the page address with an <a href>.
Give icon-only buttons and links an accessible name.
Tab through the page: every control should be reachable, show visible focus, and work with Enter (and Space, for buttons).
Keep role="button" with tabindex="0" only for markup you cannot change, with the keyboard script in place.

For the wider picture, our guide to keyboard navigation covers focus order, skip links and keyboard traps.

Accessible Navigation Menus and Dropdowns That Work

Denis Omerovic — Mon, 19 Oct 2026 07:15:21 +0000

Originally published at AccessGuard.

The main navigation is the one component every site has, and the one a keyboard user meets first. When it fails, they cannot reach anything else. It is also the component where most of the ARIA advice you find online makes things worse, because it starts from the word "menu".

This guide covers the pattern W3C recommends for site navigation, the markup for it, what to do about hover submenus and mobile toggles, and how to explain the findings to whoever owns the site. It applies whether you write the markup yourself or are choosing a theme, a page builder block or a plugin.

Why role="menu" is usually the wrong choice for site navigation

In everyday speech a navigation bar is a "menu". In ARIA, role="menu" and role="menubar" mean something narrower: a widget that behaves like the menu bar at the top of a desktop application. The W3C ARIA Authoring Practices Guide (APG) defines a menu as "a widget that offers a list of choices to the user, such as a set of actions or functions" (APG, Menu and Menubar Pattern).

Adding those roles is a promise. Screen readers announce a menu and expect the keyboard model that comes with it: the arrow keys move between items, only one item sits in the Tab sequence, and Tab leaves the whole menubar. Most navigation bars that carry role="menubar" deliver none of that. They are a list of links with the roles pasted on, so the user is told one thing and gets another.

The APG's own navigation menubar example opens with a warning: "The menubar pattern requires complex functionality that is unnecessary for typical site navigation that is styled to look like a menubar with expandable sections or fly outs. A pattern more suited for typical site navigation with expandable groups of links is the Disclosure Pattern" (APG, Navigation Menubar Example).

So the menubar is not forbidden. It is a lot of work to get right, and for a list of pages it buys nothing. If your navigation is a set of links, some of them grouped under section headings, use the disclosure pattern below.

One line on a related guide: a custom select or autocomplete field is a combobox, a different widget with its own rules, covered in how to build accessible custom dropdowns and comboboxes. This guide is about site navigation only.

The disclosure pattern: a button and a list of links

The APG's disclosure navigation example "does not use the menu role because it does not provide the complex functionality that assistive technologies expect in a widget that has the menu role. Typical site navigation does not need all the keyboard interactions specified by the menu and menubar pattern" (APG, Example Disclosure Navigation Menu).

The structure is plain HTML. A nav landmark holds a list. A top-level item is either a link, or a button that shows and hides a nested list of links. The button carries two attributes: aria-expanded says whether its list is open, and aria-controls points to the list.

<!-- Broken: menu roles with no menu keyboard model, and a div as the trigger -->
<ul role="menubar">
  <li role="menuitem">
    <div class="nav-trigger">Services</div>
    <ul role="menu" class="submenu">
      <li role="menuitem"><a href="/services/audits">Audits</a></li>
    </ul>
  </li>
</ul>

<!-- Fixed: a nav landmark, a real button, and links in a list -->
<nav aria-label="Main">
  <ul>
    <li><a href="/">Home</a></li>
    <li>
      <button type="button" aria-expanded="false" aria-controls="nav-services">Services</button>
      <ul id="nav-services" hidden>
        <li><a href="/services/audits">Audits</a></li>
        <li><a href="/services/fixes">Fixes</a></li>
      </ul>
    </li>
  </ul>
</nav>

The script only has to flip two things when the button is pressed:

// Toggle the submenu and keep aria-expanded in step with what is on screen
document.querySelectorAll('nav button[aria-controls]').forEach((button) => {
  const list = document.getElementById(button.getAttribute('aria-controls'));
  button.addEventListener('click', () => {
    const open = button.getAttribute('aria-expanded') === 'true';
    button.setAttribute('aria-expanded', String(!open));
    list.hidden = open;
  });
});

Because it is a real button, Enter and Space work and it is announced as a button with its state, which is what 4.1.2 Name, Role, Value (Level A) asks for: the name and role "can be programmatically determined", and for its state, "notification of changes to these items is available to user agents, including assistive technologies" (WCAG 2.2). Our guide to ARIA attributes explains why the native element beats a div with roles added.

The keyboard behaviour to build

From the APG disclosure example, the required keys are few:

Tab and Shift + Tab move between the top-level links and buttons, and through the links of an open list.
Enter or Space on a button opens or closes its list.
Escape, when a list is open, closes it and puts focus back on its button.

Arrow keys, Home and End are marked optional in that example. Add them if you like, but Tab, Enter, Space and Escape are what 2.1.1 Keyboard (Level A) depends on: "All functionality of the content is operable through a keyboard interface" (WCAG 2.2). The general rules for focus and tab order are in our guide to keyboard navigation and focus management.

Should the section name be a link too?

A common design has "Services" as both a page and a submenu trigger. One element cannot be both: a link goes somewhere on Enter, a button opens the list. Either make the top-level item a link and give the submenu a separate small button beside it (with an accessible name such as "Services submenu"), or keep the button and put an "All services" link as the first item in the list. The second is simpler and works the same on touch screens.

Hover submenus and what 1.4.13 asks for

Many sites open submenus on mouse hover. You can keep that, as long as keyboard users have the button and the hover behaviour passes 1.4.13 Content on Hover or Focus (Level AA). W3C lists "sub-menus" among the content it covers (Understanding SC 1.4.13). Content that appears on hover or focus must be:

Dismissible: "A mechanism is available to dismiss the additional content without moving pointer hover or keyboard focus". In practice, Escape closes the open submenu.
Hoverable: "the pointer can be moved over the additional content without the additional content disappearing". A gap between the top item and the submenu that closes it as the pointer crosses fails this.
Persistent: it "remains visible until the hover or focus trigger is removed, the user dismisses it, or its information is no longer valid". No timer that hides it after two seconds.

/* Broken: a 12px gap closes the submenu before the pointer reaches it */
.nav li { position: relative; }
.nav .submenu { position: absolute; top: calc(100% + 12px); }

/* Fixed: the submenu touches its trigger; the gap is padding inside it */
.nav .submenu { position: absolute; top: 100%; padding-top: 12px; }

Never make hover the only way in. A submenu that opens on hover and has no button is unreachable by keyboard and on many touch screens, which is a 2.1.1 failure before 1.4.13 even comes up.

The mobile toggle

On small screens the whole navigation usually hides behind a single toggle. It is the same disclosure pattern one level up, and it fails in the same few ways.

<!-- Broken: an icon in a div, no name, no state -->
<div class="hamburger" onclick="toggleNav()"><svg>...</svg></div>

<!-- Fixed: a named button that reports whether the navigation is open -->
<button type="button" class="nav-toggle" aria-expanded="false" aria-controls="site-nav">
  <svg aria-hidden="true" focusable="false">...</svg>
  <span class="visually-hidden">Menu</span>
</button>

Then check what happens around it:

Focus order. After the toggle opens the navigation, the next Tab should land on the first link inside it. If the panel sits at the end of the markup, focus wanders through the whole page first.
Escape. It should close the panel and return focus to the toggle.
A full-screen panel. If it covers the page, the content underneath must not take focus while it is open, or keyboard users tab into links they cannot see. The HTML inert attribute on the main content does this. A panel that covers the page like this behaves as a dialog, so the focus rules in our guide to accessible modals apply.
A sticky header. When focus moves down the page, the sticky bar must not cover the focused element entirely. That is 2.4.11 Focus Not Obscured (Minimum), Level AA (Understanding SC 2.4.11).

Marking the current page with aria-current

Sighted users see the current page highlighted in the navigation. Screen reader users need the same signal in the markup. ARIA's aria-current "indicates the element that represents the current item within a container or set of related elements", and "Authors SHOULD only mark one element in a set of elements as current" (WAI-ARIA 1.2).

<!-- Broken: the highlight is only a class, so nothing is announced -->
<a href="/services/audits" class="active">Audits</a>

<!-- Fixed: announced as the current page, and styled from the same attribute -->
<a href="/services/audits" aria-current="page">Audits</a>

Style it with [aria-current="page"] rather than a separate class, so the visual highlight and the announced state can never disagree. Most CMSes and themes print an "active" class already; adding the attribute in the same template is usually one line.

More than one navigation on a page

Header, footer and breadcrumb navigation are all nav landmarks. The APG says: "If a page includes more than one navigation landmark, each should have a unique label" (APG, Navigation Landmark). aria-label="Main", aria-label="Footer" and aria-label="Breadcrumb" are enough. Leave the word "navigation" out of the label, because screen readers already announce the landmark type.

Link text matters in navigation too: icon-only social links and repeated "More" links are common findings. The link text checker flags links with no name or vague text.

What a scan finds and what needs a person

An automated scan can find a lot of this in the rendered page: invalid ARIA such as menu roles missing their required children, buttons and links with no accessible name, and divs with click handlers that a keyboard cannot reach. Our ARIA checker and keyboard and focus checker look for those, and a free accessibility audit runs them on any page.

A scan cannot tell you whether the submenu stays open while the pointer crosses to it, whether Escape returns focus to the button, or whether the mobile panel lets focus escape underneath it. 1.4.13 in particular is a manual check. No automated tool can confirm a navigation conforms to WCAG. Our step by step manual keyboard accessibility test covers the rest in about twenty minutes.

How to explain it to a client or manager

Keep it concrete: "Keyboard users cannot open the Services menu, so they cannot reach the six pages under it." That is a sentence a manager can act on. The fix for most navigation findings is small, a button instead of a div, two attributes and an Escape handler, and it usually lives in one template, so it fixes every page at once.

Your checklist

The navigation is a nav with a list of links, and no menu, menubar or menuitem roles unless you built the full menubar keyboard model.
Every submenu trigger is a button with aria-expanded that changes when it opens and closes.
Enter and Space open a submenu; Escape closes it and returns focus to its button.
Hover submenus also open from the button, stay open while the pointer moves onto them and have no auto-hide timer.
The mobile toggle is a named button with aria-expanded, focus moves into the panel, and nothing behind a full-screen panel takes focus.
The sticky header never fully covers the focused element.
The current page link has aria-current="page", and the highlight is styled from it.
Each nav on the page has a unique label.
Run a free scan for the countable problems, then test the navigation by keyboard, on a phone and with the pointer.

Agent Ready Website: What AI Browser Agents Need to Read

Denis Omerovic — Fri, 16 Oct 2026 07:19:18 +0000

Originally published at AccessGuard.

A browser agent is software that opens a web page and uses it on someone's behalf: it reads the page, picks a link, fills in a form, presses the button. If your site's buttons have no names, its form fields have no labels and its menus are built from bare div elements, the agent gets stuck in the same places a screen reader user does. That is the whole idea behind an agent ready website, and it is good news, because the fix is work you can already measure against WCAG 2.2.

This guide explains what agents read, the five failures that stop them, the markup that fixes each one, and how to check your own site. You can run a free accessibility scan on any page while you read, and our AI agent readiness page maps each need to the check that finds it.

How a browser agent reads your page

Agents differ, and they change often, but they read a page in some mix of three ways:

The HTML the browser has rendered: element types, attributes and text.
The accessibility tree. The browser builds this from the HTML for assistive technology. Each node has a role (button, link, textbox, heading), an accessible name and a state (checked, expanded, disabled). It is what a screen reader reads aloud.
Screenshots, read by a vision model, with clicks sent as screen coordinates.

Some of this is documented by the people who build them. Microsoft's Playwright MCP server, which lets an AI model drive a browser, says it "uses Playwright's accessibility tree, not pixel-based input". OpenAI's publishers and developers FAQ says its Atlas browser uses ARIA, the same roles and labels screen readers rely on, to understand page structure and controls, and advises site owners to follow WAI-ARIA best practices for buttons, menus and forms. Anthropic's computer use tool works the other way, from screenshots, with click coordinates "in screenshot pixels".

So an agent that reads the tree needs the structure to be in the markup, and an agent that reads pixels needs what is on screen to be legible and big enough to hit. Both are WCAG topics.

Is your website AI ready? The five failures that stop agents

These are the problems that leave an agent with nothing to choose by. Each is also a WCAG failure that hurts people using assistive technology, which is why fixing them is not a bet on any one AI product.

1. Icon buttons with no accessible name

A button that shows only an icon has a role but no name. In the accessibility tree it reads as "button" and nothing else, so a cart button, a search button and a menu button look identical. This fails 4.1.2 Name, Role, Value (Level A).

<!-- Broken: the tree says "button" and nothing more -->
<button class="icon-cart">
  <svg viewBox="0 0 24 24">...</svg>
</button>

<!-- Fixed: the tree says "button, View cart" -->
<button class="icon-cart" aria-label="View cart">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">...</svg>
</button>

Our ARIA checker flags buttons and links with no name. The same rule applies to linked logos and image links, where the name comes from the alt text (see how to write alt text).

2. Custom controls with no role

A div with a click handler looks like a button and acts like one for a mouse. To the accessibility tree it is a generic container with some text in it, so an agent that looks for interactive elements may not find it, and a keyboard cannot reach it. That fails 4.1.2 and 2.1.1 Keyboard.

<!-- Broken: a generic element with a click handler -->
<div class="btn" onclick="addToCart()">Add to cart</div>

<!-- Fixed: a real button, focusable and announced as one -->
<button type="button" onclick="addToCart()">Add to cart</button>

The same goes for custom dropdowns, tabs and toggles. If you build them yourself, they need the right role and state, as in aria-expanded="true" on a menu button, so the tree says what they are and whether they are open. Our guide to ARIA attributes covers the patterns, and the keyboard accessibility checker flags click handlers with no keyboard access.

3. Form fields with no programmatic label

A placeholder is not a label. It disappears when someone types, and a field labelled only by nearby text has no name in the accessibility tree. An agent filling a checkout form then has to guess which box is the postcode. This fails 1.3.1 Info and Relationships and 4.1.2.

<!-- Broken: no label, only a placeholder -->
<input type="text" name="zip" placeholder="ZIP">

<!-- Fixed: a label tied to the field, and the purpose stated -->
<label for="zip">ZIP or postal code</label>
<input type="text" id="zip" name="zip" autocomplete="postal-code">

The autocomplete value is a bonus: it states the field's purpose in a fixed vocabulary that browsers and password managers already understand (1.3.5 Identify Input Purpose). The form label checker finds unlabelled fields, and our accessible forms guide covers errors and grouping.

4. Names that do not match what is on screen

An agent working from a screenshot sees the word on the button. An agent working from the tree sees the accessible name. When they disagree, the two kinds of agent are looking at different pages, and so are people who use voice control. WCAG has a criterion for exactly this, 2.5.3 Label in Name (Level A): the accessible name has to contain the visible text.

<!-- Broken: shows "Buy now", the tree says "Proceed" -->
<button aria-label="Proceed">Buy now</button>

<!-- Fixed: let the visible text be the name -->
<button>Buy now</button>

Most of the time the fix is to delete an aria-label that was never needed. Visible text already names a button.

5. Links and structure that all look the same

Ten links called "Read more" are ten identical entries in the accessibility tree. A page with no headings and no main landmark gives an agent no way to skip the navigation and find the content. Link text that says where it goes (2.4.4 Link Purpose) and a real heading outline with landmarks (1.3.1) fix both, and the link text checker finds the vague ones.

What helps agents that read screenshots

For a vision model, the page is a picture. What helps a person with low vision tends to help here too: text with enough contrast to read (contrast requirements), and click targets large enough and far enough apart to hit by coordinates (WCAG 2.5.8 target size). Text set as real HTML text, rather than baked into an image, is readable either way.

Some things that block agents are outside WCAG altogether: bot checks, sign-in walls, rate limits, cookie banners that cover the page. Whether you want agents to get past those is a business decision, not an accessibility one, and an audit will not answer it.

How to check if your website is AI agent ready

You can see your site the way a tree-reading agent sees it in a few minutes, with tools you already have.

Look at the accessibility tree in Chrome

Open DevTools, go to the Elements panel, open the Accessibility tab and turn on Show accessibility tree. The DOM is replaced by the full page tree. Walk through your main task, such as add to cart or book a call, and look at every control on the way. Each one should have a role you would expect and a name you could act on. "button" with no name, "generic" where a button should be, and "textbox" with no name are the three things to look for.

Dump the tree with Playwright

If you write tests, Playwright's ARIA snapshots give you "a YAML representation of the accessibility tree" of a page or part of it, one element per line with its role and name:

// Prints the checkout form as an agent reading the tree sees it
const tree = await page.locator('form#checkout').ariaSnapshot();
console.log(tree);
// - textbox "Email"
// - textbox "ZIP or postal code"
// - button "Place order"

Store the snapshot and compare it in CI, and a later release that drops a label or a name fails the build instead of reaching users.

Do the keyboard pass

Tab through the same task without a mouse. Anything you cannot reach or operate with the keyboard usually has a role problem underneath, and that is what trips a tree-reading agent too. Our keyboard testing guide has the full procedure, and if the task opens a dialog, the accessible modal dialog guide covers what it has to do.

Scan for the patterns

Our free scan runs automated WCAG 2.2 AA checks in a real browser and finds the unnamed buttons, unlabelled fields, clickable divs and vague links across a page in a couple of minutes. It does not give an agent readiness score, and it cannot tell you whether a particular agent can finish a particular task. Automated checks find many real problems but cannot confirm that a page conforms to WCAG, and nobody can promise that fixing them changes how any AI product treats your site, since they do not publish that.

What to tell a client or a manager

Keep it to three sentences. AI agents that browse for people read the same labels and structure screen readers use, and at least one of the companies building them, OpenAI, tells site owners to follow WAI-ARIA best practices for that reason. The problems that stop agents are WCAG failures we can find and fix, so the work pays off for disabled visitors whatever happens with agents. We will not promise more traffic from AI, because nobody can.

Checklist

Every button and link has a name in the accessibility tree, including icon buttons and image links.
Every interactive element is a real button, a, input or select, or has the right role and state.
Every form field has a label, and personal data fields have an autocomplete value.
Accessible names contain the visible text.
Links say where they go, and the page has headings and a main landmark.
Text has enough contrast and targets are at least 24 by 24 CSS pixels or spaced to match.
You have walked your main task in the accessibility tree and with the keyboard.
You have run a free scan on the pages that matter and fixed what it found.

Color Contrast Requirements: WCAG 2.0, 2.1, 2.2 and the ADA

Denis Omerovic — Wed, 14 Oct 2026 07:14:02 +0000

Originally published at AccessGuard.

Someone has asked you what contrast ratio the law requires. Maybe a client who got a letter about the ADA, a designer defending a pale gray, or a manager who read that "WCAG 2.2 changed everything". The short answer is the same in almost every case: 4.5:1 for normal text and 3:1 for large text, plus 3:1 for the parts of buttons, inputs and icons people need to see. That has been the Level AA rule since WCAG 2.0, and no later version or US law has changed the numbers.

If you only need to check a pair of colors, the free color contrast checker gives you the ratio and the AA verdict in a few seconds. The rest of this guide explains where each number comes from, which version and which law points at which level, and what to say when someone asks whether a ratio makes a site "ADA compliant".

The ratios at a glance

Every number below comes from the WCAG 2.2 Recommendation and its Understanding documents at the W3C, linked in each row.

WhatLevel AALevel AAACriterion

Normal text and images of text4.5:17:11.4.3 (AA), 1.4.6 (AAA)
Large text (18pt, or 14pt bold)3:14.5:11.4.3 (AA), 1.4.6 (AAA)
Parts of user interface components and graphics needed to understand them3:1No higher level1.4.11 (AA)
Focus indicator, focused against unfocused stateNot required3:12.4.13 (AAA)

Three details catch people out:

No rounding. The W3C says computed values "should not be rounded", and gives the example that 4.499:1 does not meet 4.5:1 (Understanding 1.4.3). A checker that shows 4.5 for a pair that is really 4.47 is hiding a failure.
Large text is measured in points. The same document puts 1pt at 1.333 CSS pixels, so 18pt is about 24px and 14pt is about 18.5px. Bold at 18.5px counts as large; regular weight at 18.5px does not.
Some text has no requirement. Text in an inactive control, pure decoration, text nobody can see, text inside a photo with other significant content, and logos and brand names are all exempt under 1.4.3.

WCAG 2.0, 2.1 and 2.2: what changed for contrast

Most searches about contrast name a version, as if each one set a new number. They did not. Here is what each version did.

WCAG 2.0 (2008)

WCAG 2.0 introduced both text criteria: 1.4.3 Contrast (Minimum) at AA with 4.5:1 and 3:1, and 1.4.6 Contrast (Enhanced) at AAA with 7:1 and 4.5:1. It said nothing about the contrast of borders, icons or focus outlines, so a pale gray input border passed 2.0 as long as its label text was dark enough.

WCAG 2.1 (2018)

WCAG 2.1 kept 1.4.3 and 1.4.6 as they were and added 1.4.11 Non-text Contrast at Level AA, one of 17 new criteria (W3C, What's new in WCAG 2.1). It asks for 3:1 against adjacent colors for:

the visual information needed to identify a control and its state, such as an input's border, a checkbox's box or the fill of a toggle, unless the control is inactive or its look comes from the browser unchanged;
the parts of a graphic needed to understand it, such as the lines in a chart or an icon that carries meaning.

This is the change that matters most in practice. A site that met 2.0 can fail 2.1 without a single text color changing, because of light form borders and pale icons.

WCAG 2.2 (2023)

WCAG 2.2 changed none of the ratios. The W3C says the 2.0 and 2.1 criteria "are essentially the same in 2.2, with one exception: 4.1.1 Parsing is obsolete and removed" (What's new in WCAG 2.2). Of the nine new criteria, one involves a ratio: 2.4.13 Focus Appearance, which asks for a focus indicator at least as large as a 2 CSS pixel perimeter of the component, with 3:1 between the same pixels focused and unfocused. It is Level AAA, so it is not part of an AA target.

So if you test against WCAG 2.2 AA, you are testing the same contrast rules as 2.1 AA. If you test against 2.0 AA, you are missing 1.4.11.

Why 4.5:1 and not some other number

Clients sometimes treat the number as arbitrary. The W3C explains it in Understanding 1.4.3: 3:1 is the minimum that the ISO 9241-3 and ANSI/HFES 100-1988 standards recommend for standard text and vision, and the ratio is raised to 4.5:1 to make up for the contrast lost by someone with moderately low visual acuity, about 20/40. That is a useful line for a client meeting: the rule is sized for a common level of vision loss, not for rare cases.

What the ADA and other laws actually require

No US law sets a contrast ratio of its own. Each one points at WCAG, and the version and level it points at decide which rows of the table apply.

RuleWho it coversStandard it points to

ADA Title II web ruleUS state and local governments, including public schools and collegesWCAG 2.1 AA (89 FR 31320)
ADA Title IIIBusinesses open to the publicNo technical standard in the regulations; the Justice Department calls WCAG "helpful guidance" (ADA.gov, 2022)
Section 508US federal agencies and what they buyWCAG 2.0 AA (Access Board, E205.4)
European Accessibility ActMany products and services sold in the EUEN 301 549; version 4.1.1, published in September 2026, points to WCAG 2.2 AA (AccessibleEU)

A few practical readings of that table:

Title II sites need 1.4.11. Because the rule adopts 2.1 AA, a city or college site has to meet the 3:1 non-text rule as well as the text ratios. The compliance dates moved to April 2027 and April 2028 in an interim rule this year; our guide to the Title II deadline extension has the details, and the ADA Title II web rule page has the summary.
Title III has no number in law. When someone says "the ADA requires 4.5:1", what is true is that WCAG AA requires it and WCAG AA is the benchmark most businesses use. The Justice Department's own guidance names "poor color contrast" as an example of a barrier, which is a good reason to treat it as a priority. See ADA website compliance for how Title III works.
Section 508 still cites 2.0. A federal client's formal requirement does not include 1.4.11, but testing against 2.1 or 2.2 AA covers everything 2.0 asks for and more.
Nobody's law requires AAA. None of these rules points at Level AAA, and the W3C itself does not recommend requiring AAA as a general policy for entire sites, because some content cannot meet it (Understanding Conformance). 7:1 is a good choice for body text when the brand allows it, not an obligation.

What to tell a client or a manager

Clients usually want one sentence. Something like this is accurate:

"WCAG Level AA, which the ADA rules and guidance point to, asks for 4.5:1 on body text, 3:1 on large headings and 3:1 on borders and icons people need to see. Our current gray fails that, and darkening it fixes it without changing the look of the brand."

What not to say: that meeting the ratios makes a site compliant. Contrast covers two of the 55 Level A and AA success criteria in WCAG 2.2 (our WCAG 2.2 checklist lists them all), and passing one says nothing about the others. The same goes for any scan, ours included: an automated check measures text on solid backgrounds reliably, but text over photos and gradients needs a person to judge.

How to check a site against these numbers

For a single pair of colors, a calculator is enough. For a site, the failures are usually in places nobody picked colors on purpose: placeholder text, disabled-looking buttons that are still active, light borders on inputs and icon-only links.

/* Broken: #999 on white is 2.85:1, fails 4.5:1 for body text */
.form-hint {
  color: #999999;
}

/* Fixed: #767676 on white is 4.54:1, passes AA for normal text */
.form-hint {
  color: #767676;
}

/* Broken: #ddd input border on white is 1.36:1, fails 1.4.11 */
input {
  border: 1px solid #dddddd;
}

/* Fixed: #8a8a8a on white is 3.45:1, passes 3:1 for non-text contrast */
input {
  border: 1px solid #8a8a8a;
}

Run the ratios in your own checker before you ship them; brand colors rarely land on these exact grays. When a brand color fails, our guide to WCAG color contrast ratios walks through darkening it step by step, testing text over images, and handling a client who will not change the palette.

To find every failing pair on a page at once, run a free audit. AccessGuard runs automated WCAG 2.2 AA checks in a real browser, so it measures the colors the page actually renders, including ones set by a theme or a plugin, and lists each failing element with its ratio.

Checklist

Decide the target first: WCAG 2.1 AA for a Title II client, 2.2 AA for anyone selling into the EU, and 2.2 AA as a sensible default for everyone else, since it covers the older versions' contrast rules.
Check body text at 4.5:1 and large text (24px, or about 18.5px bold) at 3:1. Do not round.
Check input borders, checkboxes, toggles, meaningful icons and chart lines at 3:1 against what is next to them.
Check hover, focus and error states, not only the default state.
Have a person look at text over images and gradients.
Write the target version and level into the brief or the contract, so "compliant" never becomes the promise.

Start with the color contrast checker for the brand palette, then scan the pages that matter to see where those colors end up.

WCAG 2.5.8 Target Size: The 24px Minimum and Its Exceptions

Denis Omerovic — Mon, 12 Oct 2026 07:13:26 +0000

Originally published at AccessGuard.

A WCAG 2.2 scan flags a row of small icons, a pagination bar and a close button, and the question that follows is always the same: do we really have to make all of these 24 pixels? Often you don't. The number in 2.5.8 is short, but the exceptions do most of the work, and the spacing exception alone clears a lot of controls without touching their size.

This guide gives the exact rule, the spacing exception with real measurements, the patterns that fail most often, and fixes that leave the design alone. To see which controls on a page are too small right now, run the page through our target size checker. It measures every button and link in a browser against the 24 by 24 minimum.

What the criterion requires

Success Criterion 2.5.8 Target Size (Minimum) is Level AA and was added in WCAG 2.2, which W3C published as a Recommendation in October 2023 (W3C, WCAG 2.2). Its text, from W3C's Understanding 2.5.8:

"The size of the target for pointer inputs is at least 24 by 24 CSS pixels, except when:"

Spacing: the target is smaller, but a 24 CSS pixel circle centered on it does not touch another target or another small target's circle.
Equivalent: "The function can be achieved through a different control on the same page that meets this criterion."
Inline: "The target is in a sentence or its size is otherwise constrained by the line-height of non-target text."
User agent control: "The size of the target is determined by the user agent and is not modified by the author."
Essential: "A particular presentation of the target is essential or is legally required for the information being conveyed."

Three details matter before you measure anything:

Both dimensions count. W3C calls a target "undersized" when it is smaller than 24 by 24. A footer link 120 pixels wide and 18 pixels tall is undersized.
The target is the clickable area, not the icon. A 16 pixel icon inside a 24 pixel button passes.
CSS pixels, not device pixels. This is the size in your stylesheet and in the browser's dev tools, whatever the screen density.

24 is not 44

The 44 by 44 figure you see in design systems belongs to 2.5.5 Target Size (Enhanced), which is Level AAA: "The size of the target for pointer inputs is at least 44 by 44 CSS pixels" (W3C, Understanding 2.5.5). An AA audit tests 24. W3C still suggests aiming for the larger size "for important links/controls", and that is good advice for a primary button. It is not a failure of AA.

The spacing exception, measured

This is the exception that saves most redesigns, and it is easier to apply than it reads. W3C's test (technique C42) for each undersized target:

Draw a 24 CSS pixel diameter circle centered on the target's bounding box.
Check that the circle does not intersect any other target.
Check that the circle does not intersect any other undersized target's circle.

Both checks pass, and the small target passes. Turned into numbers for targets side by side, two rules of thumb fall out:

Two small targets next to each other pass when their centers are at least 24 pixels apart. For equal targets, that is size plus gap is at least 24.
A small target next to a full size one passes when the gap is at least 12 minus half the small target's size, because its circle (radius 12) must not reach the bigger target.

LayoutDistance between centersResult

20 by 20 buttons, no gap20pxFails: circles overlap
20 by 20 buttons, 4px gap24pxPasses (W3C's own example)
16 by 16 icons, 4px gap20pxFails
16 by 16 icons, 8px gap24pxPasses
16 by 16 icon, 4px from a 40px buttonCircle reaches 12px, button starts 12px awayPasses
Stacked links 18px tall, no gap18pxFails
Stacked links 18px tall, 6px gap24pxPasses

Two edge cases from the Understanding document. If targets overlap, the overlapping area is left out of the size. If a target is not a rectangle (rounded, clipped or an SVG shape), the circle goes on the center of its bounding box, which for an odd shape may sit outside the shape itself.

One honest caveat: passing on spacing does not make a control easy to use. W3C says so directly: "It is still possible to have very small, and difficult to activate, targets and meet the requirements of this Success Criterion." Spacing is a pass, not a recommendation.

The inline, user agent and essential exceptions

Inline

Links inside a sentence are exempt. W3C's reason is that text reflows with the viewport, so an author cannot know where links will land next to each other. The fix for crowded text links is readable line height, not bigger links. Note what this does not cover: a list of links stacked in a footer or sidebar is not a sentence, so treat each one as a target and measure it.

User agent control

If the browser draws the control and you have not resized it, it is exempt. W3C's examples are the day grid in <input type="date"> and the browser's scrollbars. The exception ends the moment your CSS changes the size: a native checkbox shrunk to 12 pixels, or a restyled thin scrollbar, is yours to measure.

Essential

This applies when the position or size carries the information. W3C's example is pins on a map: they must sit where the places are, even when that puts them close together. Forms that law requires to copy a paper layout are the other example. "Our designer prefers small icons" is not essential.

Equivalent

A small control passes if the same function is available through another control on the same page that meets the criterion. A tiny "edit" icon in a table row can pass if the row also opens a full size edit menu. Write down which control is the equivalent in the audit, because a reviewer will ask.

Five patterns that usually fail

Icon-only social rows. Sixteen pixel icons with a few pixels between them. Under 24 pixels between centers, so they fail on spacing too.
Table row actions. Edit, duplicate and delete icons packed at the end of each row. They fail unless a full size equivalent exists, and a slip here deletes the wrong record.
Close buttons. A 14 pixel "x" in a dialog corner. Often it passes on spacing because nothing else is near it, so check the circle before you file it. It is still worth enlarging.
Pagination. Single digit page numbers are usually narrower than 24 pixels, with little space between them. This is the case technique C42 was written for.
Footer link lists. Wide but short, stacked with no space between them. The height is the problem, and the inline exception does not apply.

How to fix without redesigning

Almost every fix makes the clickable area bigger and leaves the visible icon the same size.

Give the link the size, not the icon

/* Broken: the link is only as big as its 16px icon */
.social a {
  display: inline-block;
}

/* Fixed: the icon stays 16px, the target is 24px */
.social a {
  display: inline-grid;
  place-items: center;
  min-width: 24px;
  min-height: 24px;
}
.social a svg {
  width: 16px;
  height: 16px;
}

Or use the spacing exception on purpose

When a toolbar really has to stay compact, set the gap from the table above instead of guessing. For 16 pixel icons that is an 8 pixel gap.

/* Broken: 16px buttons, 4px apart, 20px between centers */
.row-actions {
  display: flex;
  gap: 4px;
}

/* Fixed: 8px apart, 24px between centers */
.row-actions {
  display: flex;
  gap: 8px;
}

Pagination and footer lists: minimums on the container

This is W3C's own technique C42, minimum sizes on each item:

/* Fixed: every page number and footer link is at least 24 by 24 */
.pagination li,
.footer-links li {
  min-height: 24px;
  min-width: 24px;
}
.pagination a,
.footer-links a {
  display: inline-flex;
  align-items: center;
  min-height: 24px;
}

Put the size on the a as well as the li. A 24 pixel list item with an 18 pixel link inside it still has an 18 pixel target, because only the link responds to the click.

Checkboxes and radios you restyled

A native checkbox at the browser's default size is a user agent control and exempt. A custom one is not: once your CSS draws the box, the box is yours to size.

/* Broken: a custom checkbox drawn at 14px */
.check input {
  appearance: none;
  width: 14px;
  height: 14px;
}

/* Fixed: the same style at the minimum size */
.check input {
  appearance: none;
  width: 24px;
  height: 24px;
}

Wrap the input in its label while you are there, so the text is clickable too and the label association a form audit checks is in place. Our guide to accessible forms covers that part.

What to tell a client or a manager

Keep it to three sentences. WCAG 2.2 added a Level AA rule that buttons and links must be at least 24 pixels, or spaced so a slip does not hit the neighbor. It helps anyone tapping on a phone, people with tremors and people using a device on a moving bus, all groups W3C names. The fix is usually CSS on the click area and nobody will see a design change.

Be careful with the words you use: fixing target sizes clears one criterion. It does not make a site compliant, and neither does a clean automated scan. The WCAG 2.2 checklist lists every A and AA criterion, and our guide to the nine new WCAG 2.2 criteria puts this one next to the others 2.2 added.

Checklist

Run the page through the target size checker, or a free accessibility audit for the rest of WCAG 2.2 AA at the same time.
For each flagged control, check the exceptions in order: is it in a sentence, drawn by the browser, essential, or duplicated by a full size control?
For the rest, measure the distance between centers. 24 pixels or more passes on spacing.
Fix with min-width, min-height and padding on the clickable element, not on the icon.
Recheck at a phone width, where layouts often draw controls smaller.
Treat 44 by 44 as the goal for primary actions, and 24 as the line an AA audit draws.

Lighthouse Accessibility Score: Why 100 Is Not an Audit

Denis Omerovic — Mon, 28 Sep 2026 07:15:45 +0000

Originally published at AccessGuard.

Sooner or later a client, a manager or a colleague opens Chrome DevTools, runs Lighthouse, sees a green 100 in the Accessibility circle, and asks why anyone needs an audit. It is a fair question, and it deserves a better answer than "trust me". This guide explains what the Lighthouse accessibility score measures, what it cannot see, and gives you words to use in that conversation.

Short version: a 100 means the page passed every automated test Lighthouse ran on it. That is worth having. It does not mean people with disabilities can use the page, and the Lighthouse report says so itself, in the line directly under the score: "Automatic detection can only detect a subset of issues and does not guarantee the accessibility of your web app, so manual testing is also encouraged."

What the Lighthouse accessibility score actually measures

Lighthouse runs a set of automated audits against one URL. In Google's words, you "give Lighthouse a URL to audit, it runs a series of audits against the page, and then it generates a report" (Lighthouse overview). Three details in the Lighthouse accessibility scoring documentation matter for how you read the number:

It is a weighted average. "The Lighthouse Accessibility score is a weighted average of all accessibility audits. Weighting is based on axe user impact assessments." The audits come from axe-core, Deque's open source testing engine, and each carries a weight of 10, 7 or 3.
Each audit is pass or fail. A page with one unnamed button out of twenty scores the same zero on that audit as a page where all twenty are unnamed.
Manual checks do not count. "Manual audits and low-impact / best-practices audits aren't included in the table because they don't affect your score."

Two more things follow from how the tool runs. It tests the page as it looks when it finishes loading, in the viewport you chose, so a menu that is closed, a modal that has not opened and an error message that only appears after submitting a form are never tested. And it tests one page, not the checkout, the account area or the other templates on the site.

The checks Google lists as manual

This is the most useful fact for the client conversation, because it comes from Google rather than from someone selling an audit. Below the score, every Lighthouse report has a section called "Additional items to manually check" with ten items, each described in the Lighthouse accessibility audits docs:

Custom controls have ARIA roles
Custom controls have associated labels
User focus is not accidentally trapped in a region
Interactive controls are keyboard focusable
Interactive elements indicate their purpose and state
The page has a logical tab order
The user's focus is directed to new content added to the page
Offscreen content is hidden from assistive technology
HTML5 landmark elements are used to improve navigation
Visual order on the page follows DOM order

None of these affect the score. A page can fail every one and still show 100. Most of them are about keyboard use, which is exactly where people who cannot use a mouse get stuck.

Four things a 100 cannot tell you

1. Whether the alt text is right

The scored audit is "Image elements have [alt] attributes". It checks that the attribute exists. It cannot tell whether the text describes the image. Both of these pass:

<!-- Broken: passes the audit, tells a screen reader user nothing -->
<img src="team.jpg" alt="IMG_2041.jpg">

<!-- Fixed: describes what the image shows in this context -->
<img src="team.jpg" alt="Our four support staff at the Leeds office">

Whether a text alternative "serves the equivalent purpose" is the actual requirement in WCAG 1.1.1 Non-text Content, and that takes a person. An alt text checker finds the missing ones fast; our guide on how to write alt text covers the rest.

2. Whether keyboard focus gets trapped

"User focus is not accidentally trapped in a region" is on Google's manual list. Its own documentation tells you how to test it: "navigate to and from all page elements using only the keyboard", with Tab going forward and Shift + Tab going back (Lighthouse: trapped user focus). A date picker or chat widget that swallows focus fails 2.1.2 No Keyboard Trap while the score stays at 100. Our guide on how to test keyboard accessibility by hand walks through it, and the keyboard and focus checker flags the markup causes it can see.

3. Whether the reading order makes sense

CSS grid, flexbox order and absolute positioning can put things on screen in a different order from the HTML. A screen reader and the Tab key follow the HTML. If the "Add to cart" button comes before the product name in the source, it passes every automated audit and still confuses people. That is 1.3.2 Meaningful Sequence and 2.4.3 Focus Order, and "Visual order on the page follows DOM order" sits on the manual list.

4. Whether a control's name matches what people see

The scored audit "Buttons have an accessible name" passes if there is any name at all. It does not compare that name with the visible label:

<!-- Broken: has a name, but not the one on screen -->
<button aria-label="Submit form">Get my quote</button>

<!-- Fixed: the name contains the visible words -->
<button>Get my quote</button>

A voice control user who says "click Get my quote" gets nothing, because the button is called "Submit form". That fails 2.5.3 Label in Name.

Checks that need a person, by WCAG criterion

This is not a complete list, but it covers what most reviews catch that automated scores miss.

WCAG criterionWhat a person checks

1.1.1 Non-text ContentAlt text describes the image; decorative images are empty
1.3.2 Meaningful SequenceReading order matches the visual order
2.1.1 Keyboard, 2.1.2 No Keyboard TrapEvery control works with Tab, Enter, Space and Escape, and focus can always leave
2.4.3 Focus OrderTab moves through the page in a sensible order, including into and out of modals
2.4.6 Headings and LabelsHeadings and labels describe their content, not just exist
2.5.3 Label in NameThe accessible name contains the visible label
3.3.1 Error IdentificationErrors after submitting are described in text and announced
4.1.3 Status MessagesMessages like "Added to cart" reach screen readers without moving focus

Every criterion links from the WCAG 2.2 specification to its Understanding document, which says what passing looks like.

What to say when someone points at the score

Keep it calm and give them Google's own words. The best ones are already on their screen, under the score: "Automatic detection can only detect a subset of issues and does not guarantee the accessibility of your web app, so manual testing is also encouraged." Something like:

"The 100 is real and it is good news: the page passes every automated test Lighthouse runs. The report itself says automatic detection only finds a subset of issues. It also lists ten things to check by hand, like keyboard traps and tab order, and Google's documentation says those don't affect the score. So a 100 tells us the basics are in place on this one page as it loaded. The audit is the part a tool can't do: someone using the site with a keyboard and a screen reader, across the templates that matter, like checkout and the contact form."

If they want evidence that tools miss things, the UK Government Digital Service built a page with 143 deliberate barriers and ran 10 automated tools against it in 2017. 42 of the barriers were missed by every tool. Tools have improved since, so treat it as a demonstration of the gap rather than a current measurement. Avoid quoting a single percentage of issues that automation catches unless you can name the study behind it.

Two things not to say: that an audit will make the site "compliant", or that the score is worthless. Neither is true, and the second one undermines the tools you will use yourself.

Where an automated scan still earns its keep

Automated checks are fast, repeatable and good at the problems they can decide: missing alt attributes, unlabelled fields, low contrast, invalid ARIA, missing page language. Run them first so the manual review is spent on judgement, not on counting empty alt attributes. Rerun them after every release so fixed problems stay fixed.

The limits of Lighthouse are one page at a time, in one state. A free AccessGuard scan runs axe-core plus its own checks in a real browser and reports failures against WCAG 2.2 AA, including some that axe alone does not catch (see the six checks most scanners miss). It is still an automated scan: it finds many problems, and it cannot confirm that a site conforms to WCAG. No automated tool can.

Your next steps

Run Lighthouse or a free scan and fix every automated failure first.
Open the "Additional items to manually check" section of the Lighthouse report and work through it.
Tab through each key template: home, a content page, search, forms, checkout.
Read the alt text on important images out loud: does it say what the image shows?
Compare visible button labels with their accessible names in DevTools.
Write down what you checked by hand, so the report shows the work behind the result, not just a score.

Keyboard Navigation Accessibility: A Complete WCAG Guide

Denis Omerovic — Fri, 25 Sep 2026 07:16:33 +0000

Originally published at AccessGuard.

Not everyone uses a mouse

It's easy to assume that everyone navigates the web the way you do - clicking with a mouse or tapping on a touchscreen. But many people rely on a keyboard as their primary or only means of interaction.

People with motor disabilities may use a keyboard, a switch device, or voice recognition software - all of which interact with web pages through the same keyboard interface. Screen reader users navigate almost entirely by keyboard. Power users often prefer keyboard shortcuts for speed. And anyone with a temporarily broken mouse or trackpad needs keyboard access as a fallback.

Keyboard accessibility isn't an edge case. It's the foundation that makes all other assistive technologies work. If your site isn't keyboard accessible, it's likely inaccessible to screen readers, voice control, and switch devices as well.

How keyboard navigation works

Understanding the basics of keyboard navigation helps you test and build accessible interfaces.

The essential keys

Tab - moves focus to the next interactive element (links, buttons, form fields)
Shift + Tab - moves focus to the previous interactive element
Enter - activates the focused element (follows links, submits buttons)
Space - activates buttons, toggles checkboxes, opens select menus
Arrow keys - navigate within components (radio groups, dropdown menus, tabs, sliders)
Escape - closes modal dialogs, menus, and popups

With just these keys, a user should be able to reach and operate every interactive element on your page. If they can't, you have a keyboard accessibility problem.

Focus order

When a user presses Tab, focus moves through interactive elements in DOM order - the order elements appear in your HTML source code. This is why it's important that your visual layout matches your source order. If CSS visually rearranges elements (using flexbox order, grid placement, or absolute positioning), the tab order might not match what a sighted user expects.

The fix is to change the source order, not to patch it with tabindex. A positive tabindex (1 or higher) pulls an element ahead of everything else on the page and almost always makes the order worse. WCAG 2.4.3 Focus Order (Level A) asks that focus moves "in an order that preserves meaning and operability" (WCAG 2.2).

<!-- Broken: tabindex forces this link ahead of the whole header -->
<a href="/offer" tabindex="3">Today's offer</a>

<!-- Fixed: move it in the source, and leave tabindex out -->
<a href="/offer">Today's offer</a>

Focus indicators - making focus visible

When a keyboard user tabs through a page, they need to see which element currently has focus. This visual indicator is called the focus ring or focus indicator.

Browsers provide a default focus indicator (usually a blue or dotted outline), but many websites remove it with CSS like outline: none or *:focus { outline: 0; } because designers find it aesthetically displeasing. This is one of the most harmful accessibility patterns on the web - it makes keyboard navigation essentially unusable.

Best practices for focus indicators

Never remove focus indicators without providing a replacement. If you remove the default outline, you must add a custom one that's equally visible.
Make focus indicators visible against all backgrounds. A thin blue outline works on white but may be invisible on a blue background. Use a combination of outline offset, contrasting colors, or multiple indicators.
Use :focus-visible for the best of both worlds. The :focus-visible pseudo-class only applies focus styles when focus was triggered by keyboard (not mouse click), reducing visual noise for mouse users while keeping indicators for keyboard users.

A good custom focus indicator might look like this:

/* Broken: removes the indicator and replaces it with nothing */
*:focus { outline: none; }

/* Fixed: a visible ring for keyboard users, no ring on mouse clicks */
:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 2px;
}

WCAG 2.2 added a measurable requirement for focus appearance: an indicator at least as large as a 2 CSS pixel perimeter of the component, with a contrast ratio of at least 3:1 between the focused and unfocused states. That is criterion 2.4.13 Focus Appearance, and it is Level AAA, not AA (WCAG 2.2). The AA requirement is 2.4.7 Focus Visible, which asks only that the indicator be visible, so treat 2.4.13 as the bar to design to rather than as an AA failure in a client report. WCAG 2.2 also added 2.4.11 Focus Not Obscured (Minimum) at Level AA, which a sticky header or cookie banner covering the focused element will fail. For a sticky header, scroll-padding-top set to the header's height keeps the focused element in view when the browser scrolls to it:

/* Fixed: leave room for a 72px sticky header when scrolling to focus */
html { scroll-padding-top: 72px; }

Skip links - bypassing repeated content

Imagine having to Tab through an entire navigation menu with 30 links on every single page before reaching the main content. For keyboard users, this is exhausting and time-consuming.

Skip links solve this by providing a link at the very top of the page that jumps directly to the main content area. It's typically hidden until it receives focus, so it doesn't affect the visual design:

<!-- Broken: the target cannot take focus, so the next Tab returns to the nav -->
<a href="#main">Skip to content</a>
...
<div id="main">

<!-- Fixed: the target is a real landmark and can take focus -->
<a href="#main" class="skip-link">Skip to content</a>
...
<main id="main" tabindex="-1">

The CSS hides it visually until focused:

.skip-link { position: absolute; top: -40px; left: 0; }
.skip-link:focus { top: 0; }

This is a WCAG Level A requirement: 2.4.1 Bypass Blocks asks for "a mechanism" to "bypass blocks of content that are repeated on multiple web pages" (WCAG 2.2). It takes minimal effort to implement, and the tabindex="-1" on the target is the detail most versions leave out.

Keyboard traps - the cardinal sin

A keyboard trap occurs when a user can Tab into an element but cannot Tab out of it. They're stuck, unable to navigate to other parts of the page without using a mouse - which they may not be able to do.

Common sources of keyboard traps include:

Embedded content - iframes, embedded maps, and third-party widgets can trap focus inside their boundaries
Custom rich text editors - editors that capture Tab for indentation can prevent users from tabbing away
Modal dialogs without proper focus management - a modal should trap focus within itself while open (this is correct behavior) but must release focus when closed
Autofocusing scripts - JavaScript that forces focus back to a specific element whenever the user tries to leave

WCAG criterion 2.1.2 (No Keyboard Trap, Level A) prohibits this. When you build a component that handles Tab itself, such as an editor or a modal, give it a documented way out: Escape, or Tab once the user leaves the last field.

Making custom components keyboard accessible

Native HTML elements like <button>, <a>, and <input> are keyboard accessible by default - they receive focus, respond to Enter/Space, and announce themselves to screen readers. Problems arise when developers build custom interactive elements from non-interactive HTML.

A clickable <div> with a JavaScript click handler is invisible to keyboard users - it doesn't appear in the tab order, and pressing Enter does nothing. To make it accessible, you'd need to add:

tabindex="0" - puts the element in the natural tab order
role="button" - tells assistive technologies it's a button
A keydown handler for Enter and Space
Proper focus styles

Or you could just use a <button> element and get all of this for free. The simplest rule for keyboard accessibility: use native HTML elements whenever possible. A <button> instead of a <div onclick>. An <a href> instead of a <span onclick>. Native elements handle keyboard interaction, focus management, and screen reader announcements automatically.

Testing keyboard accessibility

This guide is about building it. To check a finished page, follow our step by step manual keyboard accessibility test: what to press, what to look for at each stop and the WCAG criterion to write in the report.

How AccessGuard helps with keyboard accessibility

Our keyboard and focus checker looks for the causes a machine can find in the rendered page: divs and spans with click handlers that a keyboard cannot reach, outline: none rules that leave no visible focus, sticky headers and banners that can cover the focused element, positive tabindex values, and controls hidden with opacity: 0 that a keyboard still reaches.

It cannot tell you whether the focus order makes sense, whether a widget traps focus or whether a menu works end to end, and no automated tool can confirm a site conforms to WCAG. Run a free accessibility audit on a page to find the countable problems, then do the manual test for the rest.

Your sticky header hides the focused link. One CSS line fixes it.

Denis Omerovic — Thu, 24 Sep 2026 07:47:17 +0000

Press Tab on a page with a sticky header and keep going past the fold. Sooner or later the focused link scrolls into view underneath the header. The keyboard user has no idea where they are.

Since WCAG 2.2 this is an AA failure with its own number: 2.4.11 Focus Not Obscured (Minimum). W3C's words: "When a user interface component receives keyboard focus, the component is not entirely hidden due to author-created content." The usual causes are named in the Understanding document: "sticky footers, sticky headers, and non-modal dialogs", and a cookie banner "will fail this success criterion if it entirely obscures a component receiving focus".

Why it happens

When an element gets focus off screen, the browser scrolls just far enough to bring it into the viewport. It knows nothing about your position: sticky or position: fixed header, so it happily parks the element at the very top, behind the bar.

The fix

Tell the scroll container how much of it is covered:

:root {
  --header-height: 4rem;
}

html {
  scroll-padding-top: var(--header-height);
}

.site-header {
  position: sticky;
  top: 0;
  height: var(--header-height);
}

scroll-padding defines an inset that scrolling into view respects, so the focused element stops below the header instead of under it. The same property fixes in-page anchor links (#section) landing under the header, so you get two bugs for one line.

A cookie banner or chat button fixed to the bottom needs the other side too:

html {
  scroll-padding-bottom: 6rem; /* height of the bottom banner */
}

If the scrolling happens inside a panel rather than the page, put scroll-padding on that panel, since it applies to the element that scrolls.

Test it in 30 seconds

Load the page fresh, with the cookie banner still showing.
Click the address bar, then press Tab until focus is past the first screen.
Every focused element should be at least partly visible. Minimum means not entirely hidden, but aim for fully visible, which is what 2.4.12 asks for at AAA.
Press Shift + Tab back up, because upward scrolling can hide things under a bottom banner.

Automated scanners mostly can't catch this, because it depends on scroll position and on which element has focus at that moment. It is one of the nine steps in a manual keyboard pass: how to test keyboard accessibility by hand.