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

Sobre esta regra de acessibilidade

Por que isto importa

O atributo aria-roledescription permite aos autores fornecer 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 conseguem 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 deficiências 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 sobre o papel é sem sentido ou está em falta, estes utilizadores perdem a capacidade de compreender o que é um elemento de 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 exige que para todos os componentes de interface de 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 funciona a regra

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

Falha: O elemento não tem papel algum (por exemplo, <div>, <span>, <p> sem um atributo role explícito). Estes elementos têm um papel genérico ou nenhum papel implícito, por isso aria-roledescription não tem nada para descrever.
Passa: 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 testes manuais para verificar se funcionam corretamente.

Como corrigir

Identifique elementos sinalizados pela regra — eles têm aria-roledescription mas nenhum papel 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, então:
- 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 de aria-roledescription refina significativamente o papel — 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, 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 papel ARIA correspondente, e um <div> ou <span> simples não mapeia para nenhum papel (ou para o papel genérico generic). Os leitores de ecrã não podem usar a descrição de forma significativa.

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

Estes elementos HTML carregam papéis 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 papel implícito de img, e <button> tem um papel implícito de button. Os valores de 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 de tecnologia assistiva. 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: