Uma landing page criada por IA pode mostrar três botões chamados “Saiba mais”, um ícone sem texto para fechar o menu e um CTA cujo nome anunciado pelo leitor de tela não corresponde ao rótulo visível. Todos parecem clicáveis. Nem todos dizem o que fazem.

O nome acessível é o texto que o navegador expõe para identificar um controle. Ele permite que uma pessoa encontre um link numa lista do leitor de tela, entenda um botão sem enxergar o ícone e acione o controle por voz usando as palavras mostradas na tela.

Este guia ajuda a inventariar links e botões, conferir o nome calculado pelo navegador, corrigir a fonte e retestar a mesma versão que chegou à URL pública.

O que um nome acessível precisa resolver

A orientação da W3C sobre nomes e descrições separa duas tarefas. O nome identifica o elemento e comunica sua finalidade. A descrição acrescenta contexto quando o nome curto não basta.

Um bom nome responde à pergunta que surge quando o controle aparece isolado:

Qual ação este botão executa?
Para onde este link leva?
Qual item este controle altera?

Na WCAG 2.2, o critério 2.4.4 sobre propósito do link pede que a finalidade possa ser determinada pelo texto do link ou por um contexto programaticamente relacionado. O critério 2.5.3 sobre rótulo no nome exige que o nome de um controle contenha o texto apresentado visualmente.

Isso não significa escrever frases longas em cada CTA. Significa dar a cada controle uma identificação curta, previsível e compatível com o que a pessoa vê.

Comece pelo inventário da tarefa principal

Escolha uma rota e uma tarefa, como abrir os planos, comparar opções e enviar contato. Liste todos os controles usados nesse caminho.

Registre:

Elemento Texto visível Nome calculado Função Destino ou efeito
link Ver preços Ver preços navegar /precos
botão menu por ícone sem nome abrir navegação móvel
link Saiba mais Saiba mais navegar /integracoes

Inclua header, menu responsivo, cards, carrossel, formulário, modal, compartilhamento e rodapé. Controles repetidos merecem atenção porque um nome genérico costuma esconder destinos diferentes.

O guia de navegação por teclado ajuda a percorrer a página na mesma ordem em que esses elementos recebem foco.

O nome não corrige uma função errada.

Use link quando o controle navega para outro endereço, arquivo ou ponto da página:

<a href="/precos">Ver preços</a>

Use botão quando o controle executa uma ação na interface:

<button type="button">Abrir filtros</button>

O padrão de links da W3C recomenda o elemento <a> com href. Adicionar role="link" a uma div não cria navegação, menu de contexto nem comportamento de teclado. O padrão de botões também diferencia uma ação de um destino.

Se o site usa div com onclick, corrija o elemento antes de ajustar ARIA. O artigo sobre HTML semântico em sites criados por IA cobre a revisão estrutural completa.

Check 2: veja o nome que o navegador calculou

Não deduza o resultado apenas lendo JSX, HTML ou um componente. Abra as ferramentas de desenvolvedor, selecione o elemento e confira a árvore de acessibilidade ou a área de propriedades de acessibilidade.

Compare:

  • função exposta, como link ou botão;
  • nome acessível calculado;
  • origem do nome, como conteúdo, aria-label ou aria-labelledby;
  • estado relevante, como expandido, pressionado ou desabilitado;
  • descrição, quando existir.

Repita no HTML produzido pela build. Um componente pode substituir texto, aplicar atributos em outra ordem ou esconder o conteúdo que deveria nomear o controle.

Depois escute o controle com um leitor de tela. O painel mostra a árvore; a tecnologia assistiva confirma a experiência. Use o roteiro de teste com leitor de tela para validar a tarefa completa.

Check 3: faça o texto visível participar do nome

Considere este botão:

<button aria-label="Enviar formulário">Quero uma demonstração</button>

O aria-label substitui o nome derivado do conteúdo. Uma pessoa que tenta acionar “Quero uma demonstração” por voz pode não encontrar o botão, porque o navegador o conhece como “Enviar formulário”.

Na maioria dos casos, o texto já resolve:

<button type="submit">Quero uma demonstração</button>

Se a interface precisa de contexto adicional, preserve o rótulo visível no começo do nome:

<button aria-label="Quero uma demonstração do plano Equipe">Quero uma demonstração</button>

Use essa expansão somente quando o contexto realmente distingue controles semelhantes. Não acrescente palavras ocultas por rotina.

Uma grade com vários links “Saiba mais” força a pessoa a reconstruir o contexto de cada card. Leitores de tela também podem listar links fora da ordem do conteúdo ao redor.

Prefira nomes que identifiquem o destino:

<a href="/recursos/dominios">Como funcionam os domínios próprios</a>
<a href="/recursos/analytics">Como acompanhar acessos</a>

Se o design exige um rótulo curto repetido, associe o título do card sem destruir o texto visível:

