Regra de acessibilidade: aria-roledescription deve estar em elementos com um role semântico

Sobre esta regra de acessibilidade

Porque isto é importante

O atributo aria-roledescription permite aos autores fornecer uma descrição legível e localizada do role de um elemento. Por exemplo, você pode usá-lo para descrever um role="slider" como “seletor de prioridade” para que um leitor de ecrã anuncie algo mais significativo ao utilizador. No entanto, este atributo só funciona quando o elemento já tem um role que as tecnologias assistivas podem identificar.

Quando aria-roledescription é colocado num elemento sem role semântico — como um <div>, <span>, ou <p> simples — não há role para a descrição refinar. Isto cria uma situação confusa onde as tecnologias assistivas podem anunciar uma descrição sem contexto, não anunciar nada, ou comportar-se de forma imprevisível. Em alguns casos, isto pode quebrar a acessibilidade de secções inteiras de uma aplicação.

Este problema afeta principalmente utilizadores cegos, utilizadores surdocegos, e utilizadores com limitações de mobilidade que dependem de leitores de ecrã ou outras tecnologias assistivas para compreender e navegar no conteúdo da página. Quando a informação do role é sem sentido ou está em falta, estes utilizadores perdem a capacidade de compreender o que é um elemento da interface e como interagir com ele.

Critérios de sucesso WCAG relacionados

Esta regra relaciona-se com o Critério de Sucesso WCAG 4.1.2: Nome, Role, Valor (Nível A), que exige que para todos os componentes da interface de utilizador, o nome, role e valor possam ser determinados programaticamente. Quando aria-roledescription é aplicado a um elemento sem um role semântico, o role não pode ser comunicado adequadamente, violando este critério.

Isto aplica-se a WCAG 2.0, 2.1, e 2.2 ao Nível A, bem como à directriz EN 301 549 9.4.1.2.

Como funciona a regra

A regra axe aria-roledescription verifica cada elemento que tem um atributo aria-roledescription e confirma que o elemento também tem um role semântico. Há três resultados possíveis:

Falha: O elemento não tem role nenhum (ex: <div>, <span>, <p> sem um atributo role explícito). Estes elementos têm um role genérico ou nenhum role implícito, por isso aria-roledescription não tem nada para descrever.
Passa: O elemento tem um role implícito bem suportado (como <button>, <img>, <nav>) ou um role explícito (como role="combobox").
Incompleto (precisa de revisão): O elemento tem um role que pode não ser amplamente suportado pelas tecnologias assistivas (ex: role="rowgroup"). Estes precisam de teste manual para verificar se funcionam corretamente.

Como corrigir

Identifique os elementos sinalizados pela regra — têm aria-roledescription mas nenhum role semântico.
Decida se o elemento realmente precisa de aria-roledescription. Em muitos casos, a solução é simplesmente removê-lo.
Se a descrição for necessária, faça uma das seguintes:
- Use um elemento HTML semântico que tenha um role implícito (ex: substitua <div> por <button>).
- Adicione um atributo role explícito ao elemento para que a descrição tenha contexto.
Certifique-se de que o valor aria-roledescription refina significativamente o role — deve descrever uma versão mais específica do que o elemento é, não contradizê-lo.

Exemplos

Incorreto: `aria-roledescription` em elementos sem role semântico

Estes elementos não têm role implícito ou explícito, por isso aria-roledescription não tem nada para descrever.

<p aria-roledescription="my paragraph">
  This is some text.
</p>

<div aria-roledescription="my container">
  Some content here.
</div>

<span aria-roledescription="my label">Name</span>

Um <p> não tem um role ARIA correspondente, e um <div> ou <span> simples não mapeia para nenhum role (ou para o role genérico generic). Os leitores de ecrã não conseguem usar a descrição de forma significativa.

Correto: `aria-roledescription` em elementos com um role implícito

Estes elementos HTML têm roles semânticos integrados, por isso a descrição refina algo real.

<img
  aria-roledescription="illustration"
  src="diagram.png"
  alt="System architecture overview" />

<button aria-roledescription="play control">
  Play
</button>

O elemento <img> tem um role implícito de img, e <button> tem um role implícito de button. Os valores aria-roledescription fornecem descrições mais específicas destes roles.

Correto: `aria-roledescription` em elementos com um role explícito

<div
  role="combobox"
  aria-roledescription="city picker"
  aria-expanded="false"
  aria-haspopup="listbox">
  Select a city
</div>

<div
  role="slider"
  aria-roledescription="priority selector"
  aria-valuenow="3"
  aria-valuemin="1"
  aria-valuemax="5"
  tabindex="0">
</div>

O atributo role explícito fornece a base semântica, e aria-roledescription adiciona uma etiqueta mais amigável para o utilizador do que esse role representa neste contexto específico.

Correção incorreta: Adicionar um role incompatível apenas para satisfazer a regra

Não adicione um role que não corresponda ao comportamento real do elemento apenas para passar na verificação.

<!-- Não faça isto -->

<p role="button" aria-roledescription="my paragraph">
  This is some text.
</p>

Se o elemento é apenas um parágrafo de texto, remova aria-roledescription completamente em vez de adicionar um role incorreto.

Precisa de revisão: `aria-roledescription` em elementos com suporte limitado do role

Alguns roles têm suporte inconsistente das tecnologias assistivas. Estes serão sinalizados como precisando de revisão manual.

<h1 aria-roledescription="page title">Welcome</h1>

<div role="rowgroup" aria-roledescription="data section">
<!-- row content -->

</div>

O role heading e o role rowgroup podem não suportar consistentemente aria-roledescription em todos os leitores de ecrã. Teste estes casos manualmente com tecnologias assistivas reais para confirmar que a descrição é anunciada corretamente.

Learn more: