Quando usar aria-label, aria-labelledby, aria-describedby ou simplesmente texto visível, com 20 trechos de antes e depois, erros comuns e um verificador de nome acessível.
Use aria-label apenas quando um elemento não tem nenhum texto visível que o nomeie, como um botão só com ícone: <button aria-label="Close dialog">. Se um texto visível já o nomeia, confie nele ou aponte aria-labelledby para ele. aria-describedby acrescenta uma ajuda extra, lida depois do nome. Os rótulos nativos do HTML sempre vêm primeiro.
Qual recurso de nomeação usar
Todo botão, link, campo e landmark precisa de um nome acessível, a frase curta que a tecnologia assistiva fala quando o foco chega ali. Esta página mostra como esse nome é calculado, vinte padrões com problema ao lado das versões corrigidas e um verificador que lê um trecho colado e informa o nome que ele receberia.
aria-label guarda o nome como uma string dentro do atributo. aria-labelledby aponta para um ou mais ids de elementos e monta o nome a partir do texto deles, então o nome sempre corresponde ao que os usuários que enxergam veem. Quando os dois estão presentes, aria-labelledby vence.
Sim. Na maioria dos controles o valor de aria-label se sobrepõe ao conteúdo de texto, então um botão que mostra Comprar com aria-label="Add to basket" é anunciado como Add to basket. Essa diferença confunde quem usa controle por voz e quebra o critério WCAG 2.5.3 Label in Name.
Use para informações de apoio que não são o nome: uma regra de senha, uma dica de formato ou uma mensagem de erro. Os leitores de tela geralmente leem a descrição depois do nome e do papel, muitas vezes após uma pequena pausa, e alguns usuários desativam as descrições.
Só se a div tiver um role que permita nomeação, como role="region" ou role="dialog". Em uma div ou span genérica, o ARIA proíbe a nomeação e a maioria dos leitores de tela ignora o atributo.
Não. As imagens recebem o nome do atributo alt. Use alt="" para imagens decorativas, assim elas são puladas. aria-label em um img funciona, mas não acrescenta nada que alt não faça.
Percorra esta lista de cima para baixo e pare na primeira opção que servir. O texto visível vem primeiro porque atende quem enxerga, quem usa leitor de tela e quem usa controle por voz com uma única string.
As quatro formas de dar um nome ou uma descrição a um elemento
Cada trecho mostra o padrão com problema, a correção e, aproximadamente, o que um leitor de tela fala depois da correção. Os anúncios variam conforme o produto e as configurações.
Sem nome, o botão normalmente é anunciado apenas como botão. Oculte o desenho para que ele não seja lido como uma imagem sem rótulo. Depois da correção, normalmente é anunciado como: Fechar, botão.
Um link vazio muitas vezes é lido como a sua URL, letra por letra em algumas configurações. Depois da correção, normalmente é anunciado como: Nossa loja no Instagram, link.
Um texto real em um span visualmente oculto sobrevive às ferramentas de tradução, que tendem a pular valores de atributos. Depois da correção, normalmente é anunciado como: Carrinho, 3 itens, link.
Com dois elementos nav sem nome, a lista de landmarks mostra navegação duas vezes e ninguém consegue distingui-los. Depois da correção, normalmente é anunciado como: Principal, navegação.
O texto do placeholder é um nome reserva fraco e some assim que a pessoa digita. Depois da correção, normalmente é anunciado como: Pesquisar produtos, campo de busca.
Um elemento label de verdade também torna a legenda clicável, o que aumenta a área de toque. Depois da correção, normalmente é anunciado como: E-mail, campo de edição.
As descrições são unidas na ordem em que os ids são listados. Depois da correção, normalmente é anunciado como: Senha, campo de edição seguro, entrada inválida, Pelo menos 12 caracteres, Muito curta....
O legend nomeia o grupo, então cada opção faz sentido sozinha. Depois da correção, normalmente é anunciado como: Velocidade de entrega, grupo, Padrão, botão de opção, 1 de 2.
Apontar para o título visível mantém o título falado e o exibido idênticos. Abra com showModal() para ter um modal de verdade. Depois da correção, normalmente é anunciado como: Excluir projeto?, diálogo, Isso remove todas as 14 páginas..
Mantenha o nome fixo e deixe o estado mudar. Não troque também o rótulo para Desfazer negrito. Depois da correção, normalmente é anunciado como: Negrito, botão de alternância, pressionado.
Mudar o rótulo e um estado pressionado ao mesmo tempo soa como uma dupla negação. Depois da correção, normalmente é anunciado como: Silenciar, botão de alternância, não pressionado.
O script precisa alternar aria-expanded e o atributo hidden juntos. Depois da correção, normalmente é anunciado como: Produtos, botão, recolhido.
Uma div clicável não recebe foco nem é anunciada como controle. Depois da correção, normalmente é anunciado como: Menu, botão, recolhido.
Escreva o que a imagem conta ao leitor. Um alt vazio marca a decoração para que ela seja pulada. Depois da correção, normalmente é anunciado como: As vendas subiram de 40 para 65 pedidos por semana em maio, imagem.
role=img transforma o SVG em um único objeto em vez de uma árvore de formas. Depois da correção, normalmente é anunciado como: Northgate Bakery, imagem.
Uma legenda visível nomeia a tabela para todos. Use aria-labelledby só quando o título fica fora dela. Depois da correção, normalmente é anunciado como: Horário de funcionamento, tabela, 2 colunas, 8 linhas.
A região precisa existir antes de o texto mudar, senão muitos leitores perdem a atualização. Depois da correção, normalmente é anunciado como: Salvo (falado sem mover o foco).
aria-roledescription muda o papel falado. Use com moderação e nunca em elementos genéricos. Depois da correção, normalmente é anunciado como: Fotos de clientes, carrossel.
Um texto de link único ajuda todos que percorrem uma lista de links. Começar com as palavras visíveis mantém o Label in Name intacto. Depois da correção, normalmente é anunciado como: Leia mais sobre o horário de inverno, link.
Quem diz clicar em Enviar no controle por voz precisa acertar este botão, então a palavra visível precisa estar no nome. Depois da correção, normalmente é anunciado como: Enviar, botão.
Erros encontrados em auditorias e suas correções
Confira os nomes antes de publicar
Cole um trecho. O verificador analisa o código no seu navegador sem executar nenhum script, encontra o primeiro elemento interativo ou nomeado e calcula um nome usando uma versão reduzida da ordem oficial. Ele pula várias etapas da especificação, então trate o resultado como uma dica rápida e confirme nas ferramentas de desenvolvedor ou em um leitor de tela.
Botão de ícone
Botão de ícone corrigido
Campo com rótulo
Rótulo divergente
Diálogo com labelledby
Trecho HTML
Nenhum botão, link, campo, landmark, imagem ou tabela encontrado no trecho.
Elemento
Nome calculado
(vazio)
Origem do nome
Avisos
Nenhum encontrado por esta verificação simplificada.
elemento label
conteúdo de texto
title do svg
title (reserva fraca)
placeholder (reserva fraca)
aria-labelledby aponta para o id inexistente "{id}".
aria-label em uma div ou span sem role é ignorado pela maioria dos leitores de tela.
A imagem não tem atributo alt.
O placeholder é o único nome. Adicione um rótulo.
Nenhum nome acessível encontrado.
O texto visível "{visible}" não está no início do nome (WCAG 2.5.3 Label in Name).
O nome termina com uma palavra de papel, então o papel será falado duas vezes.
O próprio elemento está com aria-hidden.
Comece grátis · Sem cartão de crédito