Como criar tooltips acessíveis em uma landing page feita por IA

Tooltips parecem uma solução econômica para explicar ícones, siglas e campos. Também são fáceis de perder. Um texto que só aparece no hover não existe para toque, pode desaparecer antes da leitura e costuma cobrir exatamente o conteúdo ampliado que a pessoa queria ver.

Antes de criar o componente, decida se a informação deveria estar visível. Quando o tooltip for adequado, mantenha foco no elemento que o acionou, relacione a descrição com aria-describedby e ofereça o mesmo conteúdo por foco e ponteiro. Este guia cobre o contrato completo e o teste da versão publicada.

Prefira texto visível quando a informação for necessária

Um tooltip deve acrescentar uma descrição curta. Ele não deve carregar instruções essenciais, validação, preço, termos, atalhos obrigatórios ou qualquer dado necessário para concluir a tarefa.

Transforme a informação em texto visível quando:

• a pessoa precisa conhecê-la antes de agir;
• o conteúdo tem mais de uma frase curta;
• há link, botão, campo ou outro elemento interativo dentro dele;
• a explicação precisa permanecer para comparação;
• a mesma dúvida aparece para a maioria das pessoas;
• o texto corrige um rótulo que já é ambíguo.

Um ícone sem nome continua sem nome mesmo que ganhe um tooltip visual. Dê primeiro um nome acessível ao controle. A descrição é informação complementar. O guia sobre nomes acessíveis de links e botões ajuda a separar as duas funções.

Se o conteúdo contém ações, use um popover ou diálogo não modal com comportamento próprio. O padrão de tooltip da W3C deixa claro que o tooltip não recebe foco. Um popup com elementos focáveis já é outro componente.

Não dependa do atributo title

O atributo title pode gerar um tooltip controlado pelo navegador, mas não oferece um contrato consistente para teclado, toque, tempo de abertura, posição ou apresentação. O HTML Standard desencoraja depender dele porque muitos agentes de usuário não expõem o conteúdo de forma acessível.

Também não duplique a mesma frase em title, aria-label e texto escondido. Um leitor de tela pode anunciar informação repetida ou calcular um nome diferente do rótulo visível.

Use HTML visível para a mensagem essencial. Para uma descrição curta associada a um controle, use um elemento com ID e aria-describedby:

<button type="button" aria-label="Copiar URL" aria-describedby="dica-copiar">
  <svg aria-hidden="true">...</svg>
</button>
<div id="dica-copiar" role="tooltip" hidden>Copiar URL pública</div>

O botão tem nome próprio. O tooltip acrescenta uma descrição. aria-describedby fica no elemento descrito, não no balão.

Abra por foco e ponteiro

Se o tooltip aparece ao passar o mouse, ele também deve aparecer quando o acionador recebe foco pelo teclado. Toque não tem hover persistente, então a interface precisa continuar compreensível sem o balão.

Mantenha o foco no acionador. Não chame focus() no tooltip e não adicione tabindex="0" ao contêiner. O padrão da W3C define o tooltip como descrição sem foco próprio.

Gerencie as entradas separadamente:

• focus mostra e blur pode esconder;
• entrada do ponteiro mostra;
• saída do ponteiro só esconde quando ele deixou tanto o acionador quanto o tooltip;
• Escape fecha sem mover foco;
• remoção do elemento ou mudança de contexto cancela timers pendentes.

Um pequeno atraso de abertura pode evitar ruído enquanto o ponteiro atravessa a página. Não use tempo máximo para fechar. Algumas pessoas precisam ampliar, mover o ponteiro ou reler.

Cumpra dispensável, hoverable e persistente

O critério 1.4.13 da WCAG 2.2 cobre conteúdo adicional que aparece por hover ou foco. Um tooltip customizado precisa ser:

• dispensável sem mover o foco ou o ponteiro, normalmente com Escape, quando cobre conteúdo;
• hoverable, para que o ponteiro possa entrar no balão sem fazê-lo sumir;
• persistente até a pessoa sair, dispensar ou a informação perder a validade.

Posicione o balão sem cobrir o acionador. Teste com ponteiro grande e zoom. Se o conteúdo cobre outro controle, Escape precisa removê-lo mesmo quando o ponteiro continua sobre o acionador. Não reabra no mesmo instante por causa do hover ainda ativo. Espere uma saída e nova entrada ou outra mudança clara de estado.

Não feche quando o ponteiro atravessa um espaço de poucos pixels entre o acionador e o tooltip. Trate os dois como uma única área de permanência.

Relacione nome e descrição corretamente

O nome responde “o que é este controle?”. A descrição acrescenta contexto. Misturar os dois gera anúncios confusos.

