Acordeão: Regras e Exemplos de Divulgação Progressiva

Um acordeão é um conjunto agrupado de controles de divulgação rotulados que permite ao leitor revelar ou recolher conteúdo de apoio no mesmo local. Use-o para detalhes de referência opcionais, não para a resposta principal da página.

Este par renderizado demonstra a divulgação progressiva: os rótulos permanecem escaneáveis, um painel está aberto e ambas as respostas estão presentes no HTML da página, independentemente de o visitante interagir ou não.

Por que este elemento é importante

Divulgação progressiva significa mostrar as informações necessárias para a decisão atual enquanto mantém detalhes mais profundos ou menos comuns disponíveis sob demanda. Ajuda quando uma página atende leitores com diferentes níveis de conhecimento. Um cliente recorrente pode ignorar notas de implementação; um usuário de primeira viagem pode abri-las. O controle reduz a densidade visual sem excluir conteúdo ou forçar cada leitor a passar por todas as exceções.

A mesma conveniência pode se tornar ocultação. Um leitor que procura uma resposta direta, chega à página e vê oito rótulos fechados precisa adivinhar qual painel a contém e realizar uma ação extra. No celular, abrir e fechar repetidamente também move o conteúdo pela janela de visualização. O acordeão, portanto, só merece seu lugar quando a maioria dos leitores consegue concluir sua tarefa principal sem abrir todos os painéis.

A extraibilidade por máquinas adiciona um teste mais rigoroso. Extraibilidade é a capacidade de motores de busca, sistemas de resposta de IA, analisadores e ferramentas assistivas receberem o texto e preservarem sua relação com seu rótulo. Cada resposta deve estar presente no Modelo de Objeto de Documento (DOM) inicial renderizado no servidor, a representação estruturada da página no navegador. O CSS pode recolher visualmente um painel presente; o JavaScript não deve buscar ou fabricar a resposta apenas após um clique. Um rastreador pode nunca clicar, executar o código do cliente ou aguardar uma requisição secundária.

Siga as regras de escrita de elementos antes de usar este padrão. Se o propósito do conteúdo corresponder a um elemento tipificado mais específico, esse elemento tem precedência. Um acordeão pode conter conteúdo de apoio permitido, mas não deve renomear ou achatar um aviso, comparação, definição ou sequência de etapas apenas para tornar a página mais curta.

Quando usar

Use um acordeão quando todas as quatro condições forem verdadeiras:

1. O leitor consegue prever o conteúdo do painel a partir do seu rótulo.
2. O conteúdo é útil para um subconjunto de leitores, em vez de necessário para todos.
3. Todo o conteúdo do painel é enviado no HTML inicial e permanece acessível sem um dispositivo apontador.
4. Recolher melhora materialmente a escaneabilidade na janela de visualização esperada.

Bons candidatos incluem detalhes opcionais de compatibilidade, ramificações incomuns de erro, definições de apoio, cláusulas secundárias de políticas, exceções de envio e respostas de referência agrupadas. Um acordeão também pode funcionar para uma grande coleção de FAQ quando cada pergunta permanece visível e cada resposta é autocontida.

Quase-acertos expõem o uso inadequado mais comum:

• Uma página curta com duas seções breves: títulos e parágrafos visíveis são mais rápidos de escanear do que dois controles.
• Um artigo longo feito para parecer mais curto: recolher dez seções substanciais reduz a altura percebida, mas aumenta a interação e oculta o escopo da página.
• Informações primárias do produto: preço, disponibilidade, limitações de material, termos de cancelamento e especificações principais influenciam a decisão e não devem depender de expansão.
• Um procedimento sequencial: etapas exigem ordem e contexto. Um painel fechado pode fazer o leitor pular um pré-requisito ou executar etapas fora de ordem.
• Uma comparação: leitores precisam de visibilidade simultânea dos mesmos critérios. Painéis separados forçam comparação baseada em memória.
• Um aviso de segurança ou qualificação legal: a consequência de perdê-lo é maior do que o benefício visual de ocultá-lo.
• Um substituto de navegação: um acordeão não é um sumário. Ele revela conteúdo no mesmo local, em vez de mover para seções estáveis da página.

Quando estiver em dúvida, publique o conteúdo visivelmente. Rolagem extra geralmente é recuperável; uma resposta perdida, restrição não divulgada ou nó DOM indisponível não é.

Onde posicionar

