Accessibility Guides for low vision
Learn how to identify and fix common accessibility issues flagged by Axe Core — so your pages are inclusive and usable for everyone. Also check our HTML Validation Guides.
A document’s accesskey attribute values must all be distinct. Or, to put it another way, accesskeys must not be used more than once to protect keyboard users from unpleasant surprises.
When a document’s accesskey attribute value is supplied, users can quickly activate or switch the focus to a particular element by hitting the designated key (often in tandem with the alt key). The page becomes less accessible as a result of duplicating the values for the accesskey attribute.
Make sure the value of each defined accesskey is distinct and does not interfere with any screen reader or default browser shortcut keys.
Users who must use alternative keyboards or input devices serving as keyboard emulators, users who have problems tracking a pointer, or users who are blind or have low eyesight and cannot employ eye-hand coordination-required devices like mice, cannot operate the content.
What this Accessibility Rule Checks
Makes certain that every element on the page with an accesskey attribute has a different value.
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:
- Inner text content — Place readable text inside the element.
-
aria-labelattribute — Add a non-emptyaria-labelwith a descriptive name. -
aria-labelledbyattribute — Point to theidof another element that contains visible, non-empty text. -
titleattribute — Use atitleattribute as a fallback (thougharia-labelor 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.
For screen reader users, Aria dialog items must include intelligible language that specifies the destination, purpose, function, or action in detail.
Elements with role="dialog" or role="alertdialog" that lack an accessible name cannot be understood by screen reader users.
What this Accessibility Rule Checks
Verifies that all objects with the role="dialog" or role="alertdialog" attribute have a clear, understandable name.
Elements with aria-hidden must not contain focusable elements.
Using the property aria-hidden="true" on an element removes the element and all of its child nodes from the accessibility API, rendering the element fully unavailable to screen readers and other assistive technology.
aria-hidden may be used with extreme discretion to hide visibly displayed content from assistive technologies if the act of hiding this content is meant to enhance the experience of assistive technology users by reducing redundant or superfluous content.
If aria-hidden is employed to hide material from screen readers, the same or equal meaning and functionality must be made available to assistive technologies.
Using aria-hidden="false" on content that is a descendant of an element that is hidden using aria-hidden="true" will not reveal that content to the accessibility API, nor will it be accessible to screen readers or other assistive technology.
The rule applies to any element whose aria-hidden attribute value is true.
By adding aria-hidden="true" to an element, authors assure that assistive technologies will disregard the element.
This can be used to hide aesthetic elements, such as icon typefaces, that are not intended to be read by assistive technologies.
A focusable element with aria-hidden="true" is disregarded as part of the reading order, but is still part of the focus order, making it unclear if it is visible or hidden.
What this Accessibility Rule Checks
For all user interface components, including form elements, links, and script-generated components, the name and role can be identified programmatically; user-specified states, properties, and values can be set programmatically; and user agents, including assistive technologies, are notified of changes.
The meter role in ARIA represents a scalar measurement within a known range — think of a gauge showing a value like CPU temperature, password strength, or storage capacity. When a screen reader encounters an element with role="meter", it announces the element as a meter, but without an accessible name, it cannot convey what is being measured. The user hears something like “meter” with no context, which is effectively meaningless.
This issue primarily affects users who are blind or have low vision and rely on screen readers, as well as users with mobility impairments who may navigate via assistive technologies. It relates to WCAG 2.0/2.1/2.2 Success Criterion 1.1.1: Non-text Content (Level A), which requires that all non-text content has a text alternative that serves an equivalent purpose. A meter without a name fails to provide this text alternative.
How to Fix
Ensure every element with role="meter" has a clear, descriptive accessible name using one of these methods:
-
aria-label— Add descriptive text directly to the element. -
aria-labelledby— Reference another visible element that contains the label text. The referenced element must exist and contain non-empty text. -
title— Use thetitleattribute as a fallback naming method (thougharia-labeloraria-labelledbyare generally preferred).
The name should clearly describe what the meter is measuring so users understand its purpose in context.
Examples
Incorrect: Meter with no accessible name
The following meter has no name at all. A screen reader will announce it as a meter but cannot tell the user what it measures.
<div role="meter" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75"></div>
Incorrect: Empty aria-label
An empty aria-label is equivalent to having no name.
<div role="meter" aria-label="" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75"></div>
Incorrect: aria-labelledby referencing a nonexistent or empty element
If the referenced element doesn’t exist or has no text content, the meter still lacks an accessible name.
<div role="meter" aria-labelledby="nonexistent" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75"></div>
<div role="meter" aria-labelledby="empty-label" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75"></div>
<div id="empty-label"></div>
Correct: Using aria-label
<div role="meter" aria-label="Disk usage" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75"></div>
Correct: Using aria-labelledby
<span id="meter-label">Battery level</span>
<div role="meter" aria-labelledby="meter-label" aria-valuemin="0" aria-valuemax="100" aria-valuenow="42"></div>
Correct: Using the title attribute
<div role="meter" title="Signal strength" aria-valuemin="0" aria-valuemax="5" aria-valuenow="3"></div>
Correct: Using the native <meter> element with a <label>
When possible, prefer the native HTML <meter> element, which has built-in semantics and can be associated with a <label>.
<label for="fuel">Fuel level</label>
<meter id="fuel" min="0" max="100" value="68">68%</meter>
For screen reader users, Aria progressbar items must include understandable language that specifies the destination, purpose, or action.
Users of screen readers are unable to determine the purpose of items with the role="progressbar" attribute that lack an accessible name.
What this Accessibility Rule Checks
Checks that all items with role="progressbar" have a distinguishable, accessible name.
Screen reader users are required to have access to understandable text within Aria tooltip elements. This text must define the destination, purpose, function, or action in a clear and concise manner.
Users of screen readers are unable to understand the function of elements that have the role of tooltip but do not have accessible names.
What this Accessibility Rule Checks
Performs a check on all elements that have the role tooltip to ensure that they have a name that can be understood and is accessible.
The destination, purpose, function, or action of an Aria treeitem element must be made clear in the element’s understandable text for screen reader users.
Users of screen readers are unable to determine the function of items with the role treeitem that lack an accessible name.
What this Accessibility Rule Checks
Ensures that all objects with the role treeitem have a clear, understandable name.
The list of 53 Input Purposes for User Interface Components are used as the basis for the programmatic definition of the purpose for each common input field that collects user data.
For screen readers to work properly, the autocomplete attribute values must be true and applied correctly.
Inaccessible content stems from missing autocomplete values in form fields. In the absence of the necessary autocomplete attribute values, screen readers will not read the identified autocomplete form fields.
When screen readers are unable to adequately notify users about the requirements for form field interaction, users cannot successfully navigate forms.
What this Accessibility Rule Checks
The purpose of each user-information-collecting input field can be established programmatically when:
- The input field fulfills a purpose specified in the Input Purposes for User Interface Components section, and
- The content is implemented using technologies that provide support for determining the desired meaning of form input data.
Ensure that the text spacing specified by style attributes is modifiable using custom stylesheets.
When lines of text are single-spaced, many people with cognitive difficulties have difficulty following them. Providing spacing between 1.5 and 2 makes it easier for them to begin a new line after finishing the previous one.
What this Accessibility Rule Checks
Text line spacing must be modifiable by custom stylesheets.
This rule demands the absence of any blink elements. Blinking items might be challenging to activate, and flashing writing can be challenging to read.
The blink tag causes information to blink, as the name implies. Although you might enjoy the appearance, blinking text and objects (such as links and buttons) might be challenging to read and operate, especially for people with poor hand-eye coordination or limited dexterity.
For those who have visual or cognitive impairments, reading blinking letters can be quite challenging. Text that blinks can be annoying, especially for people who have cognitive difficulties. Some people may find it challenging to understand. The blink element should never be used due to these reasons.
What this Accessibility Rule Checks
Verifies that the blink element is never utilized.
According to WCAG 2 AAA contrast ratio thresholds, all text elements must have sufficient contrast between foreground text and background colors.
Some people with impaired eyesight have little contrast, meaning there are few bright or dark areas. Everything seems approximately the same brightness, making it difficult to detect outlines, borders, edges, and particulars. Text whose luminance (brightness) is too similar to the background can be difficult to read.
Nearly three times as many individuals suffer from low vision than total blindness. About 8% of males and 0.4% of women in the United States cannot see the typical complete spectrum of colors. A person with impaired vision or color blindness cannot distinguish text against an insufficiently contrasted background.
In the background, both color transparency and opacity are taken into account.
Transparency and opacity of colors in the foreground are more challenging to detect and account for due to:
- Background and foreground colors are same.
- Gradient backgrounds in CSS
- Background colors for pseudo-elements in CSS.
- Background colors generated using CSS borders.
- Overlap by another piece in the foreground - this can present positioning challenges.
- Elements shifted out of the viewport using CSS.
What this Accessibility Rule Checks
Examines each text element to check that the contrast between the foreground text and background colors meets the WCAG 2 AAA contrast ratio requirements.
This rule does not report text elements that have a background-image, are concealed by other components, or are text images.
This check additionally looks for child elements of disabled buttons so that they can be ignored to prevent a false value.
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
- Identify the failing elements by running axe. Each violation will report the current contrast ratio and the colors involved.
- 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).
- 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.
- 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 screen orientation (such as portrait or landscape) of mobile applications should not be restricted to a single mode. Users should be able to shift the orientation of their device between portrait and landscape without losing readability. Additionally, upon opening a page, it should appear in the current orientation of the user.
Users of assistive technologies may not have access to orientation features on their devices or assistive technologies.
What this Accessibility Rule Checks
Unless a specific display orientation is important, content does not confine its view and functionality to a single display orientation, such as portrait or landscape.
The text in table header components should be visible. Make sure screen reader users can access the table header. It is preferable to mark up an element with a td if it is not a header.
Both sighted users and screen reader users should be able to comprehend the visible text that explains the purpose of the row or column in table header components.
What this Accessibility Rule Checks
Verifies that each table header element has a visible text.
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:
-
Explicit association — Use the
forattribute on the<label>matching theidof the input. -
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>
The visible label of interactive items labeled through their content must be included in their accessible name.
This rule applies to any element with the following attributes:
- a semantic role that is a widget that supports name from content,
- visible text, and
-
an
aria-labeloraria-labelledbyattribute.
button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, searchbox, switch, tab, and treeitem are widget roles that support name from content.
The whole visible text content of the target element either matches its accessible name or is contained within it.
Leading and trailing whitespace and case sensitivity differences should be disregarded.
Users using speech input can interact with a web page by saying the visible text labels of menus, links, and buttons.
Voice input users are confused when they utter a visible text label, but the speech command does not work since the accessible (programmatic) name of the component does not match the visible label. When a user interface component contains a visible text label — whether the label is actual text or a picture of text — that text must also appear in the component’s accessible (programmatic) name. When the visual label and accessible (programmatic) name for interactive components are synchronized, users using speech input can engage with those components successfully.
What this Accessibility Rule Checks
For any user interface element with a visible text label, the accessible name must match (or include) the label’s visible text.
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
idvalues 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 orvalueattribute 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:
-
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.
-
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.
-
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
:focusand:hoverstates.
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-bottomcan work as an alternative totext-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.
Elements of type <marquee> are prohibited because they are deprecated, add difficulty for users with limited dexterity, and distract users with cognitive or attention problems.
The marquee element produces difficult-to-read and-click-on scrolling text. Furthermore, it can be disturbing to viewers, particularly those with low eyesight, cognitive impairments, or concentration difficulties.
People with attention difficulties or cognitive impairments may be distracted by scrolling content. People with inadequate fine motor skills may not be able to precisely click on links inside scrolling content. Users with visual impairments may not be able to read the content of the scrolling text with sufficient clarity.
What this Accessibility Rule Checks
Prevents the use of the deprecated marquee element.
The user-scalable="no" parameter in the <meta name="viewport"> element must not be used since it prevents text scaling and zooming, which are necessary for individuals with impaired vision.
The option user-scalable="no" within the content attribute of the <meta name="viewport"> element prevents page zooming.
The maximum-scale setting restricts the user’s ability to zoom.
This is troublesome for individuals with low vision who rely on screen magnifiers to view web page content.
Users with partial or low vision frequently choose to increase their browser’s fonts to make web content easier to read. Everything visible in the browser window at a given time is the viewport focus. If the user maximizes the browser on a high-resolution display, the viewport’s focus area is expansive and may encompass the entire online page.
If the browser window is small, only a small portion of the web page is visible in the viewport focus region. The viewport focus of the browser has no effect on the programmatic focus. Users can scroll the web page up and down, but the focus does not follow the viewport. Developers are required by the Web Content Accessibility Guidelines to build pages to enable resizing up to 200%; nevertheless, it is considered best practice to demand a 5x zoom.
What this Accessibility Rule Checks
Ensures that the user-scalable="no" parameter is absent from the <meta name="viewport"> element, and that the maximum-scale parameter is greater than or equal to 500%
The user-scalable="no" parameter in the <meta name="viewport"> element must not be used since it prevents text scaling and zooming, which are necessary for individuals with impaired vision.
The option user-scalable="no" within the content attribute of the <meta name="viewport"> element prevents page zooming.
The maximum-scale setting restricts the user’s ability to zoom.
This is troublesome for individuals with low vision who rely on screen magnifiers to view web page content.
Users with partial or low vision frequently choose to increase their browser’s fonts to make web content easier to read. Everything visible in the browser window at a given time is the viewport focus. On a high-resolution display, maximizing the browser provides a big viewport focus area that may include the entire online page.
If the browser window is small, only a small portion of the web page will be seen in the viewport focus region. The viewport focus of the browser has no effect on the programmatic focus. Users can scroll the web page up and down, but the focus does not follow the viewport. Developers are required by the Web Content Accessibility Guidelines to create websites to accommodate resizing up to 200%.
Ensures that user-scalable="no" is not included in the <meta name="viewport"> element and that maximum-scale is not less than 2.
What this Accessibility Rule Checks
Ensures that user-scalable="no" is not included in the <meta name="viewport"> element and that maximum-scale is not less than 2.
To enable screen reader users to navigate the heading structure with keyboard shortcuts rather than wasting time listening to more of the website to understand its structure, make sure the page, or at least one of its frames, contains a h1 element that appears before the start of the main content.
Users of screen readers can utilize keyboard keys to move straight to the first h1, which should, in theory, let them access the web page’s main content. Screen reader users must listen to more of the website in order to understand its structure if there is no h1 or if it appears elsewhere other than at the start of the main material, wasting significant time.
Keep in mind that unlike a visual user, a blind user cannot just glance at a web page and comprehend its layout. Without reading the entire material, visual users can learn a lot about the website layout. Users who are blind do not have such option. Unless there is another convenient way to gain a “glimpse,” screen readers read sequentially, which requires listening to the entire web page. It turns out that one method to do that is to use headers. Keyboard shortcuts can be used by screen reader users to move around a document’s heading hierarchy.
What this Accessibility Rule Checks
This rule locates every element that matches the subsequent selector and confirms that there is at least one of them: h1:not([role]), [role="heading"][aria-level="1"]
Checks to make sure elements selected for removal from the accessibility tree are really deleted.
In some circumstances, an element having a semantic role of none or presentation does not resolve to none or presentation (respectively).
This prevents the element from being eliminated from the accessibility tree, as would be expected, and allows screen readers to interact with it.
You shouldn’t focus the element or give it any global ARIA attributes in order to keep the element out of the accessibility tree.
What this Accessibility Rule Checks
Checks every element with role=“none” or role=“presentation” to ensure they do not have a global ARIA attribute and are not focusable.
A label element with a programmatic association must be included for each select element.
To make forms accessible, they must have clear form labels. Even if a form element isn’t programmatically named, sighted users can usually tell what it’s for when they see checkboxes, radio buttons, input fields, etc. To identify form fields, screen reader users need clear form labels. All form elements should have labels to remove confusion and make the product more accessible.
Screen reader users are in the dark about the expected input data when form elements lack labels. Without a defined label connection (or redundant text acting as a label), screen readers cannot automatically determine information about input items.
What this Accessibility Rule Checks
ensures that each select element has a label that is associated with it programmatically.
Ready to validate your sites?
Start your free trial today.