HTML Guides

The aria-label attribute is not allowed on a label element that is associated with a form control through the for attribute.

A <label> element already provides an accessible name for the form control it's associated with. Adding aria-label to the <label> itself creates a conflict: the aria-label would attempt to override the label's own accessible name, but the label's visible text is what gets passed to the associated form control. This redundancy is not only unnecessary but explicitly prohibited by the HTML specification.

The <label> element's purpose is to be the accessible label for another element. If you want the form control to have an accessible name, simply put that text inside the <label> element as visible content. If you need to provide a different accessible name directly to the form control, place the aria-label on the input element instead.

Incorrect Example

<label for="input_email" id="label_input_email" aria-label="Email">

Email

</label>

<input type="email" id="input_email">

Correct Example

The simplest fix is to remove the aria-label from the <label>, since the label's text content already serves as the accessible name for the input:

<label for="input_email" id="label_input_email">

Email

</label>

<input type="email" id="input_email">

If you need the accessible name to differ from the visible label text, place aria-label on the input instead:

<label for="input_email" id="label_input_email">

Email

</label>

<input type="email" id="input_email" aria-label="Your email address">

A div element without an explicit role (or with role="generic") cannot have the aria-labelledby attribute because generic containers have no semantic meaning that benefits from a label.

The div element maps to the generic ARIA role by default. Generic elements are purely structural — they don't represent anything meaningful to assistive technologies. Labeling something that has no semantic purpose creates a confusing experience for screen reader users, since the label points to an element that doesn't convey a clear role.

The aria-labelledby attribute is designed for interactive or landmark elements — things like dialog, region, navigation, form, or group — where a label helps users understand the purpose of that section.

To fix this, you have two options: assign a meaningful ARIA role to the div, or use a more semantic HTML element that naturally supports labeling.

HTML Examples

❌ Invalid: aria-labelledby on a plain div

<h2 id="section-title">User Settings</h2>

<div aria-labelledby="section-title">

<p>Manage your account preferences here.</p>

</div>

✅ Fixed: Add a meaningful role to the div

<h2 id="section-title">User Settings</h2>

<div role="region" aria-labelledby="section-title">

<p>Manage your account preferences here.</p>

</div>

✅ Fixed: Use a semantic element instead

<h2 id="section-title">User Settings</h2>

<section aria-labelledby="section-title">

<p>Manage your account preferences here.</p>

</section>

Using a section element or adding role="region" tells assistive technologies that this is a distinct, meaningful area of the page — making the label useful and the markup valid.

A span element has an implicit ARIA role of generic, and the aria-labelledby attribute is not allowed on elements with that role.

The span element is a generic inline container with no semantic meaning. Its default ARIA role is generic, and the ARIA specification explicitly prohibits naming generic elements with aria-labelledby (or aria-label). This restriction exists because accessible names on generic containers create confusing experiences for assistive technology users — screen readers wouldn't know what kind of thing is being labeled.

To fix this, you have two main options:

1. Add a meaningful role to the span that supports aria-labelledby, such as role="group", role="region", or any other role that accepts a label.
2. Use a more semantic element that already has an appropriate role, like a section, nav, or div with an explicit role.

If the span doesn't truly need a label, simply remove the aria-labelledby attribute.

HTML Examples

❌ Invalid: aria-labelledby on a plain span

<span id="label">Settings</span>

<span aria-labelledby="label">

<input type="checkbox" id="opt1">

<label for="opt1">Enable notifications</label>

</span>

✅ Fix: Add an appropriate role

<span id="label">Settings</span>

<span role="group" aria-labelledby="label">

<input type="checkbox" id="opt1">

<label for="opt1">Enable notifications</label>

</span>

✅ Fix: Use a semantic element instead

<span id="label">Settings</span>

<fieldset aria-labelledby="label">

<input type="checkbox" id="opt1">

<label for="opt1">Enable notifications</label>

</fieldset>

The aria-labelledby attribute creates a relationship between an element and the text content that labels it. It works by pointing to the id of one or more elements whose text should be used as the accessible name. When the validator reports that aria-labelledby must point to an element in the same document, it means at least one of the id values you referenced doesn't correspond to any element on the page.

This typically happens for a few reasons:

• Typo in the id — the aria-labelledby value doesn't exactly match the target element's id (remember, IDs are case-sensitive).
• The referenced element was removed — the labeling element existed at some point but was deleted or moved, and the reference wasn't updated.
• The id exists in a different document — aria-labelledby cannot reference elements across pages, iframes, or shadow DOM boundaries. The target must be in the same document.
• Dynamic content not yet rendered — the element is inserted by JavaScript after the validator parses the static HTML.

This is primarily an accessibility problem. Screen readers and other assistive technologies rely on aria-labelledby to announce meaningful labels to users. When the reference is broken, the element effectively has no accessible name, which can make it impossible for users to understand its purpose. Browsers won't throw a visible error, so the issue can go unnoticed without validation or accessibility testing.

To fix the issue, verify that every id referenced in aria-labelledby exists in the same HTML document. Double-check spelling and casing. If you reference multiple IDs (space-separated), each one must resolve to an existing element.

Examples

Incorrect — referencing a non-existent id

The aria-labelledby attribute points to "dialog-title", but no element with that id exists:

<div role="dialog" aria-labelledby="dialog-title">

<h2 id="dlg-title">Confirm deletion</h2>

<p>Are you sure you want to delete this item?</p>

</div>

Correct — matching id values

Ensure the id in the referenced element matches exactly:

<div role="dialog" aria-labelledby="dialog-title">

<h2 id="dialog-title">Confirm deletion</h2>

<p>Are you sure you want to delete this item?</p>

</div>

Incorrect — referencing multiple IDs where one is missing

When using multiple IDs, every one must be present. Here, "note-desc" doesn't exist:

<section aria-labelledby="note-heading note-desc">

<h3 id="note-heading">Important note</h3>

<p id="note-description">Please read carefully before proceeding.</p>

</section>

Correct — all referenced IDs exist

<section aria-labelledby="note-heading note-description">

<h3 id="note-heading">Important note</h3>

<p id="note-description">Please read carefully before proceeding.</p>

</section>

Incorrect — case mismatch

IDs are case-sensitive. "Main-Title" and "main-title" are not the same:

<nav aria-labelledby="Main-Title">

<h2 id="main-title">Site navigation</h2>

<ul>

<li><a href="/">Home</a></li>

</ul>

</nav>

Correct — consistent casing

<nav aria-labelledby="main-title">

<h2 id="main-title">Site navigation</h2>

