Verificação HTML: Um elemento com "role=listitem" deve estar contido num elemento com "role=list" ou "role=group", ou ser propriedade deste.

Sobre este problema HTML

A especificação WAI-ARIA define requisitos rigorosos de propriedade para determinados roles. O role listitem é um desses roles — deve ser “propriedade de” um elemento com role="list" ou role="group". “Propriedade de” significa que o listitem deve ser um filho DOM direto do elemento proprietário, ou explicitamente associado com ele através do atributo aria-owns.

Isto é importante porque os leitores de ecrã e outras tecnologias de apoio dependem da árvore de acessibilidade para transmitir estrutura aos utilizadores. Quando um leitor de ecrã encontra uma lista devidamente estruturada, anuncia algo como “lista, 3 itens” e permite ao utilizador navegar entre itens. Sem o role="list" pai, os itens individuais perdem o contexto de lista — os utilizadores não saberão quantos itens existem, onde a lista começa e termina, ou que os itens estão relacionados.

Na maioria dos casos, a solução mais simples e robusta é usar elementos nativos de lista HTML (<ul> ou <ol> com filhos <li>) em vez de roles ARIA. Os elementos nativos têm semântica incorporada que não requer atributos adicionais. Use roles ARIA apenas quando os elementos nativos não são viáveis — por exemplo, ao construir um componente personalizado onde o layout visual impede o uso de marcação de lista padrão.

Exemplos

Incorreto: `listitem` sem uma lista pai

Estes elementos listitem não estão contidos dentro de um pai role="list" ou role="group", por isso o validador reporta um erro.

<div role="listitem">Maçãs</div>
<div role="listitem">Bananas</div>
<div role="listitem">Cerejas</div>

Correto: envolver itens em `role="list"`

Adicionar um contentor pai com role="list" estabelece a relação de propriedade necessária.

<div role="list">
  <div role="listitem">Maçãs</div>
  <div role="listitem">Bananas</div>
  <div role="listitem">Cerejas</div>
</div>

Correto: usar elementos nativos de lista HTML

Os elementos nativos <ul> e <li> carregam implicitamente os roles list e listitem sem quaisquer atributos ARIA. Esta é a abordagem preferida.

<ul>
  <li>Maçãs</li>
  <li>Bananas</li>
  <li>Cerejas</li>
</ul>

Correto: usar `role="group"` para sublistas aninhadas

O contentor role="group" é apropriado para agrupar um subconjunto de itens de lista dentro de uma lista maior, tal como uma sublista aninhada.

<div role="list">
  <div role="listitem">Frutas
    <div role="group">
      <div role="listitem">Maçãs</div>
      <div role="listitem">Bananas</div>
    </div>
  </div>
  <div role="listitem">Vegetais
    <div role="group">
      <div role="listitem">Cenouras</div>
      <div role="listitem">Ervilhas</div>
    </div>
  </div>
</div>

Note que role="group" deve ele próprio estar aninhado dentro de um role="list" — não substitui o contentor de lista de nível superior, mas serve como um mecanismo de agrupamento intermédio dentro de um.

Correto: usar `aria-owns` para propriedade não-descendente

Se a estrutura DOM impedir você de aninhar os itens diretamente dentro do contentor da lista, pode usar aria-owns para estabelecer a relação programaticamente.

<div role="list" aria-owns="item-1 item-2 item-3"></div>

<!-- Estes itens vivem noutro lugar no DOM -->

<div role="listitem" id="item-1">Maçãs</div>
<div role="listitem" id="item-2">Bananas</div>
<div role="listitem" id="item-3">Cerejas</div>

Esta abordagem deve ser usada com moderação, pois pode criar confusão se a ordem visual não corresponder à ordem da árvore de acessibilidade. Sempre que possível, reestruture o seu HTML para que os itens sejam descendentes reais do contentor da lista.