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

Sobre esta regra de acessibilidade

Por que isto é importante

O atributo aria-roledescription permite que os autores forneçam uma descrição legível e localizada do papel 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 para o utilizador. No entanto, este atributo só funciona quando o elemento já tem um papel que as tecnologias assistivas consigam identificar.

Quando aria-roledescription é colocado num elemento sem papel semântico — como um <div>, <span>, ou <p> simples — não há papel 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 para secções inteiras de uma aplicação.

Este problema afeta principalmente utilizadores cegos, utilizadores surdocegos, e utilizadores com limitações motoras 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 papel é 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, Papel, Valor (Nível A), que requer que para todos os componentes da interface do utilizador, o nome, papel e valor possam ser determinados programaticamente. Quando aria-roledescription é aplicado a um elemento sem papel semântico, o papel não pode ser comunicado adequadamente, violando este critério.

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

Como a regra funciona

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

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

Como corrigir

Identifique os elementos sinalizados pela regra — têm aria-roledescription mas nenhum papel semântico.
Decida se o elemento realmente necessita aria-roledescription. Em muitos casos, a solução é simplesmente removê-lo.
Se a descrição for necessária, faça uma das seguintes opções:
- Use um elemento HTML semântico que carregue um papel implícito (por exemplo, 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 o papel de forma significativa — deve descrever uma versão mais específica do que o elemento é, não contradizê-lo.

Exemplos

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

Estes elementos não têm papel implícito ou explícito, pelo que 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 papel ARIA correspondente, e um <div> ou <span> simples mapeia para nenhum papel (ou para o papel genérico generic). Os leitores de ecrã não conseguem usar a descrição de forma significativa.

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

Estes elementos HTML carregam papéis semânticos incorporados, pelo que 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 papel implícito de img, e <button> tem um papel implícito de button. Os valores aria-roledescription fornecem descrições mais específicas destes papéis.

Correto: `aria-roledescription` em elementos com papel 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 sobre o que esse papel representa neste contexto específico.

Correção incorreta: Adicionar um papel 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 papel incorreto.

Necessita revisão: `aria-roledescription` em elementos com suporte de papel limitado

Alguns papéis têm suporte inconsistente nas tecnologias assistivas. Estes serão sinalizados como necessitando revisão manual.

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

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

</div>

O papel heading e o papel 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: