# Acordeón accesible: botones, encabezados y estado

Source: https://allyway.ai/es/glossary/acordeon-accesible

Un acordeón accesible es un conjunto de secciones plegables cuyas cabeceras son botones dentro de encabezados, muestran si están desplegadas o plegadas con aria-expanded y se pueden abrir con el teclado. Los acordeones personalizados entran en el criterio WCAG 4.1.2 Nombre, función, valor, de nivel A.

Un acordeón accesible permite a todos los visitantes abrir y cerrar sus secciones, con el ratón, con el teclado o con un lector de pantalla. Los acordeones están en todas partes: páginas de preguntas frecuentes, fichas de producto, menús móviles, ajustes de cookies. Con demasiada frecuencia la cabecera en la que se hace clic es un `div` con un controlador de clic: los usuarios de teclado no pueden abrirla y los usuarios de lector de pantalla nunca se enteran de que detrás hay más contenido oculto.

## Qué significa

Un acordeón creado con script es un componente personalizado, así que le afecta el criterio [WCAG 4.1.2 Nombre, función, valor](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (nivel A): su [nombre, función y valor](https://allyway.ai/es/glossary/nombre-funcion-valor) deben poder determinarse por software y los cambios de estado deben llegar a las tecnologías de apoyo. El W3C cita expresamente como ejemplo los widgets de mostrar y ocultar (disclosure). El [patrón de acordeón](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) de la guía WAI-ARIA Authoring Practices describe la estructura:

| Parte | Qué necesita |
|---|---|
| Cabecera | Un `button` que sea el único elemento dentro de un encabezado (un `h2`, `h3`… que encaje en la [estructura de encabezados](https://allyway.ai/es/glossary/estructura-de-encabezados) de la página) |
| Estado | `aria-expanded="true"` cuando el panel es visible, `"false"` cuando está oculto |
| Relación con el panel | `aria-controls` con el ID del panel |
| Panel (opcional) | `role="region"` con `aria-labelledby` que apunte a su botón; evítelo cuando puedan estar abiertos muchos paneles a la vez (más de 6, aproximadamente), para que la página no se llene de regiones |
| Panel que no se puede cerrar | `aria-disabled="true"` en su botón, si el acordeón no permite plegar un panel abierto |

Teclado: Intro o Espacio abre o cierra el panel de la cabecera que tiene el foco. Tab y Mayús + Tab recorren todos los elementos que pueden recibir el foco, incluido el contenido de los paneles abiertos.

> **Tip:** > **La opción nativa: details y summary**
> Para una sola sección desplegable, los elementos HTML `<details>` y `<summary>` ya incluyen el rol, el estado y el manejo del teclado, sin necesidad de ARIA. Use el patrón ARIA cuando necesite el comportamiento completo de un acordeón, por ejemplo que solo haya un panel abierto a la vez.

## Ejemplos

```html title="Ejemplo"
<h3>
  <button type="button" id="acc-1" aria-expanded="false"
          aria-controls="acc-panel-1">
    How long does shipping take?
  </button>
</h3>
<div id="acc-panel-1" role="region" aria-labelledby="acc-1" hidden>
  <p>Orders within Austria arrive in 2–3 working days.</p>
</div>
```

El script alterna `aria-expanded` y `hidden` a la vez. Un lector de pantalla anuncia algo como «How long does shipping take?, botón, contraído, encabezado de nivel 3»: la persona sabe qué es, que se puede abrir y dónde se sitúa en el esquema de la página. Como es un `<button>` real, la [navegación por teclado](https://allyway.ai/es/glossary/navegacion-por-teclado) funciona sin código adicional.

**Do:** Qué hacer

Ponga un botón real dentro de un encabezado, mantenga `aria-expanded` sincronizado con lo que se muestra, oculte los paneles cerrados con `hidden` o `display: none` y muestre un contorno de foco bien visible en las cabeceras.

**Don't:** Qué evitar

Hacer clicable un `div` o el propio encabezado, mostrar el estado solo con una flecha que gira, usar estados como `aria-selected` que un botón no puede tener, u ocultar los paneles cerrados solo de forma visual, de modo que los lectores de pantalla aún los lean.

## Cómo comprobar un acordeón accesible



## Preguntas frecuentes

Q: ¿Cómo se hace accesible un acordeón?
A: Use un `<button>` dentro de un encabezado para cada cabecera, ponga `aria-expanded` en `true` o `false`, vincule el botón con su panel mediante `aria-controls` y oculte los paneles cerrados con `hidden`. El navegador se encarga entonces del teclado.

Q: ¿Las cabeceras de un acordeón deben ser encabezados o botones?
A: Ambas cosas: el patrón del W3C pone el botón dentro de un encabezado. El encabezado permite saltar entre secciones y el botón permite abrirlas y cerrarlas.

Q: ¿Puedo usar details y summary para un acordeón?
A: Sí, para secciones desplegables sencillas `<details>` y `<summary>` son accesibles de serie. Si necesita que solo se abra un panel a la vez o animaciones personalizadas, el patrón de acordeón ARIA le da más control.

Q: ¿Un acordeón necesita navegación con las teclas de flecha?
A: No es obligatorio. Intro, Espacio y la tecla Tab son el núcleo del patrón del W3C para las cabeceras de un acordeón; moverse entre cabeceras con las flechas es un extra opcional. En las pestañas, en cambio, las teclas de flecha son lo esperado.

Q: ¿Son buenos los acordeones para las páginas de preguntas frecuentes?
A: Mantienen cortas las páginas largas, pero las respuestas ocultas pasan fácilmente desapercibidas. Ayudan los encabezados de pregunta claros y también la opción de abrir todas las secciones a la vez en las páginas de preguntas frecuentes largas.
