Acordeón: Reglas y ejemplos de divulgación progresiva

Un acordeón es un conjunto agrupado de controles de divulgación etiquetados que permite al lector revelar o plegar contenido de apoyo en el mismo lugar. Úsalo para detalles de referencia opcionales, no para la respuesta principal de la página.

Este par renderizado demuestra la divulgación progresiva: las etiquetas siguen siendo escaneables, un panel está abierto y ambas respuestas están presentes en el HTML de la página, independientemente de si el visitante interactúa.

Por qué es importante este elemento

La divulgación progresiva significa mostrar la información necesaria para la decisión actual mientras se mantienen disponibles bajo demanda los detalles más profundos o menos comunes. Ayuda cuando una página atiende a lectores con diferentes niveles de conocimiento. Un cliente recurrente puede pasar por alto las notas de implementación; un usuario novel puede abrirlas. El control reduce la densidad visual sin eliminar contenido ni obligar a cada lector a pasar por cada excepción.

La misma conveniencia puede convertirse en ocultación. Un lector que busca una respuesta directa, llega a la página y ve ocho etiquetas cerradas debe adivinar qué panel la contiene y realizar una acción adicional. En móvil, abrir y cerrar repetidamente también mueve el contenido dentro del viewport. Por lo tanto, el acordeón se gana su lugar solo cuando la mayoría de los lectores pueden completar su tarea principal sin abrir todos los paneles.

La extractabilidad automática añade una prueba más estricta. La extractabilidad es la capacidad de los motores de búsqueda, sistemas de respuesta con IA, analizadores y herramientas de asistencia para recibir el texto y preservar su relación con su etiqueta. Cada respuesta debe estar presente en el Modelo de Objetos del Documento (DOM) inicial renderizado por el servidor, la representación estructurada de la página en el navegador. CSS puede plegar visualmente un panel presente; JavaScript no debe obtener o fabricar la respuesta solo después de un clic. Un rastreador puede no hacer clic, ejecutar el código del cliente o esperar una solicitud secundaria.

Sigue las reglas de redacción de elementos antes de usar este patrón. Si el propósito del contenido coincide con un elemento tipado más específico, ese elemento tiene prioridad. Un acordeón puede contener contenido de apoyo permitido, pero no debe renombrar ni aplanar una advertencia, comparación, definición o secuencia de pasos solo para hacer la página más corta.

Cuándo usarlo

Usa un acordeón cuando se cumplan las cuatro condiciones:

1. El lector puede predecir el contenido del panel a partir de su etiqueta.
2. El contenido es útil para un subconjunto de lectores, no necesario para todos.
3. Todo el contenido del panel se envía en el HTML inicial y permanece accesible sin necesidad de un dispositivo señalador.
4. Plegar mejora materialmente el escaneo en el viewport esperado.

Los buenos candidatos incluyen detalles opcionales de compatibilidad, ramas de error poco comunes, definiciones de apoyo, cláusulas secundarias de políticas, excepciones de envío y respuestas de referencia agrupadas. Un acordeón también puede funcionar para una colección grande de preguntas frecuentes cuando cada pregunta permanece visible y cada respuesta es autocontenida.

Los casos cercanos revelan los usos incorrectos más comunes:

• Una página corta con dos secciones breves: los encabezados y párrafos visibles son más rápidos de escanear que dos controles.
• Un artículo largo que parece más corto: plegar diez secciones sustanciales reduce la altura percibida pero aumenta la interacción y oculta el alcance de la página.
• Información principal del producto: el precio, la disponibilidad, las limitaciones del material, las condiciones de cancelación y las especificaciones principales influyen en la decisión y no deben depender de la expansión.
• Un procedimiento secuencial: los pasos requieren orden y contexto. Un panel cerrado puede hacer que los lectores omitan un requisito previo o ejecuten pasos fuera de secuencia.
• Una comparación: los lectores necesitan visibilidad simultánea de los mismos criterios. Los paneles separados obligan a una comparación basada en la memoria.
• Una advertencia de seguridad o calificación legal: la consecuencia de omitirla es mayor que el beneficio visual de ocultarla.
• Un sustituto de navegación: un acordeón no es una tabla de contenidos. Revela contenido en el mismo lugar en lugar de moverse a secciones estables de la página.

Ante la duda, publica el contenido de forma visible. El desplazamiento adicional suele ser recuperable; una respuesta omitida, una restricción no revelada o un nodo DOM no disponible no lo son.

Dónde ubicarlo

Coloca el acordeón después de que la página haya entregado su respuesta directa y suficiente explicación visible para que el lector entienda qué contiene el grupo. Preséntalo con un H2 y una oración de alcance. El grupo funciona entonces como una capa de referencia complementaria dentro de esa sección.

