Accessibility Guides for Trusted Tester

An image map is an <img> element linked to a <map> element via the usemap attribute. Inside the <map>, individual <area> elements define clickable hotspots that function as links. Each of these <area> elements is essentially a link, and like all links, it must have an accessible name that describes its purpose.

Why This Is an Accessibility Problem

Screen readers cannot interpret graphical content. When a user navigates to a clickable <area> that lacks alternative text, the screen reader has no meaningful label to announce. In many cases, it will fall back to reading the link URL or the image filename — neither of which conveys the purpose of the link. This critically impacts:

• Blind users and deafblind users who rely entirely on screen readers to navigate and interact with content.
• Users with mobility impairments who use assistive technologies like switch devices or voice control, which depend on accessible names to identify interactive elements.

This rule relates to the following WCAG success criteria:

• WCAG 2.4.4 – Link Purpose (In Context) (Level A): The purpose of each link must be determinable from the link text alone, or from the link text combined with its programmatically determined context. An <area> without alternative text has no discernible purpose.
• WCAG 4.1.2 – Name, Role, Value (Level A): All user interface components must have a programmatically determined name. An <area> element is an interactive component, so it requires an accessible name.

This rule also applies under Section 508, EN 301 549, and Trusted Tester requirements.

How to Fix It

Ensure every active <area> element inside a <map> has an accessible name by using one of these methods:

1. alt attribute (preferred) — Add descriptive alt text directly to the <area> element.
2. aria-label attribute — Provide a text label via aria-label.
3. aria-labelledby attribute — Reference another element that contains the label text.

The alt text should clearly describe the purpose or destination of the link, not the visual appearance of the hotspot region.

Also, make sure the parent <img> element has its own alt attribute describing the image as a whole.

Examples

Incorrect: <area> Elements Without Alternative Text

In this example, the <area> elements have no alt text. Screen readers cannot communicate what each clickable region does.

<img src="solar_system.jpg" alt="Solar System" width="472" height="800" usemap="#solar-map">
<map name="solar-map">
  <area shape="rect" coords="115,158,276,192" href="https://example.com/mercury">
  <area shape="rect" coords="115,193,276,234" href="https://example.com/venus">
  <area shape="rect" coords="115,235,276,280" href="https://example.com/earth">
</map>

Correct: <area> Elements With alt Text

Each <area> now has a descriptive alt attribute that communicates the link’s purpose.

<img src="solar_system.jpg" alt="Solar System" width="472" height="800" usemap="#solar-map">
<map name="solar-map">
  <area shape="rect" coords="115,158,276,192" href="https://example.com/mercury" alt="Mercury">
  <area shape="rect" coords="115,193,276,234" href="https://example.com/venus" alt="Venus">
  <area shape="rect" coords="115,235,276,280" href="https://example.com/earth" alt="Earth">
</map>

Correct: Using aria-label Instead of alt

<img src="floor_plan.png" alt="Office floor plan" width="600" height="400" usemap="#office-map">
<map name="office-map">
  <area shape="rect" coords="0,0,200,200" href="/rooms/conference-a" aria-label="Conference Room A">
  <area shape="rect" coords="200,0,400,200" href="/rooms/kitchen" aria-label="Kitchen">
</map>

Incorrect: Server-Side Image Map

Server-side image maps use the ismap attribute and rely on mouse click coordinates sent to the server. These are not keyboard accessible and provide no text alternatives for individual regions. Avoid this pattern entirely.

<a href="/maps/nav.map">
  <img src="navbar.gif" alt="Navigation" ismap>
</a>

Instead, replace server-side image maps with client-side image maps (usemap and <map>) that include proper alt text on each <area>, or use a different navigational pattern altogether such as a standard list of links.

When you assign a role like link, button, or menuitem to an element, you are telling the browser and assistive technologies that this element is an interactive command. Screen readers rely on the accessible name of these elements to communicate their purpose to the user. If no accessible name exists, a screen reader might announce something like “button” or “link” with no additional context — leaving the user with no way to understand what the control does.

This issue primarily affects users who are blind or have low vision and rely on screen readers, but it also impacts users with mobility impairments who may use voice control software to activate elements by name. If there is no name, voice control users cannot target the element with a spoken command.

Related WCAG Success Criteria

This rule maps to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that all user interface components have a name that can be programmatically determined. It applies across WCAG 2.0, 2.1, and 2.2, and is also referenced in EN 301 549 (9.4.1.2), Trusted Tester guidelines, and RGAA.

The Trusted Tester guidelines further specify that the purpose of each link or button must be determinable from some combination of its text, accessible name, accessible description, or programmatically determined context.

How to Fix It

Ensure that every element with role="link", role="button", or role="menuitem" has an accessible name through one of these methods:

1. Inner text content — Place readable text inside the element.
2. aria-label attribute — Add a non-empty aria-label with a descriptive name.
3. aria-labelledby attribute — Point to the id of another element that contains visible, non-empty text.
4. title attribute — Use a title attribute as a fallback (though aria-label or visible text is preferred).

When possible, prefer using native HTML elements (<a>, <button>) over custom ARIA roles, as they come with built-in accessibility behaviors. If you must use ARIA roles, always make sure the accessible name is clear and describes the action or destination.

Examples

Incorrect: No accessible name

These elements will be flagged because screen readers cannot determine their purpose.

<!-- Empty element with no text or label -->

<div role="link"></div>

<!-- Empty aria-label provides no name -->

<div role="button" aria-label=""></div>

<!-- aria-labelledby points to a non-existent element -->

<div role="menuitem" aria-labelledby="nonexistent"></div>

<!-- aria-labelledby points to an empty element -->

<div role="link" aria-labelledby="empty-label"></div>
<div id="empty-label"></div>

Correct: Accessible name provided

Each of these elements has a discernible name that screen readers can announce.

<!-- Inner text content -->

<div role="link" tabindex="0">Visit our help center</div>

<!-- aria-label attribute -->

<div role="button" tabindex="0" aria-label="Close dialog"></div>

<!-- aria-labelledby pointing to visible text -->

<div role="menuitem" tabindex="0" aria-labelledby="menu-label">
  <span id="menu-label">Save document</span>
</div>

<!-- Combination of aria-label and inner text -->

<div role="link" tabindex="0" aria-label="Learn more about pricing">
  Learn more
</div>

<!-- title attribute as a fallback -->

<div role="button" tabindex="0" title="Submit form"></div>

Preferred: Use native HTML elements

Native elements handle naming and keyboard behavior automatically, reducing the chance of accessibility issues.

<a href="/help">Visit our help center</a>

<button type="button">Close dialog</button>

Note: When testing with RGAA, issues reported by this rule may need to be mapped to a different RGAA test, such as 6.2.1 for links.

The aria-hidden="true" attribute tells assistive technologies to ignore an element and all of its descendants. This is useful for hiding purely decorative content — such as icon fonts or redundant visuals — that would clutter the screen reader experience. However, a serious problem arises when focusable elements like links, buttons, form inputs, or elements with tabindex="0" exist inside an aria-hidden="true" container.

When this happens, keyboard users can still Tab to those elements, but screen readers won’t announce them. The user lands on what feels like an invisible, unlabeled control. They have no way to know what the element is or what it does. This affects blind users, deafblind users, users with low vision who rely on screen readers, and mobility-impaired users who navigate exclusively by keyboard.

It’s also important to understand that aria-hidden="false" on a descendant does not override aria-hidden="true" on an ancestor. Once a parent is hidden from the accessibility tree, all children remain hidden regardless of their own aria-hidden value. Any focusable children inside that subtree still create the same problem.

Related WCAG Success Criteria

This rule primarily relates to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that for all user interface components, the name and role can be programmatically determined, and states, properties, and values can be programmatically set. A focusable element inside an aria-hidden="true" container violates this because its name and role are stripped from the accessibility API while it remains reachable via keyboard — making it impossible for assistive technologies to convey its purpose. This rule is flagged across WCAG 2.0, 2.1, and 2.2 at Level A, as well as in Trusted Tester, EN 301 549, and RGAA guidelines.

How to Fix It

There are several strategies to resolve this issue:

1. Remove aria-hidden="true" from elements that contain focusable children, if those children need to be interactive.
2. Remove focusable elements from inside the aria-hidden="true" container if the entire section is truly meant to be hidden.
3. Make focusable elements unfocusable by adding tabindex="-1" to links, buttons, or other interactive elements inside the hidden container.
4. Use the disabled attribute on form controls (not aria-disabled, which does not actually prevent focus).
5. Hide elements with CSS using display: none or visibility: hidden, which removes them from both the accessibility tree and the focus order simultaneously.

If you need to hide content from assistive technologies, ensure equivalent meaning and functionality is still available through other accessible means.

Examples

Incorrect: Focusable link inside aria-hidden="true"

The link is removed from the accessibility tree but still receives keyboard focus.

<div aria-hidden="true">
  <a href="/home">Home</a>
</div>

Incorrect: Offscreen focusable link inside aria-hidden="true"

Moving a link offscreen does not remove it from the focus order.

<div aria-hidden="true">
  <a href="/" style="position:absolute; top:-999em">Link</a>
</div>

Incorrect: Using aria-disabled instead of disabled

The aria-disabled attribute does not actually prevent the input from receiving focus.

<div aria-hidden="true">
  <input aria-disabled="true" />
</div>

Incorrect: Element with tabindex="0" and aria-hidden="true"

Adding tabindex="0" makes a normally non-focusable element focusable, creating a conflict with aria-hidden="true".

<p tabindex="0" aria-hidden="true">Some descriptive text</p>

Incorrect: Trying to override aria-hidden on a descendant

Setting aria-hidden="false" on a child does not re-expose it when a parent has aria-hidden="true". The button remains hidden from assistive technologies but still receives focus.

<div aria-hidden="true">
  <div aria-hidden="false">
    <button>Submit</button>
  </div>
</div>

Incorrect: Focusable <summary> inside aria-hidden="true"

The <summary> element is natively focusable.

<details aria-hidden="true">
  <summary>More info</summary>
  <p>Additional details here.</p>
</details>

Correct: Non-focusable content inside aria-hidden="true"

A paragraph with no interactive elements is safe to hide.

<p aria-hidden="true">Decorative description text</p>

Correct: Focusable elements hidden with CSS display: none

Using display: none removes the link from both the focus order and the accessibility tree.

<div aria-hidden="true">
  <a href="/" style="display:none">Link</a>
</div>

Correct: Focusable elements made unfocusable with tabindex="-1"

Adding tabindex="-1" removes the button from the tab order.