<ul>

<li><a href="/">Home</a></li>

</ul>

</nav>

If you don't have a visible labeling element on the page and don't want to add one, consider using aria-label instead, which accepts a string value directly rather than referencing another element:

<nav aria-label="Site navigation">

<ul>

<li><a href="/">Home</a></li>

</ul>

</nav>

The aria-owns attribute is used to define parent-child relationships in the accessibility tree that aren't reflected in the DOM structure. For example, if a menu visually "owns" items that are placed elsewhere in the markup (perhaps for layout reasons), aria-owns tells assistive technologies that those elements should be treated as children of the owning element. The attribute accepts a space-separated list of one or more IDs.

According to the WAI-ARIA specification, each ID referenced by aria-owns must correspond to an element in the same document. If no matching element is found, the relationship is broken and the accessibility tree becomes inaccurate. This can confuse screen readers and other assistive technologies, potentially making parts of your page inaccessible or misrepresented to users who rely on them.

Common causes of this error:

• Typos in the ID value — a small misspelling like aria-owns="drpdown-menu" instead of aria-owns="dropdown-menu".
• Referencing an element that doesn't exist — the target element was removed or never added to the page.
• Referencing an element in a different document — the target lives inside an <iframe> or a shadow DOM, which are separate document contexts.
• Dynamic content timing — the referenced element is added to the DOM by JavaScript after validation or after the aria-owns relationship is evaluated.

How to fix it:

1. Check that every ID in the aria-owns value exactly matches an id attribute on an element in the same document.
2. Look for typos or case mismatches — IDs are case-sensitive.
3. If the target element is inside an <iframe>, restructure your markup so both elements are in the same document, or use a different ARIA approach.
4. If the element is added dynamically, ensure it exists in the DOM before the aria-owns relationship is needed by assistive technologies.

Examples

Incorrect — referencing a nonexistent ID

The element with id="dropdown-items" does not exist anywhere in the document, so the aria-owns reference is broken.

<button aria-owns="dropdown-items">Open Menu</button>

<!-- No element with id="dropdown-items" exists -->

Incorrect — typo in the referenced ID

The button references "menu-lst" but the actual element has id="menu-list".

<button aria-owns="menu-lst">Options</button>

<ul id="menu-list">

<li>Option A</li>

<li>Option B</li>

</ul>

Correct — referenced ID exists in the same document

The aria-owns value matches the id of an element present in the same page.

<button aria-owns="menu-list">Options</button>

<ul id="menu-list">

<li>Option A</li>

<li>Option B</li>

</ul>

Correct — multiple IDs referenced

When aria-owns lists multiple IDs, each one must have a corresponding element in the document.

<div role="tree" aria-owns="branch1 branch2 branch3">

File Explorer

</div>

<div role="treeitem" id="branch1">Documents</div>

<div role="treeitem" id="branch2">Pictures</div>

<div role="treeitem" id="branch3">Music</div>

Complete valid example

<!DOCTYPE html>

<html lang="en">

<head>

<title>aria-owns Example</title>

</head>

<body>

<div role="combobox" aria-expanded="true" aria-owns="suggestions">

<input type="text" aria-autocomplete="list">

</div>

<ul id="suggestions" role="listbox">

<li role="option">Apple</li>

<li role="option">Banana</li>

<li role="option">Cherry</li>

</ul>

</body>

</html>

In this example, the combobox uses aria-owns to claim the suggestions listbox as its child in the accessibility tree, even though the <ul> is a sibling in the DOM. Because the id="suggestions" element exists in the same document, the reference is valid and assistive technologies can correctly associate the two.

Every HTML semantic element carries an implicit ARIA role that assistive technologies already recognize. The <article> element has a built-in role of article, which signals that the content represents a self-contained composition — such as a blog post, news story, forum comment, or any section that could be independently distributed or reused. When you explicitly add role="article" to an <article> element, you're telling the browser and screen readers something they already know.

While this redundancy won't break anything functionally, it creates unnecessary noise in your markup and goes against the W3C's guidance on using ARIA. The first rule of ARIA use states: "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so." Redundant roles make code harder to maintain and can signal to other developers that something non-standard is happening when it isn't.

The role="article" attribute is useful when applied to non-semantic elements like <div> or <span> that need to convey article semantics — for instance, in legacy codebases where changing the element isn't feasible. But on the <article> element itself, it should simply be removed.

Examples

❌ Redundant role on <article>

This triggers the validator warning because role="article" duplicates the element's implicit role:

<article role="article">

<h2>Breaking News</h2>

<p>A rare bird was spotted in the city park this morning.</p>

</article>

✅ Fixed: no explicit role needed

Simply remove the role attribute. The <article> element already communicates the article role to assistive technologies:

<article>

<h2>Breaking News</h2>

<p>A rare bird was spotted in the city park this morning.</p>

</article>

✅ Appropriate use of role="article" on a non-semantic element

If you cannot use the <article> element for some reason, applying the role to a generic element like <div> is valid and useful:

<div role="article">

<h2>Breaking News</h2>

<p>A rare bird was spotted in the city park this morning.</p>

</div>

✅ Multiple articles within a feed

A common pattern is nesting several <article> elements inside a feed. No explicit roles are needed on the articles themselves:

<section role="feed" aria-label="Latest posts">

<article>

<h2>First Post</h2>

<p>Content of the first post.</p>

</article>

<article>

<h2>Second Post</h2>

<p>Content of the second post.</p>

</article>

</section>

This same principle applies to other semantic elements with implicit roles — for example, <nav> already has role="navigation", <main> has role="main", and <header> has role="banner". Avoid adding redundant roles to any of these elements to keep your HTML clean and standards-compliant.

The HTML specification defines built-in semantic roles for many elements, and the <header> element is one of them. When a <header> is a direct child of <body> (or at least not nested inside a sectioning element), browsers and assistive technologies already interpret it as a banner landmark — the region of the page that typically contains the site logo, navigation, and other introductory content. Explicitly adding role="banner" duplicates what the browser already knows, which adds unnecessary noise to your markup.

This principle is part of the WAI-ARIA specification's guidance on using ARIA roles: the first rule of ARIA is "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state, or property to make it accessible, then do so." Redundant roles don't typically break anything, but they clutter the code, can confuse developers maintaining the project, and signal a misunderstanding of HTML semantics.

It's worth noting an important nuance: the <header> element only maps to the banner role when it is not a descendant of <article>, <aside>, <main>, <nav>, or <section>. When nested inside one of these sectioning elements, <header> has no corresponding landmark role — it simply serves as the header for that particular section. In that context, adding role="banner" would not be redundant; it would actually change the semantics, which is almost certainly not what you want.

