Gerador de FAQ Accordion HTML

FAQ accordion acessível com HTML semântico

Um FAQ em formato accordion é o padrão de interface em que cada pergunta colapsa em uma única linha e o visitante expande para revelar a resposta. O padrão mantém páginas longas escaneáveis, reduz o ruído visual acima da dobra e permite que o usuário pule direto para a dúvida que interessa. Até pouco tempo cada implementação dependia de JavaScript para alternar aria-expanded, gerenciar foco e animar o painel. Navegadores modernos trazem um elemento nativo que resolve quase tudo isso de graça: o par <details> + <summary> é totalmente acessível por teclado (Enter e Espaço alternam, Tab move o foco, o estado é anunciado por leitores de tela) e renderiza sem uma única linha de script.

Um bloco típico fica assim:

<details class="faq">
  <summary>Como instalo o pacote?</summary>
  <p>Rode <code>npm install acme</code> na raiz do projeto.</p>
</details>

Estilizando o marcador de disclosure

Por padrão o navegador desenha um pequeno triângulo ao lado do summary. Para escondê-lo use summary::-webkit-details-marker { display: none } no WebKit e summary { list-style: none } no Firefox, e em seguida adicione seu próprio SVG ou pseudo-elemento. Use o seletor details[open] para estilizar o estado aberto — rotacionar um chevron, mudar o fundo ou trocar a cor do texto para comunicar o estado.

Animando abrir e fechar

O <details> nativo abre instantaneamente, sem transição. Para animar, a alternativa mais estável é envolver a resposta em uma div interna, consultar scrollHeight no toggle e fazer transição em max-height. Uma spec futura (interest-target e o pseudo-elemento ::details-content) permitirá animação só com CSS, mas o suporte ainda é parcial em 2026.

Dados estruturados para rich results

Complemente a marcação com JSON-LD usando Schema.org FAQPage para que buscadores entendam a lista de Q&A:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "Como instalar?",
    "acceptedAnswer": { "@type": "Answer", "text": "Rode npm install acme." }
  }]
}
</script>

Ressalva importante: em agosto de 2023 o Google restringiu o rich snippet de FAQ na SERP apenas a domínios governamentais e de saúde com autoridade. Os dados estruturados continuam úteis para outros crawlers, assistentes de voz e busca interna, mas não conte mais com o destaque na SERP em um site comercial comum.

Perguntas frequentes

Devo usar <details> ou um accordion em JavaScript? Comece pelo <details>. Ele é acessível por padrão, menor, mais rápido e continua funcionando se o JS falhar. Só recorra a um componente de framework (Headless UI, Radix Accordion, Material UI) quando precisar de transições animadas, comportamento "um aberto por vez" ou tema profundamente customizado.

O schema de FAQ ainda ajuda no SEO? Indiretamente. O Google raramente mostra o rich result em sites não autoritativos hoje, mas o JSON-LD continua alimentando extração de entidades, ajuda em busca por voz e é consumido por Bing e outros buscadores.

Como abrir um painel e fechar os outros automaticamente? Dê a todos os <details> o mesmo atributo name — navegadores modernos passam a tratá-los como um grupo exclusivo, reproduzindo o comportamento clássico de accordion.

Posso deixar um painel aberto por padrão? Sim, basta adicionar o atributo booleano open no <details> desejado.