<div aria-hidden="true">
  <button tabindex="-1">Close</button>
</div>

Correct: Form input properly disabled with the disabled attribute

The disabled attribute prevents the input from receiving focus entirely.

<input disabled aria-hidden="true" />

Correct: Removing aria-hidden and keeping elements interactive

If the content needs to be focusable, simply don’t hide it from assistive technologies.

<div>
  <a href="/home">Home</a>
</div>

When you use ARIA roles to create custom input controls instead of native HTML elements, the browser no longer automatically associates a label with the control. Native <input>, <select>, and <textarea> elements support the <label> element through implicit wrapping or explicit for/id pairing, but custom <div> or <span> elements with ARIA roles do not. This means you must supply an accessible name through ARIA-specific mechanisms.

This rule applies to elements with any of the following ARIA input roles:

• combobox
• listbox
• searchbox
• slider
• spinbutton
• textbox

Who is affected

Without an accessible name, users who rely on screen readers (including blind and deafblind users) hear only the role of the element — for example, “textbox” — with no indication of what information to enter. Users with mobility impairments who navigate via voice control also depend on accessible names to target specific controls by speaking their labels. This creates a serious barrier to interaction.

Related WCAG success criteria

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that all user interface components have a name that can be programmatically determined by assistive technologies. It is a Level A requirement, meaning it represents the minimum baseline of accessibility.

How to fix the problem

Because <label> elements do not work reliably with non-native elements like <div> or <span>, you need to use one of these approaches:

1. aria-label — Add a concise, descriptive label directly on the element.
2. aria-labelledby — Point to the id of one or more visible elements that serve as the label.
3. title — Use the title attribute as a last resort (it is less discoverable for sighted users).

Make sure the accessible name you provide is not empty or whitespace-only, and that any id referenced by aria-labelledby actually exists in the DOM.

Common mistakes

• Setting aria-label to an empty or whitespace-only string (e.g., aria-label=" ").
• Using aria-labelledby with an id that doesn’t exist on the page.
• Wrapping a custom ARIA widget in a <label> element, which does not provide a programmatic name for non-native elements in most browser/screen reader combinations.
• Using <label for="id"> to point to a <div> — the for attribute only works with native labelable elements like <input>, <select>, and <textarea>.

Examples

Incorrect: no accessible name on a combobox

The <div> has a combobox role but no label of any kind.

<div role="combobox">England</div>

Incorrect: aria-label is only whitespace

An empty or whitespace-only aria-label does not count as an accessible name.

<div aria-label=" " role="combobox">England</div>

Incorrect: aria-labelledby references a non-existent id

The referenced id must exist in the document; otherwise the accessible name resolves to empty.

<div role="listbox" aria-labelledby="color-label">
  <div role="option">Orange</div>
</div>
<!-- No element with id="color-label" exists -->

Incorrect: <label> wrapping a non-native element

Implicit label association does not work for <div> elements with ARIA roles.

<label>
  First name
  <div role="textbox"></div>
</label>

Incorrect: explicit <label for> targeting a non-native element

The for attribute only creates a programmatic association with native labelable elements.

<label for="name-field">First name</label>
<div role="textbox" id="name-field"></div>

Correct: aria-label on a combobox

<div role="combobox" aria-label="Country">England</div>

Correct: aria-labelledby pointing to a visible label

<p id="color-label">Select a color:</p>
<div role="listbox" aria-labelledby="color-label">
  <div role="option">Orange</div>
</div>

Correct: aria-labelledby on a searchbox

<p id="search-label">Search currency pairs:</p>
<div role="searchbox"
  contenteditable="true"
  aria-labelledby="search-label"></div>

Correct: aria-label on a slider

<div role="slider"
  aria-label="Choose a value"
  aria-valuemin="1"
  aria-valuemax="7"
  aria-valuenow="2"
  tabindex="0"></div>

Correct: aria-label on a spinbutton

<div role="spinbutton"
  aria-label="Enter quantity"
  aria-valuemin="0"
  aria-valuemax="10"
  aria-valuenow="8"
  tabindex="0"></div>

Correct: aria-labelledby on a textbox

<p id="name-label">First name</p>
<div role="textbox"
  contenteditable="true"
  aria-labelledby="name-label"></div>

When possible, prefer native HTML form controls (<input>, <select>, <textarea>) because they have built-in label support and keyboard behavior. Use custom ARIA input roles only when native elements cannot meet your design requirements, and always ensure those custom controls have an accessible name.

Toggle fields are interactive controls that let users select options, toggle settings, or make choices. When these controls are built using ARIA roles instead of native HTML elements, the browser does not automatically derive a name from a <label> element or inner content the way it would for a native <input type="checkbox">. You must explicitly provide an accessible name so assistive technologies can announce the control’s purpose.

Without an accessible name, a screen reader might announce something like “checkbox, unchecked” with no indication of what the checkbox represents. This makes the interface unusable for people who are blind, deafblind, or who rely on voice control software. Users with mobility impairments who use speech recognition tools also depend on accessible names to target and activate controls by voice.

This rule applies to elements with the following ARIA roles:

• checkbox
• menuitemcheckbox
• menuitemradio
• radio
• radiogroup
• switch

Related WCAG Success Criteria

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that for all user interface components, the name and role can be programmatically determined. Toggle fields that lack an accessible name violate this requirement because assistive technologies cannot convey the control’s purpose to the user.

How to Fix It

You can provide an accessible name for ARIA toggle fields using any of these techniques:

1. Inner text content — Place descriptive text inside the element. The browser uses this text as the accessible name.
2. aria-label — Add an aria-label attribute with a descriptive string directly on the element.
3. aria-labelledby — Reference the id of another element that contains the label text. Ensure the referenced element actually exists in the DOM.
4. title — Use the title attribute as a last resort. While it does provide an accessible name, it is less discoverable for sighted users and not consistently exposed by all assistive technologies.

Important: If you use aria-labelledby, make sure the referenced id matches an element that exists and contains meaningful text. Pointing to a non-existent id results in no accessible name.

Examples

Incorrect: Toggle fields without accessible names

<!-- checkbox with a broken aria-labelledby reference -->

<div role="checkbox" aria-checked="false" aria-labelledby="nonexistent-id"></div>

<!-- menuitemcheckbox with no name -->

<ul role="menu">
  <li role="menuitemcheckbox" aria-checked="true"></li>
</ul>

<!-- menuitemradio with no name -->

<ul role="menu">
  <li role="menuitemradio" aria-checked="false"></li>
</ul>

<!-- radio with no name -->

<div role="radiogroup">
  <div role="radio" aria-checked="false" tabindex="0"></div>
</div>

<!-- switch with no name and empty child spans -->

<div role="switch" aria-checked="true">
  <span></span>
  <span></span>
</div>

Each of these elements has no text content, no valid aria-label, no working aria-labelledby, and no title. A screen reader cannot announce what they represent.

Correct: Toggle fields with accessible names

<!-- checkbox: name from inner text content -->

<div role="checkbox" aria-checked="false" tabindex="0">
  Subscribe to newsletter
</div>

<!-- menuitemcheckbox: name from aria-label -->

<ul role="menu">
  <li role="menuitemcheckbox"
      aria-checked="true"
      aria-label="Word wrap">
  </li>
</ul>

<!-- menuitemradio: name from aria-labelledby -->

<p id="font-label">Sans-serif</p>
<ul role="menu">
  <li role="menuitemradio"
      aria-checked="true"
      aria-labelledby="font-label">
  </li>
</ul>

<!-- radio: name from title -->

<div role="radiogroup" aria-label="Crust type">
  <div role="radio"
       aria-checked="false"
       tabindex="0"
       title="Regular Crust">
  </div>
</div>

<!-- switch: name from aria-label -->

<div role="switch"
     aria-checked="true"
     aria-label="Dark mode"
     tabindex="0">
  <span>off</span>
  <span>on</span>
</div>

Preferred: Use native HTML elements when possible

Native HTML elements come with built-in accessible name mechanisms and keyboard behavior. Whenever possible, prefer them over custom ARIA toggle fields:

<!-- Native checkbox with a label -->

<label>
  <input type="checkbox"> Subscribe to newsletter
</label>

<!-- Native radio buttons with a fieldset -->

<fieldset>
  <legend>Crust type</legend>
  <label><input type="radio" name="crust" value="regular"> Regular Crust</label>
  <label><input type="radio" name="crust" value="thin"> Thin Crust</label>
</fieldset>

Using native elements reduces the risk of accessibility issues and eliminates the need to manually manage roles, states, and keyboard interactions.

The <blink> element was once used to draw attention to content by making it flash repeatedly. While it may have seemed like an eye-catching effect, it creates serious accessibility barriers for multiple groups of users. The element has been deprecated from the HTML specification, and although most modern browsers no longer render the blinking effect, the element should still be removed from your markup to ensure compliance and avoid issues in any environment that might still support it.

Why this is an accessibility problem

Blinking content affects several groups of users:

• Users with cognitive disabilities may find blinking text distracting or incomprehensible. The constant flashing can make it very difficult to focus on and understand the content.
• Users with low vision struggle to read text that appears and disappears rapidly. The intermittent visibility makes the content effectively unreadable.
• Users with motor disabilities may have difficulty clicking on blinking links or buttons, since the target is not consistently visible and requires precise timing to activate.
• Users with photosensitive conditions can experience discomfort or, in extreme cases, seizures from flashing content, depending on the frequency.

This rule relates to WCAG 2.2 Success Criterion 2.2.2: Pause, Stop, Hide (Level A), which requires that for any moving, blinking, or scrolling content that starts automatically and lasts more than five seconds, users must be able to pause, stop, or hide it. Since the <blink> element provides no mechanism for users to control the flashing, it fails this criterion outright.

This rule also applies to Section 508 §1194.22(j), which states that pages must be designed to avoid causing the screen to flicker with a frequency greater than 2 Hz and lower than 55 Hz.

How to fix it

1. Remove all <blink> elements from your HTML. Replace them with standard elements like <span>, <strong>, or <em>.
2. Remove text-decoration: blink; from your CSS, as this is the CSS equivalent of the <blink> element.
3. Use alternative emphasis techniques to make content stand out — bold text, color, larger font size, borders, background highlights, or icons.

Important: Many modern browsers silently ignore the <blink> element, so the text won’t visually blink even though the element is present in the source code. Don’t rely on how the page looks in the browser to determine whether <blink> tags exist. Always check the actual HTML source.

Examples

Incorrect: using the <blink> element

<p><blink>Moving Sale Thursday!</blink></p>

This causes the text to flash on and off (in browsers that support it), making it inaccessible.