To fix the warning, remove the role="banner" attribute from your <header> element. The native semantics are sufficient.

Examples

Incorrect: redundant role="banner" on <header>

This triggers the validator warning because <header> already implies the banner role at the top level:

<header role="banner">

<img src="logo.svg" alt="My Company">

<nav>

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

<a href="/about">About</a>

</nav>

</header>

Correct: let <header> use its implicit role

Simply remove the role="banner" attribute:

<header>

<img src="logo.svg" alt="My Company">

<nav>

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

<a href="/about">About</a>

</nav>

</header>

Correct: using role="banner" on a non-<header> element

If for some reason you cannot use a <header> element (e.g., working within a legacy CMS), applying role="banner" to a <div> is the appropriate way to convey the same landmark semantics:

<div role="banner">

<img src="logo.svg" alt="My Company">

<nav>

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

<a href="/about">About</a>

</nav>

</div>

A <header> inside a sectioning element has no banner role

When <header> is nested inside an <article> or other sectioning element, it does not carry the banner role. This is expected and correct — the <header> here simply introduces the article content:

<article>

<header>

<h2>Article Title</h2>

<p>Published on <time datetime="2024-01-15">January 15, 2024</time></p>

</header>

<p>Article content goes here.</p>

</article>

The <base> element must appear before any <link> or <script> elements in the <head> section of the document.

The <base> element sets the base URL and/or default target for all relative URLs in a page. Because <link> and <script> elements often reference external resources using relative URLs, the browser needs to know the base URL before it encounters those elements. If <base> appears after a <link> or <script>, the browser may have already resolved their URLs without the intended base, leading to broken references or unexpected behavior.

Only one <base> element is allowed per document, and the HTML specification requires it to appear before any elements that have attributes accepting URLs. In practice, placing it as the first child of <head> (after <meta charset>) is the simplest way to satisfy this rule.

Invalid example

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="utf-8">

<title>Example</title>

<link rel="stylesheet" href="styles/main.css">

<script src="js/app.js"></script>

<base href="https://example.com/">

</head>

<body>

<p>Hello</p>

</body>

</html>

The <base> element comes after the <link> and <script> elements, which triggers the validation error.

Valid example

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="utf-8">

<base href="https://example.com/">

<title>Example</title>

<link rel="stylesheet" href="styles/main.css">

<script src="js/app.js"></script>

</head>

<body>

<p>Hello</p>

</body>

</html>

Moving <base> before the <link> and <script> elements fixes the error and ensures all relative URLs resolve correctly.

The <big> element was a purely presentational HTML element that increased the text size by one level (similar to moving from small to medium, or medium to large). HTML5 removed it from the specification because it violates the principle of separating content structure from visual presentation. HTML should describe the meaning of content, while CSS should handle how it looks.

Using obsolete elements causes several problems. First, W3C validation will fail, which can impact code quality standards and SEO audits. Second, while current browsers still support <big> for backward compatibility, there's no guarantee future browsers will continue to do so. Third, the <big> element carries no semantic meaning — it doesn't tell assistive technologies why the text is larger, only that it should be displayed differently. CSS gives you more precise control over font sizing while keeping your HTML clean and standards-compliant.

To fix this issue, replace every <big> element with a <span> (or another semantically appropriate element) and apply CSS to control the font size. You can use inline styles, a <style> block, or an external stylesheet.

If the larger text has a specific meaning — such as emphasizing importance — consider using a semantic element like <strong> or <em> instead, and style it with CSS as needed.

Examples

❌ Obsolete: using the <big> element

<p>This is <big>important text</big> in a paragraph.</p>

✅ Fixed: using a <span> with inline CSS

This is a direct replacement that mimics the original behavior of <big>, which rendered text at font-size: larger:

<p>This is <span style="font-size: larger;">important text</span> in a paragraph.</p>

✅ Fixed: using a CSS class

For better maintainability, use a class instead of inline styles:

<style>

.text-big {

font-size: larger;

}

</style>

<p>This is <span class="text-big">important text</span> in a paragraph.</p>

✅ Fixed: using a semantic element with CSS

If the text is larger because it's important or emphasized, use a semantic element and style it:

<style>

.highlight {

font-size: 1.25em;

}

</style>

<p>This is <strong class="highlight">important text</strong> in a paragraph.</p>

Choosing a font-size value

The <big> element historically corresponded to font-size: larger, but with CSS you have full flexibility:

• font-size: larger — relative increase, closest to original <big> behavior
• font-size: 1.2em — scales to 120% of the parent's font size
• font-size: 1.25rem — scales relative to the root font size
• font-size: 20px — absolute pixel value (less flexible, generally avoid)

Using relative units like em, rem, or the larger keyword is preferred because they scale well across different screen sizes and respect user font-size preferences.

In earlier versions of HTML, the border attribute on <img> was commonly used to control the border width in pixels. Its most frequent use was border="0" to suppress the default blue border browsers would render around images wrapped in <a> links. While this worked, it mixed presentation with markup — something HTML5 discourages in favor of a clean separation between structure (HTML) and styling (CSS).

The W3C HTML Validator flags this attribute as obsolete because it was removed from the HTML5 specification. Modern browsers still understand it for backward compatibility, but relying on deprecated features is bad practice. It can lead to inconsistencies across browsers, makes your code harder to maintain, and signals to validators and other developers that the markup is outdated.

The recommended approach is to handle image borders entirely in CSS. If you previously used border="0" to remove borders from linked images, most modern CSS resets and normalize stylesheets already handle this. If you're not using a reset, a single CSS rule takes care of it globally — no need to repeat the attribute on every <img> tag.

How to fix it

1. Remove the border attribute from all <img> elements.
2. Add a CSS rule to achieve the same effect. For removing borders, use img { border: 0; } in your stylesheet. For adding a visible border, use properties like border: 2px solid #333;.

Examples

❌ Obsolete border attribute

<a href="/products">

<img src="product.jpg" alt="Our product" border="0">

</a>

This triggers the validator warning because border is no longer a valid attribute on <img>.

✅ Fixed with CSS (external/internal stylesheet)

<style>

img {

border: 0;

}

</style>

<a href="/products">

<img src="product.jpg" alt="Our product">

</a>

A single rule in your stylesheet removes borders from all images, which is cleaner and easier to maintain than repeating the attribute on every element.

✅ Fixed with inline CSS (if needed)

<a href="/products">

<img src="product.jpg" alt="Our product" style="border: 0;">

