Verificação HTML: Valor inválido "button" para o atributo "role" no elemento "h1" (ou h2, h3, h4, h5, h6).

Sobre este problema HTML

A especificação ARIA in HTML define quais roles são permitidos em cada elemento HTML. Os elementos de cabeçalho (<h1>–<h6>) têm um role implícito de heading, e o conjunto de roles que podem ser explicitamente atribuídos é limitado. O role button não está entre eles, portanto aplicar role="button" diretamente a um elemento de cabeçalho é inválido.

Isto é importante por várias razões. Primeiro, os cabeçalhos desempenham um papel crítico na estrutura do documento e acessibilidade — os utilizadores de leitores de ecrã dependem dos cabeçalhos para navegar e compreender a hierarquia da página. Atribuir role="button" a um cabeçalho substitui o seu significado semântico, o que confunde as tecnologias assistivas. Segundo, os navegadores e leitores de ecrã podem lidar com semânticas conflituosas de forma imprevisível, levando a uma experiência inconsistente para os utilizadores. Terceiro, viola a especificação W3C HTML, o que significa que a sua marcação não passará na validação.

Porque esta combinação é problemática

Quando você aplica role="button" a um elemento, as tecnologias assistivas tratam-no como um botão interativo. Isto substitui completamente a semântica nativa de cabeçalho do elemento. Os utilizadores que navegam por cabeçalhos já não encontrariam esse cabeçalho na sua lista, e os utilizadores que navegam por controlos interativos encontrariam um “botão” que pode não se comportar como tal (faltando suporte de teclado, gestão de foco, etc.).

Se você genuinamente precisa de algo que pareça um cabeçalho mas aja como um botão, existem abordagens válidas para conseguir isto sem quebrar a semântica.

Como corrigir

Existem várias estratégias dependendo da sua intenção:

Use um elemento <button> estilizado como um cabeçalho. Esta é frequentemente a abordagem mais limpa quando o propósito principal é a interatividade. Você pode estilizar o botão com CSS para corresponder à aparência do seu cabeçalho.
Envolva o cabeçalho num <div> com role="button". Isto preserva o cabeçalho no esquema do documento enquanto torna o contentor interativo. No entanto, esteja ciente de que o role button aplica role="presentation" a todos os elementos descendentes, o que significa que as tecnologias assistivas irão remover a semântica de cabeçalho do <h2> dentro dele. O conteúdo do texto permanece acessível, mas não será reconhecido como um cabeçalho.
Coloque um <button> dentro do cabeçalho. Isto mantém a semântica de cabeçalho intacta para a estrutura do documento enquanto torna o texto dentro dele interativo. Este padrão é comumente usado para componentes no estilo acordeão e é a abordagem recomendada pelas WAI-ARIA Authoring Practices.

Exemplos

❌ Inválido: `role="button"` num cabeçalho

<h2 role="button">Toggle Section</h2>

Isto desencadeia o erro de validação porque button não é um role permitido para elementos de cabeçalho.

✅ Correção: use um `<button>` estilizado como um cabeçalho

<button type="button" class="heading-style">Toggle Section</button>

.heading-style {
  font-size: 1.5em;
  font-weight: bold;
  background: none;
  border: none;
  cursor: pointer;
}

✅ Correção: envolva o cabeçalho num contentor com `role="button"`

<div role="button" tabindex="0">
  <h2>Toggle Section</h2>
</div>

Note que esta abordagem faz com que o <h2> perca a sua semântica de cabeçalho para as tecnologias assistivas, uma vez que o role button não suporta elementos filhos semânticos. Lembre-se também de adicionar tabindex="0" para que o elemento seja focalizável pelo teclado, e implemente manipuladores keydown para Enter e Espaço para replicar o comportamento nativo do botão.

✅ Correção: coloque um `<button>` dentro do cabeçalho (recomendado para acordeões)

<h2>
  <button type="button" aria-expanded="false">
    Toggle Section
  </button>
</h2>

Este é o padrão mais robusto. O cabeçalho permanece no esquema do documento, e o botão dentro dele é totalmente interativo com suporte de teclado incorporado. Os utilizadores de leitores de ecrã podem encontrá-lo tanto ao navegar por cabeçalhos como ao navegar por elementos interativos. O atributo aria-expanded comunica se a secção associada está aberta ou fechada.