The element “a” must not appear as a descendant of the “button” element.

A button element, or an element with the role=button attribute, is not allowed to be nested inside an <a> element.

When you encounter the issue where the <a> element is nested inside an element with role="button", it’s important to understand that this can lead to accessibility conflicts. The role="button" indicates that the element is interactive, similar to a button. Nesting an <a> (which is also an interactive element) inside it can confuse assistive technologies.

How to Fix This Issue

You should either change the structure so that the <a> is not inside the button or change the role of the button to avoid this violation. Here are two common approaches to resolve the issue:

Option 1: Remove the <a> Tag

Replace the <a> tag with an appropriate action directly inside the element with role="button".

Example Before:

<div role="button">
  <a href="#link">Click here</a>
</div>

Example After:

<div role="button" tabindex="0" onclick="location.href='#link';">
  Click here
</div>

Here, we use JavaScript to navigate to the link when the div is clicked.

Option 2: Remove the role="button"

If the <a> tag is sufficient by itself, you can remove the role="button" from the surrounding element.

Example Before:

<div role="button">
  <a href="#link">Click here</a>
</div>

Example After:

<a href="#link">Click here</a>

This maintains the desired navigation without creating a conflict between the button and link semantics.

A button element, or an element with the role=button attribute, is not allowed to be nested inside an <a> element.

A descendant element with a tabindex attribute cannot be nested inside an element that uses role="button".

The role="button" attribute marks an element as a button for assistive technologies, but true button elements (using the button tag) should typically manage focus and tab order on their own. Adding a nested element with tabindex inside a role=”button” container can confuse keyboard navigation and accessibility tools. Each tabbable element should have a clear, non-overlapping place in the focus order.

Incorrect example (causes the error):

<div role="button">
  <span tabindex="0">Click me</span>
</div>

Corrected example 1: Move tabindex to the container

<div role="button" tabindex="0">
  <span>Click me</span>
</div>

Corrected example 2: Use a native button element

<button>
  <span>Click me</span>
</button>

Whenever possible, use native elements like button, as they provide correct focus, keyboard, and accessibility behavior without extra attributes or roles. Only use role="button" with proper keyboard and accessibility support if absolutely necessary, and avoid tabbable descendants within such containers.

An <a> element cannot contain a descendant element with the attribute tabindex.

A button element cannot contain a descendant element with the attribute tabindex.

The aria-expanded attribute can only be true, false, or undefined.

This attribute indicates whether a grouping element is expanded or collapsed.

An element like <h1>, <h2>, etc., used to define a heading, does not accept the button role.

The following HTML code is invalid because the <h2> element can’t have role="button"

<h2 role="button">Some heading</h2>

Instead, you can nest the <h2> inside a <div> with that role. In this case however, browsers automatically apply role presentation to all descendant elements of any button element as it is a role that does not support semantic children.

<div role="button">
  <h2>Some heading</h2>
</div>

A <li> element, used to define a list item, does not accept the button role.

This HTML code is invalid because the <li> elements can’t have role="button":

<ul>
  <li role="button">One</li>
  <li role="button">Two</li>
</ul>

Spaces are not permitted in the href value for phone links; the phone number must be a continuous string without spaces or slashes.

The href attribute of an anchor (<a>) element defines the link’s destination. For phone numbers, the proper URI scheme is tel:, not callto:. According to the HTML standard and the WHATWG Living Standard, the phone number should contain only digits and may use plus (+) or hyphen (-) characters for formatting, but it should not include spaces or slashes.

Incorrect HTML:

<a href="callto:07142/ 12 34 5">Call us</a>

Correct HTML:

<a href="tel:0714212345">Call us</a>

With country code and optional formatting:

<a href="tel:+49714212345">Call us</a>

For best compatibility and validation, always use the tel: scheme and ensure the phone number string contains only allowed characters.