</a>

Inline styles work but aren't ideal for large-scale fixes. Prefer a stylesheet rule when possible.

✅ Adding a decorative border with CSS

If your intent was to add a visible border (e.g., border="2"), replace it with a more flexible CSS equivalent:

<style>

.bordered {

border: 2px solid #333;

}

</style>

<img src="photo.jpg" alt="A scenic landscape" class="bordered">

CSS gives you far more control — you can specify the border style, color, individual sides, and even use border-radius for rounded corners, none of which were possible with the old border attribute.

The border attribute on the <img> element is obsolete in HTML5 and should be replaced with CSS.

Older versions of HTML allowed border as an attribute directly on <img> elements, most commonly set to 0 to remove the blue border that browsers added around images wrapped in links. HTML5 dropped this attribute from the specification. Modern browsers no longer add that default border, so in most cases the attribute can simply be removed.

If you still need to control the border on an image, use CSS instead. You can apply a style directly with the style attribute, use a class, or add a rule in your stylesheet.

HTML examples

Invalid: using the obsolete border attribute

<a href="/home">

<img src="logo.png" alt="Logo" border="0">

</a>

Valid: using CSS instead

<a href="/home">

<img src="logo.png" alt="Logo" style="border: 0;">

</a>

Or, with a stylesheet rule:

<style>

img {

border: 0;

}

</style>

<a href="/home">

<img src="logo.png" alt="Logo">

</a>

The border attribute on the <table> element is obsolete in HTML5 and should be replaced with CSS styling.

The border attribute was commonly used in older HTML to add borders to tables. In HTML5, the only valid value for the border attribute on a <table> is an empty string ("") or "1", and even then it's considered obsolete. The validator message mentions img { border: 0; } because the border attribute was also frequently used on <img> elements, but the same principle applies to tables — presentational attributes should be replaced with CSS.

To style table borders, use the CSS border property on the <table>, <th>, and <td> elements. The border-collapse property is also useful for controlling whether borders are merged or separated.

HTML Examples

❌ Invalid: using the obsolete border attribute

<table border="2">

<tr>

<td>Cell 1</td>

<td>Cell 2</td>

</tr>

</table>

✅ Valid: using CSS for borders

<style>

table, td {

border: 2px solid black;

border-collapse: collapse;

}

</style>

<table>

<tr>

<td>Cell 1</td>

<td>Cell 2</td>

</tr>

</table>

Every HTML element carries an implicit ARIA role that communicates its purpose to assistive technologies like screen readers. The <button> element natively has the button role built in, so explicitly adding role="button" is redundant. The W3C validator flags this as unnecessary because it adds no information — assistive technologies already understand that a <button> is a button.

The role attribute exists primarily to assign interactive semantics to elements that don't have them natively. For example, you might add role="button" to a <div> or <span> that has been styled and scripted to behave like a button (though using a native <button> is always preferable). When you apply it to an element that already carries that role by default, it creates noise in your code and can signal to other developers that something unusual is going on — when in fact nothing is.

This principle applies broadly across HTML. Other examples of redundant roles include role="link" on an <a> element with an href, role="navigation" on a <nav> element, and role="heading" on an <h1> through <h6> element. The WAI-ARIA specification refers to these as "default implicit ARIA semantics," and the general rule is: don't set an ARIA role that matches the element's native semantics.

Removing redundant roles keeps your markup clean, easier to maintain, and avoids potential confusion during code reviews or audits. It also aligns with the first rule of ARIA: "If you can use a native HTML element with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state, or property to make it accessible, then do so."

How to fix it

Remove the role="button" attribute from any <button> element. No replacement is needed — the native semantics are already correct.

If you have a non-button element (like a <div>) that uses role="button", consider replacing it with a real <button> element instead. This gives you built-in keyboard support, focus management, and form submission behavior for free.

Examples

❌ Redundant role on a button

<button role="button">Buy now</button>

<button type="submit" role="button">Submit</button>

Both of these trigger the validator warning because role="button" duplicates what the <button> element already communicates.

✅ Button without redundant role

<button>Buy now</button>

<button type="submit">Submit</button>

Simply removing the role attribute resolves the issue. The element's native semantics handle everything.

❌ Using role="button" on a non-semantic element

<div role="button" tabindex="0" onclick="handleClick()">Buy now</div>

While this is technically valid and won't trigger the same warning, it requires manual handling of keyboard events, focus styles, and accessibility states.

✅ Using a native button instead

<button onclick="handleClick()">Buy now</button>

A native <button> provides keyboard interaction (Enter and Space key activation), focusability, and correct role announcement — all without extra attributes or JavaScript.

Other common redundant roles to avoid

<!-- ❌ Redundant -->

<a href="/about" role="link">About</a>

<nav role="navigation">...</nav>

<h1 role="heading">Title</h1>

<input type="checkbox" role="checkbox">

<!-- ✅ Clean -->

<a href="/about">About</a>

<nav>...</nav>

<h1>Title</h1>

<input type="checkbox">

The WAI-ARIA specification defines implicit roles (also called "native semantics") for many HTML elements. An <input> element with type="submit" inherently communicates to assistive technologies that it is a button control. Adding role="button" explicitly restates what the browser and screen readers already know, making it redundant.

The role="button" attribute is designed for situations where you need to make a non-interactive element — such as a <div> or <span> — behave like a button for assistive technologies. When applied to elements that already carry this semantic meaning natively, it adds unnecessary noise to your markup without providing any accessibility benefit.

Why this is a problem

• Redundancy: The explicit role duplicates the element's built-in semantics, cluttering the HTML with no added value.
• Maintenance risk: Redundant ARIA attributes can mislead other developers into thinking the role is necessary, or that the element's native semantics differ from what they actually are.
• Standards compliance: The W3C validator flags this as an issue because the ARIA in HTML specification explicitly states that authors should not set ARIA roles or attributes that match an element's implicit native semantics. This principle is sometimes called the "first rule of ARIA" — don't use ARIA when a native HTML element already provides the semantics you need.
• Potential conflicts: While current browsers handle redundant roles gracefully, explicitly overriding native semantics can theoretically interfere with future browser or assistive technology behavior.

How to fix it

Remove the role="button" attribute from any <input type="submit"> element. The same principle applies to other input types with implicit roles, such as <input type="reset"> (which also has an implicit button role) and <button> elements.

Examples

❌ Incorrect: redundant role="button" on a submit input

<form action="/checkout" method="post">

<input type="submit" role="button" value="Buy Now">

</form>

✅ Correct: no explicit role needed

