Verificação HTML: O elemento "a" não deve aparecer como descendente de um elemento com o atributo "role=button".

Sobre este problema HTML

A especificação WAI-ARIA define regras rigorosas sobre quais elementos podem ser filhos de papéis interativos. Um elemento com role="button" é tratado como um controlo interativo, e o elemento <a> (quando tem um href) também é um controlo interativo. Aninhar um elemento interativo dentro de outro cria o que é conhecido como uma violação de aninhamento de conteúdo interativo. Leitores de ecrã e outras tecnologias de apoio não conseguem determinar de forma confiável a intenção do utilizador quando encontram este padrão — devem anunciar um botão, um link, ou ambos? O resultado é um comportamento imprevisível que pode tornar o seu conteúdo inacessível.

Este problema aparece comumente quando os programadores envolvem links dentro de contentores estilizados que receberam role="button", ou quando usam bibliotecas de componentes que aplicam semântica de botão a elementos wrapper contendo tags âncora.

Além da acessibilidade, os próprios navegadores lidam com elementos interativos aninhados de forma inconsistente. Alguns podem ignorar o papel interativo exterior, enquanto outros podem impedir que o link interior funcione corretamente. Isto torna o padrão não confiável mesmo para utilizadores que não dependem de tecnologias de apoio.

Como corrigir

Existem várias abordagens dependendo da sua intenção:

Se o elemento deve navegar para um URL, use um elemento <a> e estilize-o para parecer um botão. Remova o role="button" do pai ou elimine completamente o wrapper pai.
Se o elemento deve executar uma ação (não navegação), use um elemento <button> ou um elemento com role="button", e processe a ação com JavaScript. Remova a tag <a> aninhada.
Se você precisa tanto de um contentor botão quanto de um link, achate a estrutura para que sejam irmãos em vez de aninhados.

Quando usar role="button" num elemento que não é um botão, lembre-se de que também deve lidar com a interação por teclado (pressionar teclas Enter e Espaço) e incluir tabindex="0" para o tornar focalizável.

Exemplos

❌ Incorreto: link aninhado dentro de um papel de botão

<div role="button">
  <a href="/dashboard">Ir para Dashboard</a>
</div>

Isto ativa o erro de validação porque o <a> é descendente de um elemento com role="button".

✅ Correção 1: use um link estilizado

Se a intenção é navegação, remova o papel de botão e deixe o elemento <a> fazer o trabalho. Estilize-o para parecer um botão com CSS.

<a href="/dashboard" class="btn">Ir para Dashboard</a>

Esta é a correção mais simples e semanticamente correta quando o objetivo é navegar o utilizador para outra página.

✅ Correção 2: use um botão real para ações

Se a intenção é ativar uma ação (não navegar), substitua toda a estrutura por um elemento <button>.

<button type="button" class="btn" onclick="navigateToDashboard()">
  Ir para Dashboard
</button>

✅ Correção 3: use uma div com `role="button"` sem elementos interativos aninhados

Se você precisa de um botão personalizado usando role="button", certifique-se de que não contém descendentes interativos.

<div role="button" tabindex="0">
  Ir para Dashboard
</div>

Quando usar esta abordagem, também deve adicionar handlers de eventos de teclado para Enter e Espaço para corresponder ao comportamento nativo do botão.

❌ Incorreto: link dentro de um elemento botão

O mesmo princípio aplica-se a elementos <button> nativos, não apenas a elementos com role="button":

<button>
  <a href="/settings">Definições</a>
</button>

✅ Corrigido: escolha um elemento interativo

<a href="/settings" class="btn">Definições</a>

❌ Incorreto: link profundamente aninhado

O erro aplica-se a qualquer nível de aninhamento, não apenas a filhos diretos:

<div role="button">
  <span class="icon-wrapper">
    <a href="/help">Ajuda</a>
  </span>
</div>

✅ Corrigido: achate a estrutura

<a href="/help" class="btn">
  <span class="icon-wrapper">Ajuda</span>
</a>

Como regra geral, cada elemento interativo na sua página deve ter um papel único e claro. Se algo parece um botão mas navega para um URL, torne-o um <a> estilizado como botão. Se executa uma ação na página, torne-o um <button>. Manter estes papéis distintos garante que o seu HTML é válido, acessível e comporta-se consistentemente entre navegadores e tecnologias de apoio.