Coloque o acordeão depois que a página tiver entregue sua resposta direta e explicação visível suficiente para o leitor entender o que o grupo contém. Introduza-o com um H2 e uma frase de escopo. O grupo então se comporta como uma camada de referência suplementar dentro dessa seção.

Regras exatas de posicionamento:

• Coloque-o após a explicação visível que ele qualifica, nunca entre uma afirmação e a evidência que a suporta.
• Mantenha-o dentro da seção pai cujo assunto rotula cada item. Se os rótulos fizerem sentido apenas com um título ausente, o grupo está mal posicionado.
• Coloque um acordeão de detalhes do produto após o valor central, contexto de preço e condições de compra; coloque ramificações de resolução de problemas após o diagnóstico compartilhado e a primeira verificação mais segura.
• Mantenha um acordeão de FAQ de fechamento após a conclusão principal e antes da próxima ação final, desde que responda a perguntas residuais em vez de repetidas.
• Dê ao grupo uma âncora de seção estável quando os leitores puderem criar links para ele. Links para painéis individuais são opcionais, mas se fornecidos, devem abrir e focar o item correto.

Um acordeão não pode ficar diretamente ao lado de abas, um segundo acordeão ou uma tabela de comparação densa. Padrões de interação adjacentes fazem os leitores escolherem um mecanismo antes de poderem escolher o conteúdo. Não pode interromper etapas ordenadas, separar um aviso de sua consequência, ou ficar entre o preço de um produto e as condições que regem esse preço. Não coloque um banner promocional dentro do grupo ou imediatamente após cada painel; a promoção compete com a tarefa de referência e faz a expansão parecer uma armadilha de vendas.

Anatomia

A anatomia rotulada contém sete partes:

1. Título do grupo: nomeia o assunto compartilhado na hierarquia do documento circundante.
2. Rótulo do item: prevê o conteúdo específico sem rótulos vagos como “Saiba mais”.
3. Controle de divulgação: um summary nativo ou um button que recebe foco de teclado e alterna um painel.
4. Indicador de estado: comunica aberto ou fechado visualmente enquanto o estado programático é exposto através de semântica nativa ou aria-expanded.
5. Painel: contém a resposta ou detalhe de referência e permanece no DOM inicial.
6. Relação de controle: semântica nativa <details>/<summary> ou aria-controls mais IDs correspondentes associam cada controle a exatamente um painel.
7. Limite do item: espaçamento, borda e agrupamento DOM mantêm um rótulo de parecer controlar uma resposta vizinha.

O chevron visível é decorativo. Oculte-o da tecnologia assistiva porque o estado expandido já fornece o significado. A rotação sozinha não pode comunicar estado; a semântica do controle deve fazer isso.

Exemplos de design

Cada variante usa os mesmos campos e regra de presença no DOM. Escolha a variante pela tarefa de leitura, não pela decoração.

Grupo padrão de abertura única

Abrir um item fecha o item anteriormente aberto. Use isto quando os painéis são alternativas e os leitores normalmente precisam de um de cada vez, como sintomas de resolução de problemas mutuamente exclusivos.

Grupo de referência multi-abertura

Os leitores podem manter vários painéis abertos. Use isto quando podem comparar ou combinar detalhes suplementares, como tipos de arquivo suportados e permissões de conta. Se a comparação simultânea for a tarefa principal, use uma tabela visível.

Orientação de abertura padrão

Abra o primeiro item ou o mais comum no carregamento inicial quando ele demonstra o padrão de conteúdo e fornece orientação útil. Nunca abra mais de um item apenas para preencher espaço.

Variante compacta de FAQ

Use rótulos de perguntas e respostas autônomas concisas. A interação não justifica por si só dados estruturados; o esquema depende do tipo de conteúdo e dos registros visíveis exatos.

Estado de estresse de conteúdo longo

Um painel com mais de dois parágrafos curtos sinaliza que o material pode merecer uma seção visível. A variante de estresse existe para testar encapsulamento, links, listas, foco e fluxo responsivo, não como o alvo editorial normal.

Parâmetros

O contrato separa o comportamento do grupo do conteúdo do item para que cada plataforma possa preservar os mesmos rótulos, estados e relações.

O primeiro título pai mapeia para heading. O primeiro título de cada item aninhado mapeia para label, e tudo após ele mapeia para o content desse item. Este é um mapeamento explícito de item aninhado, consistente com a precedência base e regras do corpo. open=true define apenas a apresentação inicial; não altera a importância do conteúdo. Quando linkable=true, navegar para um fragmento de item deve expandi-lo, mover o foco de forma previsível e deixar o título visível abaixo de qualquer cabeçalho fixo.