<form action="/checkout" method="post">

<input type="submit" value="Buy Now">

</form>

❌ Incorrect: redundant role on a <button> element

The same issue applies to <button> elements, which also have an implicit button role:

<button type="submit" role="button">Submit Order</button>

✅ Correct: let native semantics do the work

<button type="submit">Submit Order</button>

✅ Correct: using role="button" where it is appropriate

The role="button" attribute is meaningful when applied to an element that does not natively convey button semantics. Note that you must also handle keyboard interaction and focus management manually in this case:

<div role="button" tabindex="0">Add to Cart</div>

Even in this scenario, using a native <button> element is strongly preferred over adding ARIA roles to non-interactive elements, since the native element provides built-in keyboard support and focus behavior for free.

The <summary> element serves as the clickable disclosure toggle for a <details> element. Because its built-in behavior is inherently interactive — clicking it expands or collapses the parent <details> content — the HTML specification assigns it an implicit button role. This means assistive technologies like screen readers already announce <summary> as a button without any additional markup.

When you explicitly add role="button" to a <summary> element, the W3C validator flags it as unnecessary. While this doesn't cause functional problems, redundant ARIA roles are discouraged by the first rule of ARIA use: if an HTML element already has the semantics you need, don't re-add them with ARIA attributes. Redundant roles add noise to your code, can confuse other developers into thinking custom behavior is being applied, and in edge cases may interact unexpectedly with certain assistive technologies.

This principle applies broadly — many HTML elements have implicit roles (e.g., <nav> has navigation, <main> has main, <button> has button). Adding the role they already carry is always unnecessary.

How to fix it

Remove the role="button" attribute from the <summary> element. No replacement is needed since the semantics are already built in.

Examples

❌ Incorrect: redundant role="button" on <summary>

<details>

<summary role="button">Show more information</summary>

<p>Here is the additional information that was hidden.</p>

</details>

The validator will report: The "button" role is unnecessary for element "summary".

✅ Correct: <summary> without an explicit role

<details>

<summary>Show more information</summary>

<p>Here is the additional information that was hidden.</p>

</details>

The <summary> element's implicit button role ensures assistive technologies already treat it as an interactive control. No additional attributes are required.

✅ Correct: a more complete <details> example

<details>

<summary>I have keys but no doors. I have space but no room. You can enter but can't leave. What am I?</summary>

<p>A keyboard.</p>

</details>

Clicking the <summary> toggles the parent <details> element between its open and closed states. Screen readers announce it as a button automatically, and keyboard users can activate it with Enter or Space — all without any explicit ARIA role.

The <center> element is a presentational HTML tag that dates back to early web development. The HTML5 specification formally made it obsolete because it violates the principle of separating content (HTML) from presentation (CSS). While most browsers still render <center> correctly for backward compatibility, relying on it is discouraged for several reasons:

• Standards compliance: Using obsolete elements means your HTML does not conform to the current HTML specification, which can cause W3C validation errors.
• Maintainability: Inline presentational elements scatter styling throughout your markup, making it harder to update the design of your site consistently. CSS allows you to control layout from a single stylesheet.
• Accessibility: Semantic HTML helps assistive technologies understand content structure. The <center> element carries no semantic meaning and adds noise to the document.
• Future-proofing: Browser support for obsolete elements is not guaranteed indefinitely. Using CSS ensures your layout will work reliably going forward.

To fix this issue, replace every <center> element with an appropriate CSS technique. The right approach depends on what you're centering.

For inline content (text, images, inline elements), apply text-align: center to the parent container.

For block-level elements (divs, sections, etc.), use margin: 0 auto along with a defined width, or use Flexbox on the parent.

Examples

❌ Obsolete: using <center>

<center>

<p>This text is centered.</p>

</center>

✅ Fixed: using text-align for inline content

<div style="text-align: center">

<p>This text is centered.</p>

</div>

Or better yet, use a CSS class to keep styles out of your HTML:

<div class="centered-text">

<p>This text is centered.</p>

</div>

.centered-text {

text-align: center;

}

❌ Obsolete: centering a block element with <center>

<center>

<div>This box is centered.</div>

</center>

✅ Fixed: centering a block element with margin: auto

<div class="centered-box">

<p>This box is centered.</p>

</div>

.centered-box {

max-width: 600px;

margin: 0 auto;

}

✅ Fixed: centering with Flexbox

Flexbox is a powerful and flexible way to center content both horizontally and vertically:

<div class="flex-center">

<p>This content is centered.</p>

</div>

.flex-center {

display: flex;

justify-content: center;

}

✅ Applying the fix directly to an element

If you only need to center the text within a single element, you can apply the style directly without a wrapper:

<p class="centered">This paragraph is centered.</p>

.centered {

text-align: center;

}

In every case, the key takeaway is the same: remove the <center> element and use CSS to achieve the desired centering effect. This keeps your HTML clean, semantic, and fully compliant with modern standards.

Character encoding tells the browser how to map the raw bytes of your HTML file into readable characters. When no encoding is declared, browsers must rely on heuristics or defaults to figure out which encoding to use. The validator's fallback to "windows-1252" reflects the behavior described in the HTML specification: if no encoding information is found, parsers may default to this legacy encoding. This can cause serious problems — characters like curly quotes, em dashes, accented letters, emoji, and non-Latin scripts can appear as garbled text (often called "mojibake") if the actual encoding of the file doesn't match what the browser assumes.

Why this matters

• Correctness: If your file is saved as UTF-8 (which is the default in most modern editors) but the browser interprets it as windows-1252, multi-byte characters will render incorrectly.
• Standards compliance: The WHATWG HTML Living Standard requires that a character encoding declaration be present. The encoding must also be declared within the first 1024 bytes of the document.
• Security: Ambiguous encoding can be exploited in certain cross-site scripting (XSS) attacks where an attacker takes advantage of encoding mismatches.
• Interoperability: Different browsers may choose different fallback encodings, leading to inconsistent rendering across platforms.

How to fix it

The simplest and recommended fix is to add <meta charset="utf-8"> as the first child element inside <head>, before <title> or any other elements. It must appear within the first 1024 bytes of the document so the parser encounters it early enough.

UTF-8 is the universal standard for the web. It can represent every character in Unicode, is backward-compatible with ASCII, and is the encoding recommended by the WHATWG HTML specification. Unless you have a very specific reason to use another encoding, always use UTF-8.

You should also ensure your text editor or build tool is actually saving the file in UTF-8 encoding. Declaring <meta charset="utf-8"> while the file is saved in a different encoding will still produce garbled text.

