Verificação HTML: O elemento X está a faltar um ou mais dos seguintes atributos: "role".

Sobre este problema HTML

ARIA (Accessible Rich Internet Applications) funciona como um sistema onde papéis definem o que um elemento é, e estados e propriedades descrevem a condição atual ou características do elemento. Certos atributos ARIA são apenas válidos quando usados em elementos que têm um papel específico — seja explicitamente declarado através do atributo role ou implicitamente fornecido pelo próprio elemento HTML. Quando adiciona um estado ou propriedade ARIA a um elemento genérico como um <div> ou <span> sem especificar um papel, as tecnologias assistivas não têm contexto para interpretar esse atributo. Por exemplo, aria-expanded="true" num <div> simples diz a um leitor de ecrã que algo está expandido, mas não comunica o que está expandido — é um botão, um menu de navegação, um item de árvore? O papel fornece esse contexto crucial.

Isto é importante por várias razões:

Acessibilidade: Os leitores de ecrã e outras tecnologias assistivas dependem da combinação de papéis e os seus estados/propriedades associados para transmitir informação significativa aos utilizadores. Uma propriedade ARIA sem um papel é ambígua e pode levar a uma experiência confusa.
Conformidade com normas: A especificação WAI-ARIA define quais estados e propriedades são permitidos em quais papéis. Usar um atributo ARIA fora de um contexto de papel válido viola a especificação.
Comportamento previsível: Os navegadores e tecnologias assistivas podem lidar com atributos ARIA órfãos de forma inconsistente, levando a resultados imprevisíveis em diferentes plataformas.

Para corrigir este problema, tem duas abordagens:

Adicione um atributo role explícito ao elemento, escolhendo um papel que suporte os atributos ARIA que está a usar.
Use um elemento HTML semântico que já tenha um papel ARIA implícito. Por exemplo, <nav> tem um papel implícito de navigation, <button> tem um papel implícito de button, e <header> tem um papel implícito de banner. Esta é geralmente a abordagem preferida, pois fornece interação de teclado e semântica integradas sem esforço extra.

Ao escolher um papel, certifique-se de que os estados e propriedades ARIA que está a usar são realmente suportados por esse papel. Por exemplo, aria-expanded é suportado por papéis como button, combobox, link, treeitem, e outros — mas não por todos os papéis. Consulte a documentação de papéis WAI-ARIA para verificar a compatibilidade.

Exemplos

Inválido: propriedade ARIA sem um papel

Este <div> usa aria-expanded mas não tem papel, portanto o validador não sabe que tipo de elemento este deveria ser.

<div aria-expanded="true">
  Conteúdo do menu
</div>

Corrigido: adicionar um papel explícito

Adicionar role="button" diz às tecnologias assistivas que este é um botão que pode ser expandido ou colapsado.

<div role="button" aria-expanded="true" tabindex="0">
  Conteúdo do menu
</div>

Corrigido: usar um elemento HTML semântico em vez disso

Um elemento <button> já tem um papel button implícito, portanto não é necessário nenhum atributo role explícito. Esta é a abordagem preferida.

<button aria-expanded="true">
  Alternar menu
</button>

Inválido: `aria-label` num elemento genérico

Um <span> não tem papel implícito, portanto aria-label não tem contexto significativo aqui.

<span aria-label="Fechar diálogo">X</span>

Corrigido: usar um elemento semântico ou adicionar um papel

<button aria-label="Fechar diálogo">X</button>

Ou, se precisar de usar um <span>:

<span role="button" tabindex="0" aria-label="Fechar diálogo">X</span>

Usar elementos com papéis implícitos

Muitos elementos HTML já carregam papéis ARIA implícitos, portanto adicionar estados e propriedades ARIA a eles é válido sem um atributo role explícito:

<!-- <nav> tem role="navigation" implícito -->

<nav aria-label="Navegação principal">
  <ul>
    <li><a href="/">Início</a></li>
    <li><a href="/about">Sobre</a></li>
  </ul>
</nav>

<!-- <details> suporta aria-expanded implicitamente -->

<details aria-describedby="help-text">
  <summary>Mais informações</summary>
  <p id="help-text">Detalhes adicionais sobre este tópico.</p>
</details>

Como regra geral, prefira sempre elementos HTML semânticos nativos em vez de elementos genéricos com papéis ARIA. Os elementos nativos vêm com suporte de teclado integrado, gestão de foco e semântica de acessibilidade — reduzindo a quantidade de código personalizado que precisa de escrever e manter.