<h3 id="dominios">Domínios próprios</h3>
<a href="/recursos/dominios" aria-labelledby="saiba-dominios dominios">
  <span id="saiba-dominios">Saiba mais</span>
</a>

Teste o nome calculado. A ordem das referências em aria-labelledby afeta o resultado anunciado. Uma copy específica costuma ser mais simples de manter do que uma rede de IDs.

Confira ainda se links com nomes iguais levam ao mesmo destino. Se “Ver planos” abre preços num card e suporte em outro, corrija o conteúdo e a arquitetura antes da marcação.

Check 5: nomeie controles que mostram apenas ícones

Um botão com SVG decorativo pode ficar sem nome:

<button type="button">
  <svg aria-hidden="true">...</svg>
</button>

Forneça a função no controle:

<button type="button" aria-label="Fechar menu">
  <svg aria-hidden="true">...</svg>
</button>

O nome deve descrever a ação, não a aparência. Use “Fechar menu”, não “X”. Use “Reproduzir vídeo”, não “Triângulo”.

Para um botão que alterna estado, escolha um contrato coerente. Você pode manter o nome e comunicar estado com aria-pressed, ou mudar o nome de “Ativar som” para “Desativar som” conforme a ação disponível. Não misture os dois modelos sem testar a fala resultante.

Ícones informativos fora de controles seguem outra regra. O guia de texto alternativo para imagens ajuda a separar conteúdo, função e decoração.

Check 6: não use descrição para remendar um nome vazio

aria-describedby complementa o nome. Ele não substitui a identificação principal.

<button type="button" aria-describedby="prazo">Publicar</button>
<p id="prazo">A nova versão pode levar alguns instantes para ficar ativa.</p>

O botão continua chamado “Publicar”. A descrição comunica o que a pessoa precisa saber antes da ação.

Evite colocar instruções inteiras em aria-label. Nomes longos atrasam a navegação e escondem a diferença entre identificação e ajuda. Se o texto precisa ficar disponível para todos, mostre-o na interface e relacione-o como descrição quando necessário.

Check 7: teste estados e conteúdo que mudam

Agentes costumam gerar componentes cujo rótulo visual muda sem atualizar o nome programático, ou o contrário.

Teste:

  • menu fechado e aberto;
  • modal antes e depois de abrir;
  • botão de play e pause;
  • favoritar e remover favorito;
  • mostrar e ocultar senha;
  • filtros aplicados e limpos;
  • envio, carregamento, sucesso e erro.

Em cada estado, confira nome, função, valor e resultado. Um nome correto no carregamento inicial não basta se ele fica desatualizado depois do clique.

Automação encontra ausências, não decide a melhor copy

Linters e scanners podem apontar:

  • controle sem nome;
  • aria-labelledby que referencia um ID inexistente;
  • atributo incompatível com a função;
  • link sem conteúdo discernível;
  • botão de ícone sem alternativa;
  • IDs duplicados.

Eles não sabem se “Continuar” leva ao checkout esperado, se dois links iguais têm destinos incompatíveis ou se a distinção entre planos faz sentido para o visitante.

Combine três evidências:

  1. scanner para encontrar padrões;
  2. árvore de acessibilidade para conferir o cálculo;
  3. teclado, voz ou leitor de tela para concluir a tarefa.

Prompt copiável para o agente

Revise os nomes acessíveis de links e botões desta landing page.


Escopo:
- fonte e commit: [referência]
- rota ou arquivo: [caminho]
- tarefa principal: [objetivo]
- copy e destinos aprovados: [referência]


1. Inventarie links, botões, CTAs e controles de ícone.
2. Registre texto visível, função, nome acessível calculado, destino ou efeito.
3. Marque nomes ausentes, genéricos, duplicados ou incompatíveis com o rótulo visível.
4. Prefira elementos nativos e nomes derivados do conteúdo visível.
5. Preserve tracking, destino, copy aprovada, estilo e comportamento.
6. Mostre o plano antes de editar quando a correção exigir nova copy ou outro destino.
7. Depois da correção, rode os checks e entregue o inventário atualizado.

Uma instrução para “adicionar aria-label em tudo” piora a página. Peça evidência do nome calculado e a menor correção para cada controle.

Publique e reteste a URL real

No Site no Ar, a documentação de Publicação define public/ como o conteúdo servido. Alterações salvas na Session ainda não estão no ar. O agente precisa chamar deploy e acompanhar deploy_status até um estado final.

Depois do sucesso:

  • abra a URL publicada;
  • confira a versão ou mudança esperada;
  • percorra os links e botões com teclado;
  • inspecione os nomes no HTML servido;
  • teste menu, modal e formulário nas larguras relevantes;
  • confirme que destinos, analytics e envio continuam funcionando.

Se encontrar uma diferença, corrija a fonte e republique o mesmo Site. Preserve a URL e registre qual Version recebeu o ajuste.

O resultado esperado não é uma coleção de atributos ARIA. É uma tarefa em que cada controle diz o que faz, corresponde ao que aparece na tela e continua correto na versão pública.