An alternative (less common) approach is to declare the encoding via an HTTP Content-Type header sent by the server, such as Content-Type: text/html; charset=utf-8. However, the <meta> tag is still recommended as a fallback for when files are viewed locally or cached without headers.

Examples

❌ Missing character encoding declaration

This document has no encoding declaration, triggering the validator warning:

<!DOCTYPE html>

<html lang="en">

<head>

<title>My Page</title>

</head>

<body>

<p>Héllo, wörld! — enjoy "quotes" and emöji 🎉</p>

</body>

</html>

✅ Fixed with <meta charset="utf-8">

Adding the <meta charset="utf-8"> tag as the first element in <head> resolves the issue:

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="utf-8">

<title>My Page</title>

</head>

<body>

<p>Héllo, wörld! — enjoy "quotes" and emöji 🎉</p>

</body>

</html>

❌ Encoding declared too late

The <meta charset> must come before other content in the <head>. Placing it after a <title> that contains non-ASCII characters means the parser may have already committed to a wrong encoding:

<!DOCTYPE html>

<html lang="en">

<head>

<title>Café Menu</title>

<meta charset="utf-8">

</head>

<body>

<p>Welcome to the café.</p>

</body>

</html>

✅ Encoding declared before all other content

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="utf-8">

<title>Café Menu</title>

</head>

<body>

<p>Welcome to the café.</p>

</body>

</html>

The key takeaway: always place <meta charset="utf-8"> as the very first element inside <head>. This is a small addition that prevents a whole class of character rendering and security issues.

In earlier versions of HTML, the charset attribute on <link> was used to indicate the character encoding of the linked resource (such as a stylesheet or other external file). The HTML Living Standard has since made this attribute obsolete. Modern browsers determine the character encoding of linked resources through the Content-Type HTTP response header — for example, Content-Type: text/css; charset=UTF-8 — or by using default encoding rules defined in the relevant specification (CSS files, for instance, default to UTF-8).

Using the obsolete charset attribute creates several issues. It gives a false sense of control over encoding, since browsers don't actually use it. It also clutters your markup with unnecessary attributes, and it may signal to other developers that this is the mechanism being relied upon for encoding, when in reality it has no effect. For standards compliance and clean, future-proof markup, it should be removed.

The fix involves two steps: first, remove the charset attribute from your HTML; second, ensure your web server sends the correct Content-Type header for the linked resources.

Examples

Incorrect: using charset on a <link> element

<link rel="stylesheet" href="styles.css" charset="UTF-8">

<link rel="stylesheet" href="print.css" charset="iso-8859-1">

Both of these will trigger the validation warning because the charset attribute is obsolete on <link>.

Correct: charset attribute removed

<link rel="stylesheet" href="styles.css">

<link rel="stylesheet" href="print.css">

Simply removing the attribute resolves the validation error. The server should handle encoding declaration instead.

Full document example

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>Example Page</title>

<link rel="stylesheet" href="styles.css">

</head>

<body>

<h1>Hello, World!</h1>

</body>

</html>

Configuring the server to declare character encoding

Once you've removed the charset attribute, make sure your web server sends the proper Content-Type header with the linked resources. Most modern servers already default to UTF-8 for CSS and JavaScript files, but you can configure this explicitly.

Apache

Add the following to your .htaccess file or server configuration:

<FilesMatch "\.css$">

AddCharset UTF-8 .css

</FilesMatch>

This causes Apache to serve CSS files with the header Content-Type: text/css; charset=UTF-8.

Nginx

Add a charset directive to the relevant location block in your server configuration:

location ~* \.css$ {

charset utf-8;

}

Node.js (Express)

Set the Content-Type header explicitly when serving the file:

app.get('/styles.css', function(req, res) {

res.setHeader('Content-Type', 'text/css; charset=UTF-8');

res.sendFile(__dirname + '/styles.css');

});

If you're using Express's built-in static file middleware (express.static), it typically sets correct content types automatically based on file extensions.

Verifying the fix

You can confirm that the server is sending the correct header by opening your browser's developer tools, navigating to the Network tab, clicking on the linked resource, and inspecting the Content-Type response header. It should include charset=UTF-8 (or whichever encoding your file uses). Once the attribute is removed from your HTML and the server is configured correctly, the validation warning will be resolved.

The charset attribute was historically used to declare the character encoding of an external script file when it differed from the document's encoding. In modern HTML, this attribute is obsolete because the HTML specification now requires that the character encoding of an external script must match the encoding of the document itself. Since the document's encoding is already declared via <meta charset="UTF-8"> (or through HTTP headers), specifying it again on individual <script> elements is redundant and no longer valid.

If your external script files use a different encoding than your HTML document, the correct solution is to convert those script files to match the document's encoding (typically UTF-8) rather than using the charset attribute. UTF-8 is the recommended encoding for all web content and is supported universally across browsers.

This matters for standards compliance — the HTML living standard explicitly marks this attribute as obsolete. It also affects maintainability, since having encoding declarations scattered across script tags can create confusion about which encoding is actually in effect. Browsers may also ignore the attribute entirely, leading to unexpected behavior if you're relying on it.

How to fix it

1. Remove the charset attribute from all <script> elements.
2. Ensure your document declares its encoding using <meta charset="UTF-8"> inside the <head>.
3. Convert any script files that aren't already UTF-8 to use UTF-8 encoding. Most modern code editors can do this via "Save with Encoding" or a similar option.
4. While you're at it, you can also remove type="text/javascript" — this is the default type for scripts and is no longer needed.

Examples

Incorrect: using the obsolete charset attribute

<script src="app.js" type="text/javascript" charset="UTF-8"></script>

This triggers the validation warning because charset is obsolete. The type="text/javascript" is also unnecessary since it's the default.

Incorrect: charset on an inline script

<script charset="UTF-8">

console.log("Hello");

</script>

The charset attribute was only ever meaningful for external scripts, and even in that context it is now obsolete.

Correct: clean script element

<script src="app.js"></script>

Correct: ensuring encoding is declared at the document level

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>My Page</title>

<script src="app.js"></script>

</head>

<body>

<p>Content here.</p>

</body>

</html>

The <meta charset="UTF-8"> declaration in the <head> covers the encoding for the entire document, including all linked scripts. No additional charset attributes are needed on individual elements.

Many HTML5 semantic elements come with built-in (implicit) ARIA roles defined in the WAI-ARIA specification. The <aside> element is one of these — it natively maps to the complementary role, which tells assistive technologies that the content is related to the main content but can stand on its own. When you explicitly add role="complementary" to an <aside>, you're stating something the browser already knows, which triggers this W3C validator warning.