Reglas de posición exactas:

• Colócalo después de la explicación visible que califica, nunca entre una afirmación y la evidencia que la respalda.
• Mantenlo dentro de la sección principal cuyo tema etiqueta cada elemento. Si las etiquetas solo tienen sentido sin un encabezado faltante, el grupo está mal ubicado.
• Coloca un acordeón de detalles de producto después del valor principal, el contexto de precio y las condiciones de compra; coloca las ramas de solución de problemas después del diagnóstico compartido y la primera verificación más segura.
• Mantén un acordeón final de preguntas frecuentes después de la conclusión principal y antes de la siguiente acción final, siempre que responda preguntas residuales en lugar de repetidas.
• Dale al grupo un anclaje de sección estable cuando los lectores puedan enlazar a él. Los enlaces a paneles individuales son opcionales, pero si se proporcionan, deben abrir y enfocar el elemento correcto.

Un acordeón no puede situarse directamente junto a pestañas, un segundo acordeón o una tabla de comparación densa. Los patrones de interacción adyacentes obligan a los lectores a elegir un mecanismo antes de poder elegir contenido. No puede interrumpir pasos ordenados, separar una advertencia de su consecuencia, ni situarse entre el precio de un producto y las condiciones que rigen ese precio. No coloques un banner promocional dentro del grupo o inmediatamente después de cada panel; la promoción compite con la tarea de referencia y hace que la expansión parezca una trampa de ventas.

Anatomía

La anatomía etiquetada contiene siete partes:

1. Encabezado de grupo: nombra el tema compartido en la jerarquía del documento circundante.
2. Etiqueta de elemento: predice el contenido específico sin etiquetas vagas como «Más información».
3. Control de divulgación: un summary nativo o un button que recibe el foco del teclado y alterna un panel.
4. Indicador de estado: comunica visualmente si está abierto o cerrado, mientras que el estado programático se expone mediante semántica nativa o aria-expanded.
5. Panel: contiene la respuesta o el detalle de referencia y permanece en el DOM inicial.
6. Relación de control: la semántica nativa <details>/<summary> o aria-controls más IDs coincidentes asocian cada control con exactamente un panel.
7. Límite de elemento: el espaciado, el borde y la agrupación del DOM evitan que una etiqueta parezca controlar una respuesta vecina.

El cheurón visible es decorativo. Ocúltalo de la tecnología de asistencia porque el estado expandido ya proporciona el significado. La rotación por sí sola no puede comunicar el estado; la semántica del control debe hacerlo.

Ejemplos de diseño

Cada variante usa los mismos campos y la regla de presencia en el DOM. Elige la variante según la tarea de lectura, no por decoración.

Grupo estándar de apertura única

Abrir un elemento cierra el elemento abierto anteriormente. Úsalo cuando los paneles son alternativas y los lectores normalmente necesitan uno a la vez, como síntomas de solución de problemas mutuamente excluyentes.

Grupo de referencia de apertura múltiple

Los lectores pueden mantener varios paneles abiertos. Úsalo cuando pueden comparar o combinar detalles complementarios, como tipos de archivo compatibles y permisos de cuenta. Si la comparación simultánea es la tarea principal, usa una tabla visible en su lugar.

Orientación con apertura por defecto

Abre el primer elemento o el más común en la carga inicial cuando demuestra el patrón de contenido y proporciona una orientación útil. Nunca abras más de un elemento solo para llenar espacio.

Variante compacta de preguntas frecuentes

Usa etiquetas de pregunta y respuestas autónomas concisas. La interacción por sí misma no justifica datos estructurados; el esquema depende del tipo de contenido y de los registros visibles exactos.

Estado de estrés de contenido largo

Un panel con más de dos párrafos cortos indica que el material puede merecer una sección visible. La variante de estrés existe para probar ajuste de texto, enlaces, listas, foco y flujo responsivo, no como el objetivo editorial normal.

Parámetros

El contrato separa el comportamiento del grupo del contenido del elemento para que cada plataforma pueda preservar las mismas etiquetas, estados y relaciones.

El primer encabezado principal se asigna a heading. El primer encabezado de cada elemento anidado se asigna a label, y todo lo que le sigue se asigna al content de ese elemento. Este es un mapeo explícito de elementos anidados, coherente con la precedencia base y las reglas del cuerpo. open=true establece solo la presentación inicial; no cambia la importancia del contenido. Cuando linkable=true, navegar a un fragmento de elemento debe expandirlo, mover el foco de forma predecible y dejar el encabezado visible debajo de cualquier encabezado fijo.

