Uma boa busca dentro de uma página combina três elementos. Ela informa quantos resultados existem, indica qual deles está ativo e ajuda a localizar o trecho no texto. A CSS Custom Highlight API pode pintar as ocorrências sem inserir elementos extras no HTML do artigo. A marcação visual complementa os controles de navegação e a lista de resultados. Desenhe primeiro como a pessoa encontra e percorre o conteúdo. Depois use o destaque para reduzir o esforço de reconhecer a palavra na linha certa.
Delimite o que a busca encontra
Imagine um manual de uso de uma biblioteca de componentes. A pessoa quer encontrar a palavra “seleção” na página sobre tabelas. O termo aparece em títulos, parágrafos, exemplos e no menu lateral. Se a busca contar tudo que o navegador exibe, o resultado pode incluir itens da navegação sem relação com a tarefa. Delimite a área e indique o escopo no rótulo do campo, como “Buscar neste guia”. Diferencie essa ferramenta da busca geral do site pela posição e pela descrição.
Planeje como tratar texto oculto em abas, acordeões ou exemplos recolhidos. É possível restringir a busca ao conteúdo aberto e dizer isso perto do campo. Se a busca incluir seções fechadas, o botão de avançar precisa revelar a seção ou levar a uma visualização que mostre o trecho. Conte as ocorrências que a pessoa consegue alcançar. Uma contagem maior que a quantidade navegável cria a impressão de que parte dos resultados desapareceu.
Dê tratamentos diferentes ao conjunto e ao item ativo
Escolha uma aparência suave para as ocorrências e uma marca mais evidente para o item em leitura. Teste o fundo e a cor do texto juntos. Uma mancha clara em texto claro pode reduzir a legibilidade no tema escuro. Uma decoração mais marcada no item ativo, acompanhada da indicação “Resultado 2 de 7”, ajuda a distinguir o estado mesmo quando a diferença entre as duas cores é difícil de perceber. Preserve o estilo de links e indique o foco no controle que está recebendo o teclado.
Faça uma amostra com uma ocorrência no título, outra dentro de um link e uma palavra que ocupe duas linhas. Em uma página com seleção manual de texto, experimente arrastar o cursor sobre um termo já destacado. Verifique se ainda fica claro qual faixa foi selecionada para copiar. A cor que funciona num parágrafo corrido pode precisar de ajuste nos títulos ou em superfícies já coloridas. O guia de contraste em sites ajuda a revisar essas combinações.
Use a API para pintar intervalos de texto
A documentação da MDN sobre CSS Custom Highlight descreve um fluxo em que o JavaScript cria intervalos com Range, agrupa as ocorrências com Highlight e registra o grupo em CSS.highlights. O estilo de cada conjunto é definido pelo pseudoelemento ::highlight(). Você pode separar o resultado ativo do restante para desenhar tratamentos distintos. Aplique apenas propriedades compatíveis com o pseudoelemento. A API oferece recursos de pintura, como cor de texto e de fundo, enquanto a geometria do parágrafo continua a mesma.
O Web Features Explorer registra o recurso entre as áreas de Interop 2026. Consulte a cobertura necessária para o projeto e teste a combinação de propriedades no navegador. A API cuida da apresentação dos intervalos que a aplicação já identificou. A lógica de busca, o anúncio dos resultados e o deslocamento até o trecho continuam sendo parte do produto. Preserve contagem, controles e trechos em uma lista quando a pintura personalizada estiver indisponível.
Combine a navegação com o foco
Ofereça botões “Anterior” e “Próximo” perto do campo e indique o progresso. Se houver sete ocorrências, defina se a última leva de volta à primeira ou se o botão fica indisponível ao chegar ao fim. Uma escolha explícita melhora o teste e facilita escrever a mensagem de estado. Quando a pessoa pressiona “Próximo”, pode ser melhor manter o foco no botão e apenas trazer o trecho para a área visível. Ela consegue avançar várias vezes sem buscar novamente os controles.
Em uma lista de resultados, um link que leva a uma seção pode justificar levar a pessoa ao título ou ao destino escolhido. Esse movimento tem uma finalidade diferente de simplesmente avançar dentro da busca. Confira com teclado e leitor de tela se a contagem muda de modo compreensível. Evite anunciar cada oscilação enquanto a pessoa ainda digita. Atualize a mensagem em um momento que dê tempo de entender o resultado. O artigo sobre foco visível em interfaces complementa a revisão da navegação.
Teste palavras reais com acentos e estilos
Em português, quem digita “selecao” pode esperar encontrar “seleção”. Defina se a busca ignora acentos, diferenças entre maiúsculas e minúsculas ou apenas espaços extras nas pontas. A comparação pode usar um texto normalizado. A aplicação precisa mapear cada resultado de volta ao intervalo original antes de pintar. Isso evita que uma transformação de caracteres desloque o destaque e cubra parte de outra palavra.
Teste uma expressão dividida por um trecho em negrito ou um link. O texto parece contínuo na tela, mas pode estar distribuído entre nós diferentes. Uma busca que verifica cada nó isoladamente pode encontrar “modo” e “escuro” e perder “modo escuro”. Decida se o produto deve aceitar a expressão inteira e entregue esse caso junto com o protótipo. Inclua ainda um termo repetido na mesma linha, um trecho com acentos e uma palavra que é parte de outra. A pessoa precisa entender a regra pelo resultado que vê.
Trate a ausência de resultados como parte da busca
Ao apagar a consulta, retire os destaques e limpe a contagem. Quando houver zero ocorrências, mostre uma resposta curta que reflita o escopo, como “Nenhum resultado neste guia”. Sugira uma tentativa concreta se ela couber, por exemplo buscar uma palavra menor. Quando uma atualização do conteúdo remover o resultado ativo, recalcule a lista e reposicione o contador. Isso evita que a interface informe uma ocorrência que já saiu da página.
Durante o ensaio, pergunte a alguém em qual seção aparece uma expressão e peça que encontre sua segunda ocorrência. Faça uma rodada com as marcas visuais e outra com a pintura desativada. Observe se a pessoa consegue terminar a tarefa nos dois casos, usando o contador, os trechos e os controles. Em uma tela estreita, confira se a barra da busca encobre justamente a linha encontrada. A combinação de rolagem, altura da barra e texto ampliado merece uma captura no arquivo de entrega.
Quando basta mostrar um trecho com contexto?
Se a consulta percorre páginas diferentes, a lista pode apresentar trechos curtos com título e seção antes de abrir qualquer documento. Se a pessoa já está lendo um texto e quer localizar ocorrências nele, o destaque no corpo reduz a distância entre resultado e contexto. Em ambos os casos, mantenha um trecho que permita reconhecer a frase. Uma palavra marcada sozinha pode coincidir com a consulta e ainda esconder o sentido que levou a pessoa a buscá-la. O teste final é encontrar a passagem certa, voltar ao controle e percorrer outra ocorrência sem perder o lugar.
Entregue um exemplo com resultados próximos
Coloque no protótipo duas ocorrências no mesmo parágrafo e outra no parágrafo seguinte. Se a rolagem já posicionou a primeira no centro da tela, avançar para a segunda pode exigir somente uma mudança de marcação e de contador. Saltar novamente a página pode dificultar a comparação entre as duas frases. Ao chegar à ocorrência seguinte, confira se o cabeçalho do trecho permanece visível. Esse cenário ajuda a separar a decisão de atualizar o estado da decisão de mover a janela.
Se a barra tiver um botão para limpar a consulta, verifique onde o foco fica depois de acioná-lo. Voltar ao campo permite iniciar outra busca imediatamente e evita deixar o teclado em um controle que acabou de desaparecer.