While this redundancy won't break anything for end users, it creates unnecessary noise in your code and can signal a misunderstanding of how semantic HTML works. Keeping markup free of redundant ARIA attributes follows the first rule of ARIA use: "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so." Clean, semantic HTML is easier to maintain and less prone to errors if ARIA roles are accidentally changed or conflict with the native semantics in the future.

This same principle applies to several other HTML elements, such as <nav> (implicit role navigation), <main> (implicit role main), <header> (implicit role banner when not nested), and <footer> (implicit role contentinfo when not nested).

Examples

❌ Redundant role on <aside>

The role="complementary" attribute is unnecessary because <aside> already implies it:

<aside role="complementary">

<h2>Related Articles</h2>

<ul>

<li><a href="/article-1">Understanding ARIA roles</a></li>

<li><a href="/article-2">Semantic HTML best practices</a></li>

</ul>

</aside>

✅ Using <aside> without the redundant role

Simply remove the role attribute:

<aside>

<h2>Related Articles</h2>

<ul>

<li><a href="/article-1">Understanding ARIA roles</a></li>

<li><a href="/article-2">Semantic HTML best practices</a></li>

</ul>

</aside>

✅ When an explicit role is appropriate

If you need to give the <aside> element a different role than its default, an explicit role attribute is valid and useful. For example, you might use <aside> for structural reasons but assign it a different ARIA role:

<aside role="note">

<p>This feature is only available in version 3.0 and later.</p>

</aside>

✅ Labeling multiple <aside> elements

If your page has multiple <aside> elements, you don't need to add role="complementary" to distinguish them. Instead, use aria-label or aria-labelledby to give each a unique accessible name:

<aside aria-label="Related articles">

<h2>Related Articles</h2>

<ul>

<li><a href="/article-1">Understanding ARIA roles</a></li>

</ul>

</aside>

<aside aria-labelledby="ad-heading">

<h2 id="ad-heading">Sponsored Content</h2>

<p>Check out our latest product.</p>

</aside>

The HTML specification maps certain elements to implicit ARIA roles. The <footer> element, when used as a direct child of <body> (i.e., not nested inside an <article>, <aside>, <main>, <nav>, or <section> element), automatically carries the contentinfo landmark role. This means screen readers and other assistive technologies already announce it as a content information landmark without any extra markup.

Adding role="contentinfo" to a <footer> element is redundant because:

• It duplicates built-in semantics. Browsers already expose the correct role to the accessibility tree. Repeating it adds no benefit and clutters your markup.
• It can cause confusion for developers. Seeing an explicit role might suggest the element doesn't have one by default, leading to misunderstandings about how HTML semantics work.
• It violates the first rule of ARIA use. The W3C's "Using ARIA" guide states: "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so."

It's worth noting that when a <footer> is nested inside a sectioning element like <article> or <section>, it does not carry the contentinfo role — it maps to a generic role instead. In that context, adding role="contentinfo" would actually change the element's semantics rather than being redundant, though doing so is generally not appropriate since each page should have only one contentinfo landmark.

If you are working with a <div> that serves as a footer (perhaps in legacy code), the best approach is to replace it with a semantic <footer> element rather than applying role="contentinfo" to the <div>.

Examples

❌ Redundant role on <footer>

This triggers the validator warning because the role is already implicit:

<footer role="contentinfo">

<p>&copy; 2024 Example Corp. All rights reserved.</p>

</footer>

✅ Fixed: <footer> without redundant role

Simply remove the role="contentinfo" attribute:

<footer>

<p>&copy; 2024 Example Corp. All rights reserved.</p>

</footer>

✅ Using a <div> as a footer (legacy pattern)

If you cannot use a <footer> element for some reason, applying role="contentinfo" to a <div> is valid and meaningful since the <div> has no implicit role:

<div role="contentinfo">

<p>&copy; 2024 Example Corp. All rights reserved.</p>

</div>

However, replacing the <div> with a <footer> is always the preferred approach.

✅ Nested footer inside a section

When <footer> appears inside a sectioning element, it does not carry the contentinfo role. No explicit role is needed here either — it simply represents footer content for that section:

<article>

<h2>Blog Post Title</h2>

<p>Article content here.</p>

<footer>

<p>Published on January 1, 2024</p>

</footer>

</article>

The <dialog> element triggers an informational warning from the W3C validator, not an error. The markup is valid HTML, and no code change is needed to resolve this message.

The <dialog> element is a native HTML element for modal and non-modal dialog boxes. It was part of the HTML specification for years before all major browsers implemented it. As of 2022, all major browsers (Chrome, Firefox, Safari, and Edge) support <dialog> natively. The W3C validator warning is outdated for most practical purposes, since browser support is now widespread.

The <dialog> element provides built-in features that are difficult to replicate with custom markup: a showModal() method that creates a top-layer modal with a backdrop, automatic focus trapping, and Esc key dismissal. It also exposes the correct ARIA role (dialog) by default, which improves accessibility without extra attributes.

If you still need to support older browsers (such as Internet Explorer or pre-2022 Safari), you can include the dialog-polyfill library. Otherwise, the warning can be safely ignored.

HTML example

<dialog id="confirm">

<form method="dialog">

<p>Are you sure?</p>

<button value="no">Cancel</button>

<button value="yes">Confirm</button>

</form>

</dialog>

<button onclick="document.getElementById('confirm').showModal()">

Open dialog

</button>

Using method="dialog" on the form allows the dialog to close automatically when a button inside it is clicked, with the button's value available through the dialog's returnValue property.

The <dialog> element was introduced to provide a native way to create modal and non-modal dialog boxes in HTML. As defined in the WHATWG HTML Living Standard and the ARIA in HTML specification, every <dialog> element automatically carries an implicit dialog role. This means assistive technologies like screen readers already recognize it as a dialog without any additional ARIA markup.

When you explicitly add role="dialog" to a <dialog> element, you're restating what the browser and assistive technologies already know. This violates the first rule of ARIA use: do not use ARIA if you can use a native HTML element or attribute with the semantics already built in. While this redundancy won't break functionality, it clutters your markup and signals to other developers (and validators) that the author may not understand the element's built-in semantics.

This principle applies broadly across HTML. Many elements have implicit ARIA roles — <nav> has navigation, <main> has main, <button> has button, and so on. Adding the matching role explicitly to any of these elements produces a similar validator warning.

How to fix it