Sintaxis y ejemplos de código

Las tres notaciones representan un grupo canónico. Pueden renderizar diferentes clases contenedoras, pero deben preservar el contenido en el HTML inicial, el orden de origen, los nombres accesibles y el estado.

Directiva Markdown portátil

:::accordion{mode=multiple linkable=true}
## Detalles de exportación

::item{id="included-fields" open=true}
### ¿Qué campos están incluidos?

La exportación contiene los campos actualmente disponibles para tu cuenta y alcance del informe.
::

::item{id="filter-behavior"}
### ¿Los filtros afectan la exportación?

Sí. Confirma el rango de fechas, mercado y filtros de estado activos antes de crear el archivo.
::
:::

Shortcode de Hugo

{{< accordion heading="Detalles de exportación" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="¿Qué campos están incluidos?" open="true" >}}
La exportación contiene los campos actualmente disponibles para tu cuenta y alcance del informe.
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="¿Los filtros afectan la exportación?" >}}
Sí. Confirma el rango de fechas, mercado y filtros de estado activos antes de crear el archivo.
{{< /accordion-item >}}
{{< /accordion >}}

Esta es la especificación del adaptador de Hugo. Un repositorio no la cumple añadiendo clases a encabezados arbitrarios; necesita un renderizador que produzca HTML de divulgación nativo o una relación equivalente de botón y panel.

Bloque de WordPress

<!-- wp:amicited/accordion {"heading":"Detalles de exportación","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"¿Qué campos están incluidos?","open":true} -->
<p>La exportación contiene los campos actualmente disponibles para tu cuenta y alcance del informe.</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"¿Los filtros afectan la exportación?"} -->
<p>Sí. Confirma el rango de fechas, mercado y filtros de estado activos antes de crear el archivo.</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

El bloque registrado de WordPress almacena los campos canónicos en lugar de depender de un grupo visual de bloques Details no relacionados. Su renderizador de servidor debe emitir cada respuesta antes de la interacción.

Ejemplos

Ejemplo correcto

Detalles de eliminación de cuenta aparece después de una explicación visible de lo que hace la eliminación y una advertencia visible de que es irreversible. Sus tres etiquetas son «¿Qué sucede con las exportaciones programadas?», «¿Cuánto tiempo permanece disponible un archivo solicitado?» y «¿Puede otro administrador cancelar la solicitud?». Cada panel contiene una rama opcional, todas las respuestas están en HTML y el foco del teclado es visible.

Esto funciona porque la consecuencia principal y la acción requerida permanecen visibles. El acordeón contiene preguntas secundarias que aplican a diferentes lectores, y cada etiqueta permite al lector predecir si vale la pena abrirla.

Ejemplo incorrecto

Elige tu plan contiene paneles cerrados etiquetados como «Inicial», «Equipo» y «Empresa». El precio, los límites de uso, el plazo del contrato, las condiciones de cancelación y la disponibilidad están dentro de los paneles. Solo se puede abrir un plan a la vez.

Esto falla porque los criterios de compra necesitan visibilidad lado a lado. El lector debe abrir los paneles repetidamente y recordar datos, mientras que un extractor no interactivo puede perder los precios cargados por el cliente. Sustitúyelo con una tabla de precios o especificaciones visible y reserva la divulgación para detalles opcionales como formatos de factura o reglas de elegibilidad poco comunes.

Marcado de esquema y accesibilidad

El acordeón no tiene un tipo dedicado de Schema.org. La interacción no alimenta datos estructurados solo por existir. Si sus registros son preguntas y respuestas genuinas, el contrato de contenido de preguntas frecuentes puede alimentar FAQPage; si el grupo contiene detalles de producto, políticas o notas de solución de problemas, usa solo el esquema justificado por la página y el contenido. El texto visible y cualquier representación estructurada deben coincidir.

Prefiere <details> y <summary> nativos para divulgaciones sencillas porque el navegador proporciona la operación del teclado y la semántica de estado. Cuando el diseño o el comportamiento de apertura única requieran una implementación personalizada, cada control debe ser un button, exponer aria-expanded="true" o "false", hacer referencia a su panel con aria-controls y tener un ID único que el panel pueda referenciar con aria-labelledby. No coloques el control en un div con un manejador de clic.

Enter o Espacio deben operar el control enfocado. Tabulador se mueve a través de los controles y el contenido interactivo en el panel abierto; el foco no debe entrar en contenido cerrado. Abrir o cerrar un panel normalmente deja el foco en su control. La navegación con teclas de flecha entre encabezados es opcional, pero si se implementa, no debe reemplazar el comportamiento normal de Tabulador.