Sintaxe e exemplos de código

As três notações representam um grupo canônico. Elas podem renderizar classes de contêiner diferentes, mas devem preservar o conteúdo no HTML inicial, ordem de origem, nomes acessíveis e estado.

Diretiva Markdown portátil

:::accordion{mode=multiple linkable=true}
## Detalhes da exportação

::item{id="included-fields" open=true}
### Quais campos estão incluídos?

A exportação contém os campos atualmente disponíveis para sua conta e escopo de relatório.
::

::item{id="filter-behavior"}
### Os filtros afetam a exportação?

Sim. Confirme o intervalo de datas, mercado e filtros de status ativos antes de criar o arquivo.
::
:::

Shortcode Hugo

{{< accordion heading="Export details" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="Which fields are included?" open="true" >}}
The export contains the fields currently available to your account and report scope.
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="Do filters affect the export?" >}}
Yes. Confirm the active date range, market, and status filters before creating the file.
{{< /accordion-item >}}
{{< /accordion >}}

Esta é a especificação do adaptador Hugo. Um repositório não a satisfaz adicionando classes a títulos arbitrários; precisa de um renderizador que produza HTML de divulgação nativa ou uma relação equivalente de botão e painel.

Bloco WordPress

<!-- wp:amicited/accordion {"heading":"Export details","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"Which fields are included?","open":true} -->
<p>The export contains the fields currently available to your account and report scope.</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"Do filters affect the export?"} -->
<p>Yes. Confirm the active date range, market, and status filters before creating the file.</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

O bloco WordPress registrado armazena os campos canônicos em vez de depender de um grupo visual de blocos Details não relacionados. Sua renderização no servidor deve emitir cada resposta antes da interação.

Exemplos

Exemplo bom

Detalhes de exclusão de conta aparece após uma explicação visível do que a exclusão faz e um aviso visível de que é irreversível. Seus três rótulos são “O que acontece com as exportações agendadas?”, “Por quanto tempo um arquivo solicitado permanece disponível?” e “Outro administrador pode cancelar a solicitação?” Cada painel contém uma ramificação opcional, todas as respostas estão em HTML e o foco do teclado é visível.

Isso funciona porque a consequência principal e a ação necessária permanecem visíveis. O acordeão contém perguntas secundárias que se aplicam a diferentes leitores, e cada rótulo permite ao leitor prever se vale a pena abri-lo.

Exemplo ruim

Escolha seu plano contém painéis fechados rotulados “Iniciante”, “Equipe” e “Empresarial”. Preço, limites de uso, prazo do contrato, condições de cancelamento e disponibilidade estão dentro dos painéis. Apenas um plano pode ficar aberto por vez.

Isso falha porque critérios de compra precisam de visibilidade lado a lado. O leitor deve abrir painéis repetidamente e lembrar fatos, enquanto um extrator não interativo pode perder preços carregados pelo cliente. Substitua por uma tabela visível de preços ou especificações e reserve a divulgação para detalhes opcionais, como formatos de fatura ou regras de elegibilidade incomuns.

Marcação de esquema e acessibilidade

Acordeão não tem um tipo Schema.org dedicado. A interação não alimenta dados estruturados apenas por existir. Se seus registros forem perguntas e respostas genuínas, o contrato de conteúdo FAQ pode alimentar FAQPage; se o grupo contiver detalhes de produto, políticas ou notas de resolução de problemas, use apenas o esquema justificado pela página e conteúdo. O texto visível e qualquer representação estruturada devem corresponder.

Prefira <details> e <summary> nativos para divulgações simples porque o navegador fornece operação de teclado e semântica de estado. Onde o design ou comportamento de abertura única exigir uma implementação personalizada, cada controle deve ser um button, expor aria-expanded="true" ou "false", referenciar seu painel com aria-controls e ter um ID único que o painel possa referenciar com aria-labelledby. Não coloque o controle em uma div com um manipulador de clique.

Enter ou Espaço deve operar o controle focado. Tab navega pelos controles e conteúdo interativo no painel aberto; o foco não deve entrar em conteúdo fechado. Abrir ou fechar um painel normalmente deixa o foco em seu controle. Navegação por teclas de seta entre cabeçalhos é opcional, mas se implementada, não deve substituir o comportamento normal de Tab.