Incorrect: using text-decoration: blink in CSS

<style>
  .attention {
    text-decoration: blink;
  }
</style>
<h2 class="attention">Limited Time Offer!</h2>

The CSS text-decoration: blink value achieves the same inaccessible effect as the <blink> element.

Correct: using static visual emphasis

<p><strong>Moving Sale Thursday!</strong></p>

Using <strong> makes the text bold and conveys emphasis to screen readers without any flashing.

Correct: using CSS for visual emphasis without blinking

<style>
  .highlight {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 8px 12px;
    font-weight: bold;
  }
</style>
<p class="highlight">Limited Time Offer!</p>

This draws attention to the content using color, a border, and bold text — all without any flashing or blinking, keeping the content readable and accessible for everyone.

When a button lacks an accessible name, assistive technologies like screen readers can only announce it generically — for example, as “button” — with no indication of its purpose. This is a critical barrier for people who are blind or deafblind, as they rely entirely on programmatically determined names to understand and interact with interface controls. A sighted user might infer a button’s purpose from an icon or visual context, but without a text-based name, that information is completely lost to assistive technology users.

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have a name that can be programmatically determined. It is also covered by Section 508, EN 301 549 (9.4.1.2), and Trusted Tester guidelines, which require that the purpose of every link and button be determinable from its accessible name, description, or context.

How to fix it

Ensure every <button> element or element with role="button" has an accessible name through one of these methods:

1. Visible text content inside the button element.
2. A non-empty aria-label attribute that describes the button’s purpose.
3. An aria-labelledby attribute that references an element containing visible, non-empty text.
4. A title attribute (use as a last resort, since title tooltips are inconsistently exposed across devices).

If a button is purely decorative and should be hidden from assistive technologies, you can assign role="presentation" or role="none" and remove it from the tab order with tabindex="-1". However, this is rare for interactive buttons.

Common mistakes to avoid

• Leaving a <button> element completely empty.
• Using only a value attribute on a <button> — unlike <input> elements, the value attribute on <button> does not provide an accessible name.
• Setting aria-label to an empty string (aria-label="").
• Pointing aria-labelledby to an element that doesn’t exist or contains no text.
• Using only an icon or image inside a button without providing alternative text.

Examples

Incorrect: empty button

<button id="search"></button>

A screen reader announces this as “button” with no indication of its purpose.

Incorrect: button with only a value attribute

<button id="submit" value="Submit"></button>

The value attribute does not set the accessible name for <button> elements.

Incorrect: empty aria-label

<button id="close" aria-label=""></button>

An empty aria-label results in no accessible name.

Incorrect: aria-labelledby pointing to a missing or empty element

<button id="save" aria-labelledby="save-label"></button>
<div id="save-label"></div>

The referenced element exists but contains no text, so the button has no accessible name.

Correct: button with visible text

<button>Submit order</button>

Correct: icon button with aria-label

<button aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-close"></use>
  </svg>
</button>

The aria-label provides the accessible name, while aria-hidden="true" on the SVG prevents duplicate announcements.

Correct: button labeled by another element

<h2 id="section-title">Shopping cart</h2>
<button aria-labelledby="section-title">
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-arrow"></use>
  </svg>
</button>

The button’s accessible name is drawn from the referenced heading text.

Correct: button with aria-label and visible text

<button aria-label="Search products">Search</button>

When both aria-label and inner text are present, aria-label takes precedence as the accessible name. Use this when you need a more descriptive name than what the visible text alone conveys.

Correct: button with title (last resort)

<button title="Print this page">
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-print"></use>
  </svg>
</button>

The title attribute provides an accessible name, but visible text or aria-label are preferred because title tooltips may not be available to touch-screen or keyboard-only users.

Websites typically repeat navigation links, branding, and other interface elements across every page. While sighted mouse users can visually scan past these blocks and click wherever they want, keyboard-only users and screen reader users must navigate through every interactive element sequentially. Without a bypass mechanism, a keyboard user might need to press Tab dozens of times just to reach the primary content on each new page they visit. For users with severe motor impairments, this can take several minutes per page and cause fatigue or physical pain. Even users with less severe limitations will experience frustrating delays compared to mouse users, who can reach any link in a second or two.

Screen reader users also benefit significantly from bypass mechanisms. Landmarks like <main>, <nav>, and <header> allow screen readers to present a structural outline of the page, enabling users to jump directly to the section they need. Headings serve a similar purpose — screen reader users can navigate by heading level to quickly locate the main content area.

This rule maps to WCAG 2.4.1 Bypass Blocks (Level A), which requires that a mechanism is available to bypass blocks of content repeated on multiple pages. It is also required by Section 508 (specifically §1194.22(o)), the Trusted Tester guidelines, and EN 301 549. Because it is a Level A requirement, it represents the minimum baseline for accessibility compliance.

How the Rule Works

The axe bypass rule checks that a page includes at least one of the following:

• A landmark region (such as <main>, <nav>, <header>, or <footer>)
• A heading (an <h1> through <h6> element)
• An internal skip link (an anchor link that points to a location further down the page)

If none of these are present, the rule flags the page as a failure.

How to Fix It

The best approach is to use HTML5 landmark elements to structure your page. At a minimum, include a <main> element that wraps the primary content of the page. You should also use <header>, <nav>, and <footer> to identify other common sections. A page should have only one <main> landmark.

Additionally, consider adding a skip navigation link as the very first focusable element on the page. This provides an immediate shortcut for keyboard users who don’t use screen readers and may not be able to navigate by landmarks.

Prefer native HTML5 elements over their ARIA equivalents. For example, use <main> rather than <div role="main">. Native elements are better supported and require less code.

Examples

Incorrect: No Landmarks, Headings, or Skip Links

This page has no structural landmarks, no headings, and no skip link. Keyboard users must tab through every element to reach the content.

<div class="header">
  <div class="logo">My Site</div>
  <div class="nav">
    <a href="/home">Home</a>
    <a href="/about">About</a>
    <a href="/contact">Contact</a>
  </div>
</div>
<div class="content">
  <p>This is the main content of the page.</p>
</div>
<div class="footer">
  <p>Footer information</p>
</div>

Correct: Using HTML5 Landmark Elements

Replacing generic <div> wrappers with semantic HTML5 elements gives the page proper structure that assistive technologies can use for navigation.

<header>
  <div class="logo">My Site</div>
  <nav>
    <a href="/home">Home</a>
    <a href="/about">About</a>
    <a href="/contact">Contact</a>
  </nav>
</header>
<main>
  <h1>Welcome</h1>
  <p>This is the main content of the page.</p>
  <section>
    <h2>Latest News</h2>
    <p>Section content here.</p>
  </section>
</main>
<footer>
  <p>Footer information</p>
</footer>

Correct: Adding a Skip Navigation Link

A skip link gives keyboard users an immediate way to bypass repeated content. It is typically visually hidden until it receives focus.

<body>
  <a class="skip-link" href="#main-content">Skip to main content</a>
  <header>
    <nav>
      <a href="/home">Home</a>
      <a href="/about">About</a>
      <a href="/contact">Contact</a>
    </nav>
  </header>
  <main id="main-content">
    <h1>Page Title</h1>
    <p>This is the main content of the page.</p>
  </main>
  <footer>
    <p>Footer information</p>
  </footer>
</body>

.skip-link {
  position: absolute;
  left: -9999px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
}

.skip-link:focus {
  position: static;
  width: auto;
  height: auto;
  overflow: visible;
}

When the skip link receives keyboard focus, it becomes visible, and pressing Enter moves focus directly to the <main> element. Combined with proper landmark elements, this gives all users fast, reliable access to the page’s primary content.

Color contrast is one of the most common accessibility barriers on the web. When text doesn’t stand out enough from its background, it becomes difficult or impossible to read for many users. People with low vision experience reduced contrast sensitivity, meaning everything appears roughly the same brightness, making it hard to distinguish outlines, edges, and details. Approximately 1 in 12 people cannot see the full spectrum of colors — about 8% of men and 0.4% of women in the United States have some form of color vision deficiency. Nearly three times as many people have low vision compared to total blindness. Without sufficient contrast, these users simply cannot read your content.

This rule maps to WCAG 2.1 Success Criterion 1.4.3: Contrast (Minimum), which is a Level AA requirement. It is also referenced in WCAG 2.0, WCAG 2.2, the Trusted Tester methodology, EN 301 549, and RGAA. The user impact is considered serious because insufficient contrast directly prevents users from perceiving text content.

How Contrast Ratios Work

Contrast ratio is calculated by comparing the relative luminance of two colors on a scale from 1:1 (no contrast, e.g., white on white) to 21:1 (maximum contrast, black on white). WCAG defines two thresholds:

• Normal text (below 18pt or below 14pt bold): minimum 4.5:1 contrast ratio
• Large text (at least 18pt / 24px, or at least 14pt bold / 19px): minimum 3:1 contrast ratio

“Large text” is defined this way because larger characters have wider strokes that are easier to read at lower contrast levels.

What This Rule Checks

The color-contrast rule in axe-core examines each text element on the page and compares the computed foreground text color against the computed background color. It accounts for background color transparency and opacity. Elements that are found to have a 1:1 contrast ratio are flagged as “incomplete” and require manual review.

This rule does not flag:

• Text elements with a background-image (these require manual testing)
• Text that is visually hidden by other overlapping elements
• Images of text
• Text inside disabled controls (including child elements of disabled buttons)

Some foreground scenarios are harder for automated tools to evaluate, including CSS gradients, pseudo-element backgrounds, backgrounds created with CSS borders, and elements repositioned off-screen with CSS.

How to Fix It

1. Identify the failing elements by running axe. Each violation will report the current contrast ratio and the colors involved.
2. Adjust the foreground color, background color, or both until the required ratio is met (4.5:1 for normal text, 3:1 for large text).
3. Use a contrast checker tool like the axe DevTools browser extension, the WebAIM Contrast Checker, or the built-in color contrast analyzer in browser developer tools to test color combinations before deploying.
4. Test with real content — sometimes dynamic content or themed components produce contrast issues that static checks miss.

Examples

Insufficient contrast (fails)

This light gray text on a white background has a contrast ratio of approximately 2.6:1, which fails the 4.5:1 requirement.

<p style="color: #aaaaaa; background-color: #ffffff;">
  This text is hard to read.
</p>

Sufficient contrast (passes)

Darkening the text color to #595959 against a white background achieves a contrast ratio of approximately 7:1, meeting the requirement.

<p style="color: #595959; background-color: #ffffff;">
  This text is easy to read.
</p>