Mantén todas las etiquetas en el árbol de accesibilidad y todas las respuestas en el HTML de origen. Un panel visualmente cerrado puede usar el comportamiento de divulgación nativo o un estado oculto compatible, pero su contenido debe estar disponible al expandirse sin una segunda carga. El estado plegado no debe causar contenido duplicado a través de copias separadas para escritorio y móvil. Prueba al 200% de zoom, con etiquetas largas, solo teclado, movimiento reducido y un lector de pantalla. Anima la altura o la rotación del icono solo cuando el movimiento se pueda suprimir y el contenido no se retrase.

Reglas de redacción

La etiqueta asume el coste de la interacción, por lo que debe hacer una promesa precisa. Escribe de 3 a 14 palabras y normalmente no más de 120 caracteres. Usa una pregunta directa para contenido de preguntas frecuentes y una frase nominal descriptiva para contenido de referencia. Evita «Más», «Detalles», «Lee esto» y etiquetas que solo se diferencien por un número.

Usa de 3 a 8 elementos por grupo. Cada panel debe contener normalmente de 20 a 120 palabras y no más de 250. Dos paneles cortos son más claros como prosa abierta; nueve o más necesitan agrupación, navegación visible o consolidación editorial. Mantén las etiquetas gramaticalmente paralelas y organiza los elementos por tarea del lector, frecuencia esperada o una secuencia real de categorías, no alfabéticamente a menos que la consulta sea genuinamente alfabética.

El tono del panel es directo, autocontenido y objetivo. Expresa la respuesta en la primera oración porque el lector ya ha pagado un coste de interacción. Define cualquier término necesario dentro del panel o en texto visible inmediatamente antes del grupo. No empieces con rodeos como «Hay varias cosas a considerar».

Nunca pongas solo dentro de un acordeón:

• la respuesta directa de la página o su propuesta de valor única;
• advertencias de seguridad, contraindicaciones, obligaciones legales o consecuencias irreversibles;
• precio, disponibilidad, límites materiales del producto o condiciones de compra requeridas;
• pasos ordenados, requisitos previos o una verificación de finalización;
• evidencia necesaria para respaldar la afirmación circundante;
• una comparación principal o matriz de decisión;
• formularios, controles de pago, consentimiento o la llamada a la acción principal de la página;
• otro acordeón, pestañas o un carrusel.

Una lista compacta, tabla pequeña, enlace en línea o imagen de apoyo es aceptable cuando pertenece enteramente a un elemento opcional y sigue siendo utilizable en móvil. Si un panel necesita su propia tabla de contenidos o más de un nivel de encabezado, promuévelo a una sección visible o a una página separada.

Tipos de publicaciones que lo usan

El arreglo postTypes del frontmatter es la fuente de esta matriz de uso. La inclusión significa que el elemento está disponible bajo la condición indicada, no que es obligatorio en todas las páginas de ese tipo.

Lista de verificación de control de calidad

• Aparece una respuesta directa visible antes del acordeón.
• Cada elemento es contenido de referencia opcional, no información que todos los lectores necesiten.
• El grupo tiene de 3 a 8 elementos con etiquetas precisas y paralelas.
• El texto completo de cada panel está presente en el HTML inicial renderizado por el servidor.
• Ninguna respuesta depende de una solicitud de red activada por clic o de una inserción solo del lado del cliente.
• details/summary nativos o botones reales proporcionan el comportamiento correcto del teclado.
• Los controles personalizados exponen aria-expanded, aria-controls, IDs únicos y una etiqueta de panel asociada.
• El foco es visible, permanece predecible después de alternar y no puede entrar en un panel cerrado.
• Las etiquetas largas se ajustan sin recortes, superposiciones ni ocultación del indicador de estado.
• El diseño funciona al 200% de zoom y en un viewport estrecho sin desplazamiento horizontal.
• El movimiento respeta las preferencias de movimiento reducido y nunca retrasa el acceso al contenido.
• Los enlaces a fragmentos individuales, cuando son compatibles, abren y revelan el panel correcto.
• Los datos estructurados se basan en el significado del contenido, no en la apariencia del acordeón.
• Los registros FAQPage, si se emiten, coinciden exactamente con el texto visible de la pregunta y la respuesta.
• No hay acordeón anidado, conjunto de pestañas adyacente, copia móvil repetida ni CTA principal presente.
• La página sigue comunicando su respuesta principal cuando todos los paneles están cerrados.

Preguntas frecuentes

El frontmatter almacena los registros canónicos de preguntas frecuentes para esta página. Sus respuestas refuerzan el límite de implementación: el contenido puede estar visualmente plegado, pero permanece presente, accesible y secundario a la respuesta visible.