Considere um botão de ícone para copiar a URL. O nome pode ser “Copiar URL”. A descrição pode dizer “Copia a URL pública para a área de transferência”. Não use aria-label="Copia a URL pública para a área de transferência" e repita a mesma frase no tooltip.

aria-describedby pode apontar para o elemento do tooltip antes de ele ficar visível. Isso mantém a relação disponível para tecnologia assistiva. Confirme o comportamento nos navegadores e leitores de tela suportados, pois anúncios de descrições dinâmicas variam conforme o momento em que o nó entra no DOM.

Não dê ao próprio tooltip um aria-label diferente do texto. Conforme a referência de tooltip do MDN, esse nome pode substituir o conteúdo usado como descrição e impedir que a frase visível seja anunciada.

Evite tooltips sobre elementos que não recebem foco

Texto estático, span e ícones decorativos não entram na ordem de teclado. Adicionar tabindex="0" a cada abreviação cria paradas extras e torna a página cansativa.

Para uma sigla, escreva o termo completo na primeira ocorrência ou use texto próximo. Para ajuda de formulário, associe instruções persistentes com aria-describedby. Para definição opcional extensa, use um botão “O que é isto?” que abra uma região ou um popover controlado.

Não envolva um botão em outro botão para acoplar um ícone de ajuda. Controles interativos aninhados geram foco e ativação imprevisíveis. Separe-os e dê nomes claros.

No celular, não faça o primeiro toque apenas abrir a dica e o segundo executar a ação sem indicar essa regra. O controle precisa cumprir sua ação principal. Se a explicação é necessária antes do toque, mantenha-a visível.

Posicione sem esconder foco ou conteúdo

O tooltip precisa acompanhar o acionador sem sair da viewport, cortar texto ou cobrir o indicador de foco. Bibliotecas de posicionamento ajudam com colisão, mas não decidem quando abrir, fechar ou anunciar.

Teste:

• acionadores nas quatro bordas da viewport;
• zoom de 200% e 400%;
• largura equivalente a 320 pixels CSS;
• texto traduzido ou maior que a demonstração;
• rolagem enquanto o tooltip está aberto;
• cabeçalhos fixos e contêineres com overflow;
• preferência de movimento reduzido.

Evite animações que atrasem o acesso ao texto. Uma transição curta de opacidade pode ser dispensável, mas o estado acessível e a visibilidade não devem ficar desencontrados. O guia de movimento reduzido ajuda a revisar a apresentação.

Não transforme tooltip em mensagem de status

Depois de copiar uma URL, a confirmação “URL copiada” é uma mensagem de status, não uma descrição permanente do botão. Um tooltip que muda de conteúdo pode não ser anunciado porque o foco continua no mesmo lugar.

Use uma região de status adequada para confirmar o resultado e mantenha o nome do botão estável. O artigo sobre mensagens de erro e status acessíveis mostra como separar instrução, erro e resultado assíncrono.

O mesmo vale para validação de formulário. Não esconda o erro num tooltip que some ao mover o ponteiro. Relacione a mensagem ao campo e preserve-a até a correção.

Teste uma matriz de entradas e saídas

Uma captura de tela não prova o comportamento. Registre pelo menos estes casos:

Com leitor de tela, escute o nome, a função e a descrição. Confirme que o texto não é repetido e que o controle continua operável. O guia de teste com leitor de tela ajuda a comparar o anúncio real com a árvore de acessibilidade.

Peça uma revisão com limites claros

Revise os tooltips desta landing page sem publicar ainda.

Escopo:
- fonte e commit: [referência]
- rotas: [lista]
- acionadores e descrições: [inventário]

Para cada item:
1. Confirme se a informação deveria ficar visível.
2. Separe nome acessível, descrição e mensagem de status.
3. Remova dependência do atributo title e de hover exclusivo.
4. Relacione o acionador ao tooltip com aria-describedby.
5. Preserve o foco no acionador e feche com Escape.
6. Garanta conteúdo dispensável, hoverable e persistente.
7. Teste teclado, ponteiro, toque, leitor de tela, zoom e bordas da viewport.
8. Preserve ações, analytics e conteúdo aprovado.

Entregue o inventário, o diff e a matriz de testes antes de publicar.

Esse pedido permite remover tooltips desnecessários em vez de apenas padronizar todos com mais JavaScript.

Reteste a URL final

Depois da aprovação, siga a documentação de Publicação: publique uma nova Version, acompanhe o deploy e abra a URL final. Repita a matriz depois que fontes, estilos e scripts terminarem de carregar.

Confira acionadores perto das bordas, páginas traduzidas e estados depois de navegação interna. Se a hidratação duplicar IDs, remover descrições ou deixar uma camada presa no body, corrija a fonte e republique o mesmo Site. O tooltip está pronto quando acrescenta contexto sem esconder a ação, o foco ou a informação principal.