Large text with lower contrast requirement (passes)

Large text (18pt or larger) only needs a 3:1 contrast ratio. This example uses #767676 on white, which has a ratio of approximately 4.5:1 — well above the 3:1 threshold for large text.

<h1 style="font-size: 24pt; color: #767676; background-color: #ffffff;">
  Large heading text
</h1>

Semi-transparent background (fails)

Transparency can reduce effective contrast. Here, the semi-transparent white background doesn’t provide enough contrast depending on what’s behind it.

<div style="background-color: #cccccc;">
  <p style="color: #777777; background-color: rgba(255, 255, 255, 0.3);">
    Text with a semi-transparent background.
  </p>
</div>

Semi-transparent background fixed (passes)

Increasing the background opacity or adjusting colors restores sufficient contrast.

<div style="background-color: #cccccc;">
  <p style="color: #333333; background-color: rgba(255, 255, 255, 0.85);">
    Text with a more opaque background.
  </p>
</div>

Using CSS classes (passes)

In practice, you’ll likely use CSS classes rather than inline styles. Ensure your design system tokens and theme colors meet contrast requirements.

<style>
  .card {
    background-color: #1a1a2e;
  }
  .card-text {
    color: #e0e0e0;
  }
</style>

<div class="card">
  <p class="card-text">
    Light text on a dark background with good contrast.
  </p>
</div>

The <title> element is the very first piece of information screen reader users hear when a page loads. It’s also what appears in browser tabs, bookmarks, and search engine results. When a page has no title — or has an empty or generic one like “Untitled” — screen reader users are forced to read through the page content to figure out its purpose. For users who navigate between multiple open tabs or use their browser history to find a previous page, missing or vague titles create serious barriers.

This rule relates to WCAG 2.4.2 Page Titled (Level A), which requires that web pages have titles describing their topic or purpose. Because this is a Level A criterion, it represents a minimum baseline for accessibility. The rule also aligns with Trusted Tester guideline 12.A and EN 301 549.

The users most affected by missing or poor page titles include:

• Screen reader users (blind and deafblind users), who rely on the title as the first orientation cue when a page loads
• Users with cognitive disabilities, who benefit from clear, descriptive titles to understand where they are
• Keyboard-only users and anyone navigating between multiple tabs, who use titles to distinguish pages

How to fix it

1. Add a <title> element inside the <head> of every HTML document.
2. Write meaningful text inside the <title> — it must not be empty or contain only whitespace.
3. Make each title unique across your site so users can distinguish between pages.
4. Put the most unique information first. If you include a site or brand name, place it at the end (e.g., “Contact Us – Acme Corp” rather than “Acme Corp – Contact Us”). This way, screen reader users hear the distinguishing content immediately instead of listening to the same brand name on every page.
5. Align the title with the page’s <h1> heading. They don’t need to be identical, but they should be closely related since both describe the page’s purpose.
6. Avoid placeholder text like “Untitled,” “Page 1,” or “New Document.”

Beyond accessibility, descriptive titles improve SEO since search engines use them to filter, rank, and display results.

Examples

Incorrect: missing <title> element

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
  </head>
  <body>
    <h1>Our Products</h1>
  </body>
</html>

This page has no <title> element at all. Screen reader users will hear no identifying information when the page loads.

Incorrect: empty <title> element

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title></title>
  </head>
  <body>
    <h1>Our Products</h1>
  </body>
</html>

A <title> element is present but contains no text, which is equivalent to having no title.

Incorrect: generic or placeholder title

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Untitled Document</title>
  </head>
  <body>
    <h1>Our Products</h1>
  </body>
</html>

While technically not empty, a placeholder title provides no useful information about the page’s content.

Correct: descriptive and unique title

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Our Products – Acme Corp</title>
  </head>
  <body>
    <h1>Our Products</h1>
  </body>
</html>

The title clearly describes the page content, places the unique information first, and includes the site name at the end for context. It also closely matches the <h1> heading on the page.

When a form field has more than one <label> element pointing to it (either via the for attribute or by nesting), assistive technologies have no reliable way to determine which label is the correct one. This inconsistency means that users who are blind, have low vision, or are deafblind may hear the wrong label, an incomplete label, or a confusing combination of labels when interacting with a form. Users with mobility impairments also benefit from properly associated labels, since a single clear <label> expands the clickable area of the associated input.

This rule relates to WCAG 2.0, 2.1, and 2.2 Success Criterion 3.3.2: Labels or Instructions (Level A), which requires that labels or instructions are provided when content requires user input. Multiple conflicting labels undermine this requirement because the user cannot reliably receive a single, clear label for the field.

How to Fix

Ensure that each form field has only one <label> element associated with it. You can associate a label with a field in one of two ways — but use only one label per field:

1. Explicit association — Use the for attribute on the <label> matching the id of the input.
2. Implicit association — Wrap the input inside the <label> element.

If you need to provide additional descriptive text beyond the label, use aria-describedby to point to supplementary instructions rather than adding a second <label>.

If you have a situation where one label must be visually hidden, hide the redundant label using CSS (display: none or visibility: hidden) so it is fully removed from the accessibility tree, and remove its for attribute. Using aria-hidden="true" alone on a <label> is not sufficient to prevent all screen readers from associating it with the field.

Examples

Incorrect: Two explicit labels for one input

Both <label> elements use for="username", causing unpredictable screen reader behavior.

<label for="username">Username</label>
<label for="username">Enter your username</label>
<input type="text" id="username" />

Incorrect: One explicit and one implicit label

The input is both wrapped in a <label> and referenced by another <label> via for.

<label for="email">Email</label>
<label>
  Email address:
  <input type="text" id="email" />
</label>

Incorrect: Nested labels

Labels should never be nested inside each other.

<label>
  Enter your comments:
  <label>
    Comments:
    <textarea id="comments"></textarea>
  </label>
</label>

Correct: Single explicit label

One <label> with a for attribute matching the input’s id.

<label for="username">Username</label>
<input type="text" id="username" />

Correct: Single implicit label

The input is wrapped inside a single <label>.

<label>
  Email address:
  <input type="text" id="email" />
</label>

Correct: Label with supplementary instructions using aria-describedby

When you need to provide extra guidance beyond the label, use aria-describedby instead of a second label.

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-hint" />
<p id="password-hint">Must be at least 8 characters with one number.</p>

Correct: Using the title attribute as a label

When a visible label is not appropriate (rare cases), the title attribute can serve as an accessible name.

<textarea id="search" title="Search terms"></textarea>

Correct: Select inside a single label

<label>
  Choose an option:
  <select id="options">
    <option selected>Option A</option>
    <option>Option B</option>
  </select>
</label>

When a <frame> or <iframe> has tabindex="-1", the browser removes it from the sequential keyboard navigation order. This means that any focusable elements inside the frame — such as links, buttons, form controls, or other interactive elements — become completely unreachable via the keyboard. If the frame also has scrollable content, keyboard users cannot scroll it either, since focus can never enter the frame to begin with.

This creates a serious barrier for people who rely on keyboards to navigate, including blind users who use screen readers and people with mobility disabilities who cannot use a mouse. Content trapped inside an inaccessible frame is effectively hidden from these users, even though it may be fully visible on screen.

Related WCAG Success Criteria

This rule maps to WCAG 2.1 Success Criterion 2.1.1: Keyboard (Level A), which requires that all functionality be operable through a keyboard interface without requiring specific timings for individual keystrokes. When focusable content is locked inside a frame with tabindex="-1", this criterion is violated because keyboard users cannot access or interact with that content.

This is a Level A requirement — the most fundamental level of accessibility — meaning it must be met for a page to be considered minimally accessible.

How to Fix It

1. Remove tabindex="-1" from any <frame> or <iframe> that contains focusable content. Without an explicit tabindex, the browser will handle focus naturally and allow keyboard users to tab into the frame.
2. Use tabindex="0" if you need to explicitly include the frame in the tab order.
3. Only use tabindex="-1" on frames that genuinely contain no focusable or interactive content. Even then, be cautious — if the frame’s content changes later to include interactive elements, the negative tabindex will silently create an accessibility barrier.

As a general best practice, avoid using tabindex="-1" on frames entirely. It’s easy for frame content to change over time, and a negative tabindex can turn into an accidental accessibility issue after a routine content update.

Examples

Incorrect: Frame with focusable content and tabindex="-1"

The button inside this iframe is unreachable by keyboard because tabindex="-1" prevents focus from entering the frame.

<iframe
  srcdoc="<button>Click me</button>"
  tabindex="-1"
  title="Interactive widget">
</iframe>

Correct: Frame with focusable content and no negative tabindex

Removing tabindex="-1" allows keyboard users to tab into the frame and reach the button.

<iframe
  srcdoc="<button>Click me</button>"
  title="Interactive widget">
</iframe>

Correct: Frame with focusable content and tabindex="0"

Using tabindex="0" explicitly places the frame in the natural tab order.

<iframe
  srcdoc="<button>Click me</button>"
  tabindex="0"
  title="Interactive widget">
</iframe>

Correct: Frame with no focusable content and tabindex="-1"

When a frame contains only static, non-interactive content (no links, buttons, or form controls), using tabindex="-1" is acceptable because there is nothing inside that requires keyboard access.

<iframe
  srcdoc="<p>Hello world</p>"
  tabindex="-1"
  title="Static content display">
</iframe>

Screen reader users rely on frame titles to understand what each embedded region of a page contains. Many screen readers offer a feature that lists all frames on a page by their titles, allowing users to jump directly to the one they need. When frames lack titles or share identical titles, this feature becomes useless — users are left guessing which frame is which, or the screen reader falls back to unhelpful information like “frame,” “javascript,” a filename, or a URL.

This issue primarily affects users who are blind, deafblind, or who navigate with assistive technologies. It relates to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have an accessible name that can be programmatically determined. When frames share a title, their accessible names fail to uniquely identify them, violating this criterion. The rule is also covered by Trusted Tester guideline 12.D, which requires that the combination of accessible name and description for each <iframe> describes its content, as well as EN 301 549 section 9.4.1.2.

How to Fix It

1. Add a title attribute to every <frame> and <iframe> element.
2. Make each title unique across the page. No two frames should share the same title.
3. Make each title descriptive. The title should clearly summarize the content or purpose of the frame. Avoid generic labels like “frame” or “untitled.”
4. Match the frame’s inner document <title> to the title attribute on the frame element when possible. Some screen readers replace the frame’s title attribute with the inner document’s <title> element, so keeping them consistent ensures a reliable experience.

Tips for Writing Good Frame Titles