Simply remove the role="dialog" attribute from the <dialog> element. The built-in semantics handle everything automatically. If you need to provide additional context for assistive technologies, consider using aria-label or aria-labelledby to give the dialog a descriptive accessible name — that's genuinely useful supplementary information rather than a redundant role.

Examples

Incorrect: redundant role attribute

<dialog role="dialog">

<h2>Confirm action</h2>

<p>Are you sure you want to delete this item?</p>

<button>Cancel</button>

<button>Delete</button>

</dialog>

This triggers the validator warning because role="dialog" duplicates the implicit role of the <dialog> element.

Correct: relying on implicit semantics

<dialog>

<h2>Confirm action</h2>

<p>Are you sure you want to delete this item?</p>

<button>Cancel</button>

<button>Delete</button>

</dialog>

Correct: adding a descriptive accessible name

<dialog aria-labelledby="dialog-title">

<h2 id="dialog-title">Confirm action</h2>

<p>Are you sure you want to delete this item?</p>

<button>Cancel</button>

<button>Delete</button>

</dialog>

Using aria-labelledby to associate the dialog with its heading is a meaningful enhancement — it gives the dialog an accessible name that screen readers announce when the dialog opens. This is the kind of ARIA usage that genuinely improves accessibility, as opposed to redundantly restating the element's role.

The HTML specification restricts what can appear inside a comment. Specifically, a comment must not contain the string -- (two consecutive hyphens) except as part of the opening and closing delimiters. This rule originates from SGML and XML 1.0, where -- is treated as a comment delimiter, and having extra occurrences inside the comment body creates ambiguity about where the comment starts and ends.

While most modern browsers are lenient and will handle comments with double hyphens without issues, the markup is technically invalid. This matters for several reasons:

• XML compatibility: If your HTML is served as XHTML or processed by XML parsers, double hyphens inside comments will cause parsing errors and potentially break the entire document.
• Standards compliance: The HTML living standard explicitly states that comments must not contain --, so validators flag this as an error.
• Predictable parsing: Different parsers may interpret malformed comments differently, leading to inconsistent behavior across tools, crawlers, and assistive technologies.

To fix the issue, look inside your comment text and replace any occurrence of -- with something else, such as a single hyphen, an equals sign, or a different separator.

Examples

Incorrect: double hyphens inside the comment body

<!-- This is a separator ---------- end of section -->

The string of hyphens inside the comment contains multiple consecutive -- pairs, making the comment invalid.

<!-- Do not use -- as a separator -->

Here, -- appears literally in the comment text, which violates the rule.

<!-- TODO -- fix this later -- maybe next sprint -->

Multiple -- sequences appear as casual text separators, each one triggering the validation error.

Correct: avoiding double hyphens

Replace double hyphens with a different character or pattern:

<!-- This is a separator ========== end of section -->

<!-- Do not use dashes as a separator -->

<!-- TODO: fix this later, maybe next sprint -->

Correct: standard comment syntax

Simple comments that don't contain -- in their body are perfectly valid:

<!-- This is a valid comment -->

<!--

Multi-line comments are fine too,

as long as they don't contain double hyphens.

-->

Common pitfall: decorative comment borders

Developers sometimes use hyphens to create visual separators in their source code:

<!-- -------------------------------- -->

<!-- Navigation Section -->

<!-- -------------------------------- -->

Replace these with a different character:

<!-- ================================ -->

<!-- Navigation Section -->

<!-- ================================ -->

Or simply remove the decorative lines:

<!-- Navigation Section -->

The WAI-ARIA specification defines strict rules about which elements can be children of interactive roles. An element with role="button" is treated as an interactive control, and the <a> element (when it has an href) is also an interactive control. Nesting one interactive element inside another creates what's known as an interactive content nesting violation. Screen readers and other assistive technologies cannot reliably determine user intent when they encounter this pattern — should they announce a button, a link, or both? The result is unpredictable behavior that can make your content inaccessible.

This issue commonly appears when developers wrap links inside styled containers that have been given role="button", or when using component libraries that apply button semantics to wrapper elements containing anchor tags.

Beyond accessibility, browsers themselves handle nested interactive elements inconsistently. Some may ignore the outer interactive role, while others may prevent the inner link from functioning correctly. This makes the pattern unreliable even for users who don't rely on assistive technologies.

How to fix it

There are several approaches depending on your intent:

1. If the element should navigate to a URL, use an <a> element and style it to look like a button. Remove the role="button" from the parent or eliminate the parent wrapper entirely.
2. If the element should perform an action (not navigation), use a <button> element or an element with role="button", and handle the action with JavaScript. Remove the nested <a> tag.
3. If you need both a button container and a link, flatten the structure so they are siblings rather than nested.

When using role="button" on a non-button element, remember that you must also handle keyboard interaction (Enter and Space key presses) and include tabindex="0" to make it focusable.

Examples

❌ Incorrect: link nested inside a button role

<div role="button">

<a href="/dashboard">Go to Dashboard</a>

</div>

This triggers the validation error because the <a> is a descendant of an element with role="button".

✅ Fix 1: Use a styled link instead

If the intent is navigation, remove the button role and let the <a> element do the job. Style it to look like a button with CSS.

<a href="/dashboard" class="btn">Go to Dashboard</a>

This is the simplest and most semantically correct fix when the purpose is to navigate the user to another page.

✅ Fix 2: Use a real button for actions

If the intent is to trigger an action (not navigate), replace the entire structure with a <button> element.

<button type="button" class="btn" onclick="navigateToDashboard()">

Go to Dashboard

</button>

✅ Fix 3: Use a div with role="button" without nested interactive elements

If you need a custom button using role="button", make sure it contains no interactive descendants.

<div role="button" tabindex="0">

Go to Dashboard

</div>

When using this approach, you must also add keyboard event handlers for Enter and Space to match native button behavior.

❌ Incorrect: link inside a button element

The same principle applies to native <button> elements, not just elements with role="button":

<button>

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

</button>

✅ Fixed: choose one interactive element

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

❌ Incorrect: deeply nested link

The error applies to any level of nesting, not just direct children:

<div role="button">

<span class="icon-wrapper">

<a href="/help">Help</a>

</span>

</div>

✅ Fixed: flatten the structure

<a href="/help" class="btn">

<span class="icon-wrapper">Help</span>

</a>

As a rule of thumb, every interactive element in your page should have a single, clear role. If something looks like a button but navigates to a URL, make it an <a> styled as a button. If it performs an in-page action, make it a <button>. Keeping these roles distinct ensures your HTML is valid, accessible, and behaves consistently across browsers and assistive technologies.