Mantenha todos os rótulos na árvore de acessibilidade e todas as respostas no HTML de origem. Um painel visualmente fechado pode usar comportamento de divulgação nativo ou um estado oculto suportado, mas seu conteúdo deve se tornar disponível quando expandido sem uma segunda busca. O estado recolhido não deve causar conteúdo duplicado por meio de cópias separadas para desktop e celular. Teste com zoom de 200%, rótulos longos, apenas teclado, movimento reduzido e um leitor de tela. Anime altura ou rotação de ícone apenas quando o movimento puder ser suprimido e o conteúdo não for atrasado.

Regras de escrita

O rótulo carrega o custo da interação, portanto deve fazer uma promessa precisa. Escreva de 3 a 14 palavras e geralmente não mais que 120 caracteres. Use uma pergunta direta para conteúdo de FAQ e uma frase nominal descritiva para conteúdo de referência. Evite “Mais”, “Detalhes”, “Leia isto” e rótulos que diferem apenas por um número.

Use de 3 a 8 itens por grupo. Cada painel deve normalmente conter de 20 a 120 palavras e no máximo 250. Dois painéis curtos são mais claros como prosa aberta; nove ou mais precisam de agrupamento, navegação visível ou consolidação editorial. Mantenha os rótulos gramaticalmente paralelos e organize os itens por tarefa do leitor, frequência esperada ou uma sequência real de categorias — não alfabeticamente, a menos que a consulta seja genuinamente alfabética.

O tom do painel é direto, autocontido e factual. Diga a resposta na primeira frase porque o leitor já pagou um custo de interação. Defina qualquer termo necessário dentro do painel ou no texto visível imediatamente antes do grupo. Não comece com rodeios como “Há várias coisas a considerar.”

Nunca coloque apenas dentro de um acordeão:

• a resposta direta da página ou proposta de valor única;
• avisos de segurança, contraindicações, obrigações legais ou consequências irreversíveis;
• preço, disponibilidade, limites materiais do produto ou condições de compra necessárias;
• etapas ordenadas, pré-requisitos ou uma verificação de conclusão;
• evidências necessárias para apoiar a afirmação circundante;
• uma comparação principal ou matriz de decisão;
• formulários, controles de checkout, consentimento ou a chamada para ação principal da página;
• outro acordeão, abas ou um carrossel.

Uma lista compacta, tabela pequena, link inline ou imagem de apoio é aceitável quando pertence inteiramente a um item opcional e permanece utilizável no celular. Se um painel precisar de seu próprio índice ou mais de um nível de título, promova-o para uma seção visível ou página separada.

Tipos de post que usam

O array postTypes do frontmatter é a origem desta matriz de uso. Inclusão significa que o elemento está disponível sob a condição declarada, não obrigatório em toda página desse tipo.

Lista de verificação de QA

• Uma resposta direta visível aparece antes do acordeão.
• Cada item é conteúdo de referência opcional, não informação que todos os leitores precisam.
• O grupo tem de 3 a 8 itens com rótulos precisos e paralelos.
• O texto completo de cada painel está presente no HTML inicial renderizado no servidor.
• Nenhuma resposta depende de uma requisição de rede acionada por clique ou inserção apenas do lado do cliente.
• details/summary nativos ou botões reais fornecem comportamento de teclado correto.
• Controles personalizados expõem aria-expanded, aria-controls, IDs únicos e um rótulo de painel associado.
• O foco é visível, permanece previsível após alternar e não pode entrar em um painel fechado.
• Rótulos longos encapsulam sem cortes, sobreposição ou ocultação do indicador de estado.
• O layout funciona com zoom de 200% e em uma janela de visualização estreita sem rolagem horizontal.
• Movimento respeita as preferências de movimento reduzido e nunca atrasa o acesso ao conteúdo.
• Links de fragmento individuais, quando suportados, abrem e revelam o painel correto.
• Dados estruturados são baseados no significado do conteúdo, não na aparência do acordeão.
• Registros FAQPage, se emitidos, correspondem exatamente ao texto visível da pergunta e resposta.
• Nenhum acordeão aninhado, conjunto de abas adjacente, cópia móvel repetida ou CTA principal está presente.
• A página ainda comunica sua resposta principal quando todos os painéis estão fechados.

Perguntas frequentes

O frontmatter armazena os registros canônicos de FAQ para esta página. Suas respostas reforçam o limite de implementação: o conteúdo pode estar visualmente recolhido, mas permanece presente, acessível e secundário à resposta visível.