• Keep titles brief but informative — describe what the frame contains, not just that it exists.
• Put the most distinctive information first. If you include a brand name, place it at the end so users don’t have to hear it repeatedly while scanning a list of frames.
• Replace placeholder titles like “untitled” or “page” with meaningful descriptions.
• If the framed content has a visible heading, consider aligning the frame title with that heading for consistency.

Examples

Incorrect: Frames with Duplicate Titles

In this example, two iframes share the same title, making it impossible for screen reader users to tell them apart.

<iframe src="/news.html" title="Company Updates"></iframe>
<iframe src="/events.html" title="Company Updates"></iframe>

Incorrect: Frame with an Empty Title

An empty title provides no useful information to assistive technology users.

<iframe src="/contact.html" title=""></iframe>

Incorrect: Frames with No Title

Without any title attribute, screen readers fall back to announcing unhelpful information like the URL or “frame.”

<iframe src="/navigation.html"></iframe>
<iframe src="/main-content.html"></iframe>

Correct: Frames with Unique, Descriptive Titles

Each frame has a distinct title that clearly describes its content.

<iframe src="/news.html" title="Latest Company News"></iframe>
<iframe src="/events.html" title="Upcoming Events Calendar"></iframe>

Correct: Frame Title Matching the Inner Document Title

For the best experience, align the title attribute with the <title> element in the framed document.

<!-- Parent page -->

<iframe src="/contact.html" title="Contact Form"></iframe>

<!-- contact.html -->

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Contact Form</title>
</head>
<body>
  <h1>Contact Us</h1>
  <form>
    <label for="email">Email</label>
    <input type="email" id="email" name="email">
    <button type="submit">Send</button>
  </form>
</body>
</html>

Correct: Hiding Decorative or Non-Content Frames

If a frame is purely decorative or contains no meaningful content for users (such as a tracking pixel), hide it from assistive technology entirely instead of giving it a misleading title.

<iframe src="/tracking-pixel.html" title="" aria-hidden="true" tabindex="-1"></iframe>

Note that this approach should only be used when the frame genuinely contains no content that any user would need to access.

Screen reader users can pull up a list of all frames on a page and navigate between them using their titles. When frames lack accessible names, users hear generic labels like “frame,” “JavaScript,” or a raw URL — none of which convey the purpose or content of the frame. This forces users to enter each frame just to figure out what it contains, which is time-consuming and frustrating.

This issue primarily affects users who are blind or deafblind and rely on assistive technology, but it also impacts users with mobility disabilities who navigate by frame lists or landmarks.

Relevant WCAG Success Criteria

This rule relates to WCAG 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have a name that can be programmatically determined. Frames are interactive containers that users navigate into and out of, so they must have an accessible name.

It is also explicitly required by Section 508 (§1194.22(i)), which states that frames shall be titled with text that facilitates frame identification and navigation.

How to Fix It

Give every <iframe> and <frame> element a clear, descriptive accessible name using one of these methods:

1. title attribute — The most common approach. Add a title that briefly describes the frame’s content.
2. aria-label attribute — Provides an accessible name directly on the element.
3. aria-labelledby attribute — References another element’s text as the accessible name.

Tips for Writing Good Frame Titles

• Be brief and descriptive. A title like “Product search results” is far more useful than “frame1” or “content.”
• Make each title unique. If you have multiple frames, each one should have a distinct title so users can tell them apart.
• Match the frame’s internal document title. Some screen readers replace the frame’s title attribute with the <title> element inside the framed document. For consistency, keep them the same or very similar.
• Avoid placeholder text. Titles like “untitled” or “iframe” provide no useful information.
• Put unique information first. If you include a brand name, place it after the descriptive content so users hear the most useful information immediately.

Examples

Incorrect: <iframe> Without an Accessible Name

The frame has no title, aria-label, or aria-labelledby, so screen readers cannot describe it.

<iframe src="https://example.com/video-player"></iframe>

Incorrect: Empty title Attribute

An empty title is the same as having no title at all.

<iframe src="https://example.com/video-player" title=""></iframe>

Correct: Using the title Attribute

<iframe src="https://example.com/video-player" title="Product demo video player"></iframe>

Correct: Using aria-label

<iframe src="https://example.com/map" aria-label="Store location map"></iframe>

Correct: Using aria-labelledby

<h2 id="chat-heading">Live Chat Support</h2>
<iframe src="https://example.com/chat" aria-labelledby="chat-heading"></iframe>

Correct: Multiple Frames With Unique Titles

When a page contains several frames, each one should have a distinct, descriptive title.

<iframe src="/navigation" title="Site navigation menu"></iframe>
<iframe src="/content" title="Main article content"></iframe>
<iframe src="/ads" title="Sponsored advertisements"></iframe>

Correct: Matching the Frame Title to the Document Title

For the best experience, align the title attribute on the <iframe> with the <title> element inside the framed document.

<!-- Parent page -->

<iframe src="contact-form.html" title="Contact us form"></iframe>

<!-- contact-form.html -->

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Contact us form</title>
</head>
<body>
  <h1>Contact Us</h1>
  <form>
    <label for="email">Email</label>
    <input type="email" id="email">
    <button type="submit">Send</button>
  </form>
</body>
</html>

Screen readers rely on distinct sound libraries for each language, with pronunciation rules, intonation patterns, and phonetics tailored to that specific language. When a user navigates to a page, the screen reader checks the lang attribute on the <html> element to determine which sound library to load. If no lang attribute is present, the screen reader falls back to whatever default language the user configured during setup. For someone who speaks multiple languages and browses websites in different languages, this creates a serious problem — the screen reader will attempt to read foreign-language content using the wrong pronunciation rules, producing garbled or incomprehensible speech.

This issue primarily affects blind and deafblind users who rely on screen readers, but it also impacts users with cognitive disabilities who may use text-to-speech tools. When text is read aloud with the wrong language rules, even simple words become unrecognizable, effectively making the content inaccessible.

Related WCAG Success Criteria

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 3.1.1: Language of Page at Level A — the most fundamental level of conformance. This criterion requires that the default human language of each web page can be programmatically determined. It is also referenced by the Trusted Tester guidelines (11.A), EN 301 549, and RGAA.

How to Fix It

Add a lang attribute with a valid language code to the opening <html> element. The value should represent the primary language of the page content.

You can use a simple two-letter language code (like en for English, fr for French, or de for German), or you can be more specific with a regional dialect code like en-US for American English or fr-CA for Canadian French. A full list of valid language subtags is available in the IANA Language Subtag Registry.

If sections of your page contain content in a different language than the primary one, use the lang attribute on those specific elements so screen readers can switch sound libraries mid-page.

For languages written right to left (such as Arabic or Hebrew), also include the dir attribute with a value of rtl to indicate the text direction.

Examples

Incorrect: Missing lang attribute

This will trigger the rule because the <html> element has no lang attribute:

<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: lang attribute with a valid language code

<html lang="en">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: Using a regional dialect code

<html lang="en-US">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

Correct: Handling inline language changes

When a portion of the page is in a different language, use the lang attribute on the containing element:

<html lang="en">
  <head>
    <title>My Website</title>
  </head>
  <body>
    <p>The French word for hello is <span lang="fr">bonjour</span>.</p>
  </body>
</html>

Correct: Right-to-left language with dir attribute

<html lang="ar" dir="rtl">
  <head>
    <title>موقعي</title>
  </head>
  <body>
    <h1>مرحبا</h1>
  </body>
</html>

Screen readers rely on language-specific sound libraries to pronounce text accurately. Each language has its own pronunciation rules, intonation patterns, and phonetic characteristics, so screen readers load the appropriate library based on the declared language of the document. When the <html> element has no lang attribute or contains an invalid value — such as a misspelling or a fabricated code — the screen reader cannot determine which library to use. It defaults to whatever language the user configured during setup, which means content written in French might be read aloud using English pronunciation rules. The result is speech that sounds like a confusing, unintelligible accent.

This issue primarily affects blind users and deafblind users who rely on screen readers, but it also impacts users with cognitive disabilities who may use text-to-speech tools to aid comprehension. When pronunciation is wrong, understanding drops dramatically.

Related WCAG Success Criteria

This rule maps to WCAG Success Criterion 3.1.1: Language of Page (Level A), which requires that the default human language of each web page can be programmatically determined. This is a Level A requirement — the most fundamental level of accessibility — meaning it must be satisfied for basic compliance under WCAG 2.0, 2.1, and 2.2. It is also required by the Trusted Tester methodology, EN 301 549, and RGAA.

How to Fix It

1. Add a lang attribute to the opening <html> element.
2. Set its value to a valid BCP 47 language tag that represents the primary language of the page.
3. Double-check the spelling of the language code. Common valid codes include "en" (English), "fr" (French), "es" (Spanish), "de" (German), "ja" (Japanese), and "ar" (Arabic).
4. You can optionally include a regional subtag, such as "en-US" for American English or "fr-CA" for Canadian French.
5. For XHTML documents served as XML, use xml:lang instead of or in addition to lang.

If the language changes within the document for specific passages, use the lang attribute on the appropriate element to indicate the switch. For right-to-left languages, also include the dir="rtl" attribute.

Examples

Incorrect: Missing lang attribute

<html>
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

Without a lang attribute, screen readers cannot determine the page language and will default to the user’s configured language, which may not match the content.

Incorrect: Invalid lang value

<html lang="english">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

The value "english" is not a valid BCP 47 language tag. The correct code for English is "en".

Correct: Valid lang attribute

<html lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <p>Welcome to my website.</p>
  </body>
</html>

Correct: Regional subtag

<html lang="fr-CA">
  <head>
    <title>Ma page</title>
  </head>
  <body>
    <p>Bienvenue sur mon site web.</p>
  </body>
</html>

Correct: Language change within the page

<html lang="en">
  <head>
    <title>Multilingual Page</title>
  </head>
  <body>
    <p>This paragraph is in English.</p>
    <p lang="es">Este párrafo está en español.</p>
  </body>
</html>

Correct: Right-to-left language

<html lang="ar" dir="rtl">
  <head>
    <title>صفحتي</title>
  </head>
  <body>
    <p>مرحبا بكم في موقعي.</p>
  </body>
</html>

The dir="rtl" attribute ensures the text direction is correctly rendered for right-to-left languages like Arabic and Hebrew.

Images are a fundamental part of web content, but they are inherently visual. Screen readers cannot interpret the pixels of an image — they rely entirely on a text alternative to describe the image’s content and purpose to the user. Without alternative text, a screen reader may read out the image’s file name (e.g., “IMG_20230415_093012.jpg”), which is meaningless and confusing. In the worst case, the image is silently skipped, and the user misses critical information.

