How to fix common axe-core accessibility issues

Allie uses the open-source axe-core engine. Here is what the most frequent rule names mean and how to fix them, with small HTML examples you can adapt.

By Allie. Published and last reviewed October 16, 2026.

Each issue in an Allie report shows an axe-core rule name. The rule IDs below are from Deque's published axe 4.10 rule list. Treat the examples as starting points: a developer should adapt and test them in your own page.

image-alt: images need alternate text

Relates to WCAG 1.1.1. Describe the purpose of the image, not its file name. If the image is decoration only, use an empty alt so assistive technology skips it.

<!-- Before -->
<img src="team.jpg">

<!-- After: informative -->
<img src="team.jpg" alt="Our five-person team outside the shop">

<!-- After: decorative -->
<img src="divider.png" alt="">

color-contrast: text needs enough contrast

Relates to WCAG 1.4.3. Normal text needs a contrast ratio of at least 4.5:1, and large text at least 3:1. Darken the text or change the background. Use a contrast checker on your brand colours.

/* Before: light grey on white */
.note { color: #aaaaaa; background: #ffffff; }

/* After: darker grey on white */
.note { color: #595959; background: #ffffff; }

label: form fields need labels

Relates to WCAG 4.1.2 and 3.3.2. Connect a visible label to each field with for and id. A placeholder alone is not a reliable label.

<!-- Before -->
<input type="email" placeholder="Email">

<!-- After -->
<label for="email">Email address</label>
<input id="email" name="email" type="email" autocomplete="email">

link-name: links need discernible text

Relates to WCAG 2.4.4 and 4.1.2. A link with only an icon or an empty anchor has no name for a screen reader.

<!-- Before -->
<a href="/cart"><svg aria-hidden="true">…</svg></a>

<!-- After -->
<a href="/cart"><svg aria-hidden="true">…</svg><span class="visually-hidden">View cart</span></a>

button-name: buttons need discernible text

Relates to WCAG 4.1.2. An icon button needs a text name. Use visible text where you can, or aria-label.

<!-- Before -->
<button><svg aria-hidden="true">…</svg></button>

<!-- After -->
<button type="button" aria-label="Close dialog"><svg aria-hidden="true">…</svg></button>

html-has-lang and html-lang-valid: set the page language

Relates to WCAG 3.1.1. Screen readers use the language to pick a pronunciation.

<!-- Before -->
<html>

<!-- After -->
<html lang="en">

document-title: every page needs a title

Relates to WCAG 2.4.2. Use a short, unique title that describes the page.

<title>Volunteer sign-up | Riverside Food Bank</title>

select-name, input-button-name, frame-title

These are the same idea for other controls: a select needs a label, an input type="submit" or type="button" needs a value or accessible name, and an iframe needs a title that says what it contains.

<iframe src="https://www.youtube.com/embed/…" title="Video: how to apply for a grant"></iframe>

list and listitem: use list markup correctly

Relates to WCAG 1.3.1. A li must sit inside a ul or ol, and a list should only contain list items.

Best-practice rules you may also see

Some axe rules, such as heading-order, region, page-has-heading-one and landmark-one-main, are listed by Deque as best practices, not as failures of a specific WCAG success criterion. They still improve navigation for screen reader users, so they are worth fixing. Add a single main landmark, keep headings in a logical order and put page content inside landmarks.

After you fix

Re-scan the page to confirm the rule no longer fires, then test the page with a keyboard. Fixing every automated finding is not the same as being fully accessible. See what automated testing can and cannot catch.

Frequently asked questions

What does an axe-core rule name like image-alt mean?

It is the identifier of the automated check that failed. Deque publishes a list of axe rules with a description of each. In Allie, each issue shows the rule name and the element that failed.

Is a placeholder enough to label a field?

No. A placeholder disappears when someone types and is not a dependable label. Use a visible label connected to the field with for and id.

Why does axe report a rule that is a best practice?

Some rules reflect industry-accepted practice, not a specific WCAG success criterion. Deque tags those as best-practice. They are still useful to fix.

Sources

We checked these pages when writing this guide.

• List of axe 4.10 rules, Deque University
• WCAG 2.2, W3C Recommendation

More guides

• WCAG 2.2 checklist
• Accessibility for nonprofits
• Accessibility barriers for small businesses
• What automated testing can and cannot catch

This guide is general information, not legal advice, and Allie reports do not certify conformance with WCAG or any law.