This rule primarily affects people who are blind or deafblind, who depend on screen readers or braille displays to access content. Users with low vision who rely on text magnification or high-contrast modes can also benefit from well-written alternative text.

Why This Matters

This rule maps to WCAG 2.2 Success Criterion 1.1.1: Non-text Content (Level A), which requires that all non-text content presented to the user has a text alternative that serves an equivalent purpose. It is also required by Section 508 and EN 301 549. Because it is a Level A requirement, it represents the absolute minimum baseline for accessibility — failing it means your content is fundamentally inaccessible to many users.

How to Provide Alternative Text

There are three main techniques for giving an image accessible alternative text:

1. The alt attribute — the most common and preferred method for <img> elements.
2. The aria-label attribute — provides an accessible name directly on the element.
3. The aria-labelledby attribute — points to the id of another element that contains the descriptive text.

Writing Good Alt Text

When writing alternative text, consider these questions:

• Why is this image here? What role does it play in the content?
• What information does it convey? What would a sighted user take away from it?
• If you removed the image, what words would replace it to preserve the same meaning?

Keep alt text concise and descriptive. Avoid phrases like “image of” or “picture of” — screen readers already announce the element as an image. Don’t use the file name as alt text. Focus on the image’s purpose and meaning, not a pixel-by-pixel description.

Handling Decorative Images

Not every image carries meaning. Decorative images — such as visual separators, background flourishes, or images whose content is fully described in surrounding text — should be hidden from assistive technology. To do this, use an empty alt attribute: alt="".

Do not omit the alt attribute entirely. If alt is missing, screen readers will often fall back to reading the file name, which creates a worse experience than having no announcement at all. An empty alt="" explicitly tells the screen reader to skip the image.

You can also use role="presentation" or role="none" to mark an image as decorative, but an empty alt attribute is simpler and more widely supported.

Examples

Incorrect: Missing Alt Text

The alt attribute is completely absent. A screen reader may announce the file name instead.

<img src="team-photo.jpg">

Incorrect: Unhelpful Alt Text

The alt text contains the file name rather than a meaningful description.

<img src="chart-q3.png" alt="chart-q3.png">

Correct: Descriptive Alt Text Using the alt Attribute

<img src="team-photo.jpg" alt="The engineering team gathered around a whiteboard during a planning session">

Correct: Alt Text Using aria-label

<img src="revenue-chart.png" aria-label="Bar chart showing quarterly revenue increasing from $2M in Q1 to $3.5M in Q4">

Correct: Alt Text Using aria-labelledby

<p id="chart-desc">Bar chart showing quarterly revenue growth from Q1 to Q4 2024.</p>
<img src="revenue-chart.png" aria-labelledby="chart-desc">

Correct: Decorative Image with Empty Alt

This separator line serves no informational purpose and should be hidden from screen readers.

<img src="decorative-line.svg" alt="">

Correct: Decorative Image Using role="presentation"

<img src="decorative-swirl.png" role="presentation">

What This Rule Checks

This axe-core rule (image-alt) inspects every <img> element on the page and verifies that it has an accessible text alternative. Specifically, it checks that each <img> has at least one of the following:

• A non-empty alt attribute
• An aria-label attribute
• An aria-labelledby attribute that references a valid element
• An empty alt="" (or role="presentation" / role="none") to indicate the image is decorative

If none of these conditions are met, the rule flags the image as a critical accessibility violation.

Every interactive control on a page needs an accessible name so that assistive technologies can announce it to users. For <input> elements with type="button", type="submit", or type="reset", the accessible name typically comes from the value attribute. While <input type="submit"> and <input type="reset"> have default browser-provided labels (“Submit” and “Reset”), <input type="button"> has no default — it renders as an empty, unlabeled button if no name is provided.

This issue critically affects blind and deafblind users who rely on screen readers. When a screen reader encounters an input button without discernible text, it may announce something like “button” with no indication of what the button does. This makes it impossible to navigate forms, submit data, or perform actions confidently. Sighted users can often infer a button’s purpose from visual context, but screen reader users depend entirely on the programmatic accessible name.

Related WCAG Success Criteria

This rule maps to WCAG 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have a name that can be programmatically determined. It also relates to Section 508 requirements that every non-text element must have a text equivalent, and EN 301 549 Section 9.4.1.2.

How to Fix It

There are several ways to give an input button a discernible accessible name:

1. value attribute — The most straightforward approach. Set value to descriptive text that communicates the button’s purpose.
2. aria-label attribute — Provides an accessible name directly. Useful when you need the accessible name to differ from the visible text, or when value cannot be used.
3. aria-labelledby attribute — References another element’s id whose text content becomes the accessible name. The referenced element must exist and contain text.
4. title attribute — Acts as a fallback accessible name. However, title is less reliable because it is not consistently exposed by all assistive technologies and only appears as a tooltip on hover, making it inaccessible to keyboard and touch users. Prefer value or aria-label instead.

For <input type="submit"> and <input type="reset">, browsers provide default labels, so they pass without an explicit value. However, if you set value="" (an empty string), you override the default and create an empty accessible name, which fails.

Examples

Incorrect: Input button with no accessible name

<form action="/search">
  <input type="button" id="go" />
</form>

This button has no value, aria-label, aria-labelledby, or title. A screen reader will announce it as just “button” with no context.

Incorrect: Empty aria-label

<form action="/search">
  <input type="button" aria-label="" />
</form>

An empty aria-label does not provide a discernible name.

Incorrect: aria-labelledby referencing a nonexistent or empty element

<form action="/search">
  <input type="button" aria-labelledby="nonexistent" />
</form>

<form action="/search">
  <input type="button" aria-labelledby="empty-label" />
  <div id="empty-label"></div>
</form>

If the referenced element doesn’t exist or has no text content, the button has no accessible name.

Incorrect: Submit or reset with an empty value

<form action="/search">
  <input type="submit" value="" />
  <input type="reset" value="" />
</form>

Setting value to an empty string overrides the browser’s default label, leaving the button unnamed.

Correct: Using the value attribute

<form action="/search">
  <input type="button" value="Search" />
</form>

Correct: Using aria-label

<form action="/search">
  <input type="button" aria-label="Search" />
</form>

Correct: Using aria-labelledby

<form action="/search">
  <input type="button" aria-labelledby="btn-label" />
  <span id="btn-label">Search</span>
</form>

Correct: Submit and reset with default or explicit values

<form action="/search">
  <input type="submit" />
  <input type="reset" />
  <input type="submit" value="Send Form" />
  <input type="reset" value="Clear All Fields" />
</form>

The first two rely on the browser’s built-in default labels (“Submit” and “Reset”). The last two provide custom, more descriptive labels through the value attribute. Both approaches are valid, though explicit descriptive labels are generally preferred for clarity.

An <input type="image"> element renders an image that functions as a submit button. Unlike standard <input type="submit"> buttons that display their value attribute as visible text, image buttons rely entirely on their visual appearance to communicate purpose. This means assistive technologies have no way to determine the button’s function unless you explicitly provide alternative text.

This is a critical accessibility barrier for several groups of users. Blind and deafblind users who rely on screen readers will hear something generic like “button” or, worse, the image file name (e.g., “btn_submit_v2.png”), which provides no useful information. Users with low vision who use screen magnifiers in combination with screen readers are similarly affected. Without a clear accessible name, these users cannot confidently interact with forms.

This rule relates to two WCAG success criteria at Level A — the minimum conformance level:

• WCAG 1.1.1 (Non-text Content): All non-text content must have a text alternative that serves the equivalent purpose. An image button is non-text content, so it needs alternative text.
• WCAG 4.1.2 (Name, Role, Value): All user interface components must have a programmatically determinable name. Buttons must expose their name to assistive technologies.

This requirement is also mandated by Section 508, EN 301 549, and the Trusted Tester guidelines.

How to fix it

Provide a non-empty accessible name for every <input type="image"> element using one of these methods:

1. alt attribute (preferred): Add an alt attribute that describes the button’s action. This is the most straightforward and widely supported approach.
2. aria-label attribute: Set an aria-label with a concise description of the button’s action.
3. aria-labelledby attribute: Reference the id of another visible element that describes the button’s action.

Writing effective alternative text

The alternative text for an image button should describe the action the button performs, not the image itself. Ask yourself: “What happens when the user clicks this button?” The answer is your alternative text.

• ✅ “Submit”, “Search”, “Add to cart”, “Log in”
• ❌ “Green arrow icon”, “button.png”, “click here”

Avoid filler words like “image of” or “button” — assistive technologies already announce the element’s role as a button.

Important: Simply placing text next to the image button in the HTML is not sufficient. Screen readers need a programmatically associated label, not visually adjacent text. Nearby text cannot be reliably determined as the button’s label by assistive technologies.

Examples

Incorrect: missing alternative text

The image button has no alt, aria-label, or aria-labelledby attribute. A screen reader might announce this as “submit.png button” or just “button.”

<form action="/search">
  <label for="query">Search</label>
  <input type="text" id="query" name="q">
  <input type="image" src="search-icon.png">
</form>

Incorrect: empty alt attribute

An empty alt attribute tells assistive technologies to ignore the element, effectively hiding the button entirely.

<input type="image" src="search-icon.png" alt="">

Correct: using the alt attribute

<form action="/search">
  <label for="query">Search</label>
  <input type="text" id="query" name="q">
  <input type="image" src="search-icon.png" alt="Search">
</form>

Correct: using aria-label

<input type="image" src="submit-arrow.png" aria-label="Submit order">

Correct: using aria-labelledby

The aria-labelledby attribute points to the id of a visible element. Make sure the referenced element exists and is not hidden with display: none or aria-hidden="true".

<h2 id="checkout-heading">Complete your purchase</h2>
<form action="/checkout">
<!-- form fields -->

  <input type="image" src="checkout-btn.png" aria-labelledby="checkout-heading">
</form>

What the rule checks

This rule verifies that every <input type="image"> element has a discoverable accessible name. It fails if the element has no alt, aria-label, or aria-labelledby attribute, or if those attributes are empty or resolve to an empty string.

Every form element — such as text inputs, checkboxes, radio buttons, and select menus — must have a programmatically associated label so that assistive technologies can identify and announce the purpose of each field. Without these labels, screen reader users cannot determine what information is expected, and users with motor impairments lose the benefit of a larger clickable target area that a properly associated <label> provides.

Why This Matters

When a form element lacks a programmatic label, screen readers either announce it generically (e.g., “edit text” or “checkbox”) or skip meaningful context entirely. This leaves blind, low-vision, and deafblind users unable to understand what data a field expects or what option a checkbox represents. They must guess based on surrounding content, which is unreliable and error-prone.

Labels also benefit users with motor impairments. When a <label> element is properly associated with an input, clicking the label text activates or focuses the associated control. This creates a larger click target, which is especially helpful for people with limited dexterity.

Sighted users often rely on visual proximity to infer a field’s purpose, but assistive technologies need an explicit programmatic relationship between the label text and the form control to convey the same information.

Relevant Standards

This rule maps to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have an accessible name that can be programmatically determined. It applies across WCAG 2.0, 2.1, and 2.2, as well as Section 508 (§1194.22(n)), EN 301 549 (9.4.1.2), and Trusted Tester guidelines. The user impact is considered critical.

How to Fix It

There are several ways to associate a label with a form element. Use the approach that best fits your situation, listed here from most recommended to least recommended.

1. Explicit <label> with for and id (Recommended)

The most common and reliable method is to use a <label> element whose for attribute matches the id of the form control. This creates an unambiguous programmatic association.

2. Implicit <label> (Wrapping)

Wrap the form control inside a <label> element. The association is implied by the parent-child relationship.

3. aria-label

Use aria-label when the field’s purpose is conveyed visually through an icon or layout rather than visible text. This creates an invisible label that only screen readers announce.

4. aria-labelledby

Use aria-labelledby when the label text already exists elsewhere on the page, or when you need to combine multiple pieces of text into a single label. Reference one or more element id values.

5. placeholder (Not Recommended)

A placeholder attribute can technically provide an accessible name, but it disappears once the user begins typing, removing the visible label. This creates usability problems for everyone and is not a recommended approach.

General Tips

• Ensure all id values are unique on the page.
• Make label text descriptive and meaningful when read aloud in isolation.
• Remember that buttons (<button>, <input type="submit">, etc.) are self-labeling through their text content or value attribute and do not need a separate <label>.
• Hidden inputs (<input type="hidden">) do not need labels since they are not presented to users.

Examples

Incorrect: Input without a label

<div>First name:</div>
<input type="text" id="firstname">

The <div> text is visually near the input, but there is no programmatic relationship. A screen reader will announce only “edit text” with no context.

Correct: Explicit label with for and id

<label for="firstname">First name:</label>
<input type="text" id="firstname">

Correct: Implicit label by wrapping

<label>
  First name:
  <input type="text">
</label>

Correct: aria-label for visually implied fields

<input type="text" aria-label="Search">
<button type="submit">🔍</button>

Correct: aria-labelledby referencing existing text

<div id="temp-label">Temperature</div>
<div id="high-label">High:</div>
<div id="low-label">Low:</div>

<input type="text" aria-labelledby="temp-label high-label">
<input type="text" aria-labelledby="temp-label low-label">

The first input is announced as “Temperature High:” and the second as “Temperature Low:”, combining the referenced text in order.

Incorrect: Relying only on placeholder

<input type="text" placeholder="Enter your email">

While this technically provides an accessible name, the visible hint disappears when the user starts typing, making it difficult to verify the field’s purpose. Always prefer a persistent visible label.

Correct: Visible label with supplementary placeholder

<label for="email">Email address</label>
<input type="text" id="email" placeholder="name@example.com">

Incorrect: Checkbox without a label

<input type="checkbox" id="terms">
I agree to the terms and conditions

The text is adjacent but not associated with the checkbox.

Correct: Labeled checkbox

<input type="checkbox" id="terms">
<label for="terms">I agree to the terms and conditions</label>

Why This Matters

Many users cannot perceive color differences reliably. Approximately 8% of men and 0.4% of women have some form of color vision deficiency, and there are nearly three times more people with low vision than those who are totally blind. For these users, if a link within a paragraph is styled only with a different color — say, blue text in a block of black text — it can be completely invisible as a link.

People with low vision often experience reduced contrast sensitivity, meaning everything appears roughly the same brightness. Without a non-color cue like an underline or a sufficient luminance difference, these users cannot detect that certain text is interactive. This can cause them to miss important navigation, actions, or information entirely.

This rule relates to WCAG 2.0/2.1/2.2 Success Criterion 1.4.1: Use of Color (Level A), which requires that color is not used as the only visual means of conveying information, indicating an action, or distinguishing a visual element. Links embedded in text are one of the most common places where this requirement is violated.

How the Rule Works

The axe rule link-in-text-block checks links that appear inside blocks of text (such as paragraphs) and evaluates them in three steps:

1. Non-color distinction present → Pass. If the link has a visual style that doesn’t depend on color — such as an underline, a border, a background color, or a distinct font weight/style — the rule passes automatically.

2. No non-color distinction and contrast below 3:1 → Fail. If the link relies only on color and the contrast ratio between the link text color and the surrounding text color is less than 3:1, the rule fails.

3. No non-color distinction but contrast is 3:1 or higher → Needs Review. If the link relies only on color but meets the 3:1 contrast threshold, the rule flags it for manual testing. You must verify that the link receives a distinct visual style (such as an underline) on :focus and :hover states.

How to Fix It

The simplest and most reliable fix is to give links a non-color visual indicator. Here are your options, in order of recommendation:

• Underline the link — This is the most universally understood link indicator.
• Add a border — A border-bottom can work as an alternative to text-decoration.
• Use a distinct font style — Bold or italic can help, though underline is more conventional for links.
• Add a background or outline — A subtle background color difference can work if it’s clearly visible.

If you choose to rely on color contrast alone (3:1 minimum between link text and surrounding text), you must also ensure the link gains a distinct non-color style on :hover and :focus. This two-part requirement exists because static contrast alone may not be sufficient for all users, but a visual change on interaction confirms the element is interactive.

Examples

Incorrect: Link distinguished only by color with insufficient contrast

<style>
  p { color: #333333; }
  a { color: #555555; text-decoration: none; }
</style>

<p>
  Learn more about our
  <a href="/services">consulting services</a>
  and how we can help.
</p>

In this example, the link has no underline and the color contrast between #555555 and #333333 is well below 3:1. Users with low vision or color blindness cannot identify the link.

Correct: Link has an underline (recommended)

<style>
  p { color: #333333; }
  a { color: #0056b3; text-decoration: underline; }
</style>

<p>
  Learn more about our
  <a href="/services">consulting services</a>
  and how we can help.
</p>

The underline provides a clear non-color visual cue, making the link identifiable regardless of color perception.

Correct: Link uses a bottom border instead of underline

<style>
  p { color: #333333; }
  a {
    color: #0056b3;
    text-decoration: none;
    border-bottom: 2px solid #0056b3;
  }
</style>

<p>
  Read our
  <a href="/guide">accessibility guide</a>
  for detailed instructions.
</p>

Correct: Color-only link with sufficient contrast plus hover/focus styles

<style>
  p { color: #333333; }
  a {
    color: #0000ee;
    text-decoration: none;
  }
  a:hover,
  a:focus {
    text-decoration: underline;
  }
</style>

<p>
  Visit our
  <a href="/help">help center</a>
  for answers to common questions.
</p>

Here the contrast between #0000ee and #333333 exceeds 3:1, and the link gains an underline on hover and focus. This satisfies the requirement, though note that axe will still flag this for manual review since it cannot automatically verify the hover/focus styles in all cases.

Incorrect: Underline removed with no replacement

<style>
  a { color: #1a73e8; text-decoration: none; }
  p { color: #000000; }
</style>

<p>
  Check out our
  <a href="/blog">latest blog posts</a>
  for updates.
</p>

Even though the blue color may seem obvious to sighted users with full color vision, removing the underline without providing another non-color indicator makes this link invisible to users with color blindness or low contrast sensitivity.

Links are one of the most fundamental interactive elements on the web. When a link lacks an accessible name, screen reader users hear something like “link” with no further context, making it impossible to understand the link’s purpose or destination. This affects people who are blind, deafblind, or have low vision and rely on screen readers, as well as keyboard-only users who navigate through links sequentially.

A link’s accessible name can come from several sources: its visible text content, an aria-label attribute, an aria-labelledby reference, a title attribute, or the alt text of an image contained within it. If none of these provide a non-empty string, the link has no discernible text, and this rule will flag it.

Beyond just having text, links must also be programmatically focusable. Avoid relying on device-specific JavaScript events like onmouseover or mouseout(), which are inaccessible to keyboard users. Use device-independent alternatives like onfocus, onblur, focus(), and blur(). Additionally, don’t hide link text from assistive technologies using display: none, visibility: hidden, or aria-hidden="true" on the link or its text content.

It’s also important to use semantic <a> elements with a valid href attribute rather than simulating links with <span> or <div> elements and click handlers. Real links are focusable by default and convey the correct role to assistive technologies.

Related WCAG Success Criteria

This rule relates to two Level A success criteria that apply across WCAG 2.0, 2.1, and 2.2:

• WCAG 2.4.4 (Link Purpose in Context): Users must be able to determine the purpose of each link from the link text alone, or from the link text combined with its programmatically determined context.
• WCAG 4.1.2 (Name, Role, Value): All user interface components, including links, must have an accessible name and role that can be programmatically determined.

This rule is also required under Section 508, EN 301 549, and Trusted Tester guidelines.

How to Fix It

1. Add visible text content inside the <a> element.
2. For image links, provide meaningful alt text on the <img> element.
3. Use aria-label when you need to provide an accessible name that differs from or supplements the visible text.
4. Use aria-labelledby to reference another element’s text as the link’s accessible name.
5. Don’t hide link text from screen readers with aria-hidden="true" or CSS that removes elements from the accessibility tree.
6. Ensure links are focusable by using proper <a> elements with href attributes and avoiding mouse-only event handlers.

Examples

Empty link (incorrect)

A link with no text or accessible name:

<a href="/settings"></a>

A link that only contains an image with no alt text:

<a href="/home">
  <img src="logo.png" alt="">
</a>

A link with its text hidden from assistive technologies:

<a href="/profile">
  <span aria-hidden="true">Profile</span>
</a>

Link with visible text (correct)

<a href="/settings">Settings</a>

Image link with descriptive alt text (correct)

<a href="/home">
  <img src="logo.png" alt="Homepage">
</a>

Link with aria-label (correct)

This is useful when multiple links share the same visible text, such as repeated “Read more” links:

<h3>Accessibility Updates</h3>
<p>New WCAG 2.2 guidelines have been published.
  <a href="/wcag22" aria-label="Read more about WCAG 2.2 updates">Read more</a>
</p>

<h3>Screen Reader Tips</h3>
<p>Learn how to navigate tables with a screen reader.
  <a href="/sr-tips" aria-label="Read more about screen reader tips">Read more</a>
</p>

Link with aria-labelledby (correct)

<h3 id="report-title">Annual Report 2024</h3>
<a href="/report-2024.pdf" aria-labelledby="report-title">Download PDF</a>

Icon link with visually hidden text (correct)

For links that use icons without visible text, use a visually hidden <span> to provide an accessible name:

<a href="/search">
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-search"></use>
  </svg>
  <span class="visually-hidden">Search</span>
</a>

The visually-hidden class hides the text visually but keeps it available to screen readers:

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

The <marquee> element was never part of any official HTML standard and has been deprecated by all major browsers. It produces text that continuously scrolls across the screen, making it extremely difficult to read, interact with, or comprehend. Even though browsers may still render it, the element should never appear in modern web content.

Why This Is an Accessibility Problem

Scrolling marquee text creates barriers for several groups of users:

• Users with low vision may not be able to read text that is constantly in motion. The movement makes it nearly impossible to track and process the words.
• Users with cognitive disabilities or attention deficits can be distracted or overwhelmed by content that moves without their control. Automatic motion competes for attention and can make it difficult to focus on other parts of the page.
• Users with limited motor skills may be unable to accurately click on links or interactive elements embedded within scrolling content, since the targets are constantly shifting position.
• Screen reader users may encounter inconsistent or confusing output, since the <marquee> element is non-standard and assistive technologies are not required to support it.

This rule relates to WCAG 2.2 Success Criterion 2.2.2: Pause, Stop, Hide (Level A), which requires that for any moving, blinking, or scrolling content that starts automatically and lasts more than five seconds, there must be a mechanism for users to pause, stop, or hide it. The <marquee> element provides no such mechanism by default, making it a failure of this criterion. This is also documented as a known failure technique: F16: Failure of Success Criterion 2.2.2 due to including scrolling content where movement is not essential to the activity without also including a mechanism to pause and restart the content.

How to Fix It

The fix is straightforward: remove all <marquee> elements from your HTML, including empty ones. Then decide how to handle the content:

1. Display the content as static text. In most cases, this is the best approach. Simply place the text in a standard element like a <p> or <span>.
2. If motion is truly needed, use CSS animations instead, and provide a visible control (such as a pause button) that allows users to stop the animation. Ensure the animation also respects the prefers-reduced-motion media query.

Examples

Incorrect: Using the <marquee> Element

This code uses the deprecated <marquee> element to create scrolling text with links. Users cannot pause or stop the movement.

<marquee behavior="scroll" direction="left">
  Frisbeetarianism is the
  <a href="https://en.wikipedia.org/wiki/Belief">belief</a> that when you
  <a href="https://en.wikipedia.org/wiki/Death">die</a>, your
  <a href="https://en.wikipedia.org/wiki/Soul">soul</a> goes up on the
  <a href="https://en.wikipedia.org/wiki/Roof">roof</a> and gets stuck.
</marquee>

Correct: Static Text

The simplest and most accessible fix is to display the content as regular, non-moving text.

<p>
  Frisbeetarianism is the
  <a href="https://en.wikipedia.org/wiki/Belief">belief</a> that when you
  <a href="https://en.wikipedia.org/wiki/Death">die</a>, your
  <a href="https://en.wikipedia.org/wiki/Soul">soul</a> goes up on the
  <a href="https://en.wikipedia.org/wiki/Roof">roof</a> and gets stuck.
</p>

Correct: CSS Animation with Pause Control and Reduced Motion Support

If scrolling text is a design requirement, use CSS with a pause button and respect the user’s motion preferences.

<div class="scrolling-container">
  <p class="scrolling-text" id="ticker">
    Breaking news: Accessibility makes the web better for everyone.
  </p>
  <button type="button" onclick="document.getElementById('ticker').classList.toggle('paused')">
    Pause / Resume
  </button>
</div>

<style>
  .scrolling-text {
    animation: scroll-left 10s linear infinite;
  }
  .scrolling-text.paused {
    animation-play-state: paused;
  }
  @keyframes scroll-left {
    from { transform: translateX(100%); }
    to { transform: translateX(-100%); }
  }
  @media (prefers-reduced-motion: reduce) {
    .scrolling-text {
      animation: none;
    }
  }
</style>

This approach gives users control over the motion and automatically disables the animation for users who have indicated they prefer reduced motion in their operating system settings.

When a page includes a <meta http-equiv="refresh"> tag with a time value under 20 hours, the browser will automatically reload or redirect the page after that delay. This happens without any user interaction or consent, which creates significant barriers for people with disabilities.

Why This Is a Problem

Automatic page refreshes are disorienting for many users. When the page reloads, the browser moves focus back to the top of the document. A user who was partway through reading content or filling out a form loses their place entirely. This is especially harmful for:

• Screen reader users (blind and deafblind users): A screen reader announces content linearly from the top. An unexpected refresh forces the user to start over, losing context and progress.
• Users with mobility impairments: People who navigate slowly using switch devices, mouth sticks, or other assistive technology may not finish interacting with the page before it refreshes, causing them to lose their work.
• Users with cognitive disabilities: Unexpected changes to the page can be confusing and make it difficult to complete tasks.

This rule relates to WCAG 2.2 Success Criterion 2.2.1: Timing Adjustable (Level A), which requires that for each time limit set by the content, users can turn off, adjust, or extend that time limit. A <meta> refresh gives users no such control — the page simply reloads or redirects with no warning or option to prevent it.

How to Fix It

You have several options depending on your use case:

1. Remove the meta refresh entirely. If the refresh is unnecessary, simply delete the tag.
2. Set the delay to 20 hours or more. If a refresh is truly needed, a delay of 20 hours or greater passes the rule, as it’s unlikely to interrupt a user’s session.
3. Use a server-side redirect. If the goal is to redirect users to a new URL, configure a 301 or 302 redirect on the server instead.
4. Use JavaScript with user controls. If you need periodic content updates, use JavaScript and provide users with the ability to pause, extend, or disable the auto-refresh.

Examples

Failing: Auto-refresh after 30 seconds

This refreshes the page every 30 seconds with no way for the user to stop it.

<head>
  <meta http-equiv="refresh" content="30">
</head>

Failing: Delayed redirect after 10 seconds

This redirects the user to another page after 10 seconds, giving them no control over the timing.

<head>
  <meta http-equiv="refresh" content="10; url=https://example.com/new-page">
</head>

Passing: Meta refresh removed

The simplest fix is to remove the meta refresh tag entirely.

<head>
  <title>My Page</title>
</head>

Passing: Server-side redirect instead of client-side

For redirects, use a server-side response. For example, an HTTP 301 header:

HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page

Passing: JavaScript refresh with user control

If you need periodic updates, use JavaScript and give users a way to stop or adjust the refresh.

<head>
  <title>Live Dashboard</title>
</head>
<body>
  <button id="toggle-refresh">Pause Auto-Refresh</button>
  <script>
    let refreshInterval = setInterval(function () {
      location.reload();
    }, 300000); // 5 minutes

    document.getElementById("toggle-refresh").addEventListener("click", function () {
      if (refreshInterval) {
        clearInterval(refreshInterval);
        refreshInterval = null;
        this.textContent = "Resume Auto-Refresh";
      } else {
        refreshInterval = setInterval(function () {
          location.reload();
        }, 300000);
        this.textContent = "Pause Auto-Refresh";
      }
    });
  </script>
</body>

Passing: Delay set to 20 hours or more

If a refresh is absolutely necessary and no interactive alternative is feasible, setting the delay to at least 72,000 seconds (20 hours) will pass the rule.

<head>
  <meta http-equiv="refresh" content="72000">
</head>

HTML has a clear content model: interactive elements like <button>, <a>, <select>, and <input> are not allowed to contain other interactive or focusable elements. When you nest one interactive control inside another — for example, placing a link inside a button — browsers and assistive technologies handle the situation inconsistently and unpredictably.

Screen readers are especially affected. When a user tabs to a nested interactive element, the screen reader may produce an empty or silent tab stop. The inner control’s name, role, and state are not announced, meaning the user has no idea what the control does or that it even exists. This creates a serious barrier for blind users who rely on screen readers and keyboard-only users who navigate by tabbing through focusable elements.

This issue also affects users with mobility impairments who use switch devices or other assistive input methods that depend on an accurate understanding of the interactive elements on the page.

Related WCAG Success Criteria

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that for all user interface components, the name and role can be programmatically determined, and states, properties, and values that can be set by the user can be programmatically set. Nested interactive controls violate this because the inner control’s name and role become inaccessible to assistive technology.

How to Fix It

The fix is straightforward: do not place focusable or interactive elements inside other interactive elements. Here are common strategies:

1. Separate the controls. Place interactive elements side by side rather than nesting them.
2. Restructure the layout. If a design requires a clickable card with inner links or buttons, use CSS positioning or JavaScript event delegation rather than literal nesting.
3. Check elements with ARIA roles. A <div> with role="button" is treated as an interactive control. It must not contain links, buttons, inputs, or any other focusable elements.

Examples

Incorrect: Link Nested Inside a Button

The <a> element inside the <button> creates a nested interactive control that screen readers will not announce properly.

<button>
  Save
  <a href="/options">More options</a>
</button>

Incorrect: Link Nested Inside an Element with role="button"

Even though the outer element is a <div>, the role="button" makes it an interactive control. The nested <a> is inaccessible to screen readers.

<div role="button" tabindex="0">
  Search
  <a href="/settings">Settings</a>
</div>

Incorrect: Button Nested Inside a Link

Placing a <button> inside an <a> element is equally problematic.

<a href="/dashboard">
  Go to dashboard
  <button>Settings</button>
</a>

Correct: Separate Interactive Controls

Place each interactive element independently so both are fully announced and operable.

<button>Save</button>
<a href="/options">More options</a>

Correct: Clickable Card with Separate Controls

If you need a card-like pattern where the entire card is clickable but also contains separate actions, avoid literal nesting. Use a flat structure with CSS for layout.

<div class="card">
  <h3><a href="/article/1">Article Title</a></h3>
  <p>A short description of the article.</p>
  <button>Bookmark</button>
</div>

Correct: Single Button with No Nested Interactive Content

A simple, properly structured button with only non-interactive content inside it.

<button>
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-save"></use>
  </svg>
  Save
</button>

Note that in the example above, the <svg> element has focusable="false" to prevent it from being a tab stop in some browsers (notably older versions of Internet Explorer and Edge), and aria-hidden="true" because the button text already provides the accessible name.