Core · Mostrar contenido
Acordeón
Muestra y oculta secciones de contenido con los elementos nativos details y summary, de una en una si asignas un nombre al grupo.
Ejemplo
Un grupo de preguntas con sus respuestas: al abrir una, se cierra la que estaba abierta.
What is a design token?
A named value, such as a color or a space, that components read instead of a literal.
Why only one open at a time?
The same name on each details connects them: opening one closes the other.
Does it need JavaScript?
No. The browser opens, closes and groups them.
Problemas conocidos
Hay dos cosas que debes saber antes de confiar en un grupo con nombre.
Grupo exclusivo. El atributo name funciona en Chrome y Edge 120, Safari 17.2 y Firefox 130, todos desde septiembre de 2024 o anteriores, por lo que aún no tiene disponibilidad amplia en Baseline. En un navegador más antiguo, cada panel se abre por separado: no se pierde nada.
Lectores de pantalla. LUZ no ha probado cómo anuncian NVDA, JAWS, VoiceOver, TalkBack y Orca un grupo exclusivo, ni ha comprobado datos de compatibilidad. La agrupación de un conjunto exclusivo no se comunica a la tecnología de asistencia: su correspondencia de accesibilidad en HTML sigue siendo una cuestión abierta (consulta la explicación de Open UI).
Código
Copiar el marcado
Un details sin clase no necesita ninguna: un resumen y un divisor, sin caja.
<details>
<summary>What is a design token?</summary>
<p>A named value that components read.</p>
</details>.luz-accordion añade la caja y el grupo. Con la clase:
<div class="luz-accordion">
<details name="faq" open>
<summary>What is a design token?</summary>
<p>A named value that components read.</p>
</details>
<details name="faq">
<summary>Does it need JavaScript?</summary>
<p>No.</p>
</details>
</div>Variantes y opciones
Un único <details> no necesita clase: la capa de elementos le da estilo. La clase solo sirve para unir varios en una pila.
| Clase o atributo | Qué hace |
|---|---|
.luz-accordion | Une los elementos <details> que contiene en un solo bloque: un borde entre ellos y esquinas redondeadas solo en el bloque |
name="…" | Agrupa los elementos details con el mismo nombre: solo puede haber uno abierto a la vez. No tienen que estar juntos |
open | Hace que un panel empiece abierto. En un grupo con nombre, solo permanece abierto el primer elemento con open en el código fuente |
Cómo funciona
Elementos nativos <details> y <summary>, con estilos de elements/interactive.css y sin clases. components/accordion.css solo añade el bloque unido.
No necesita JavaScript.
- summary es la etiqueta del panel; el resto de details es su contenido.
- El contenido cerrado no se muestra ni forma parte del orden de lectura hasta que se abre el panel.
Sin JavaScript
No cambia nada: el navegador se encarga de abrir, cerrar y agrupar. El acordeón funciona por completo sin scripts.
Teclado y ARIA
Con Tab se llega a cada summary en orden. Enter o Espacio lo abre o lo cierra.
No hay atajos con las teclas de flecha para moverse entre paneles.
- No añadas ningún role:
<details>ya tiene su propia semántica y no admite roles ARIA. - No pongas enlaces ni botones dentro de summary: ese elemento ya es el control.
El contraste y el foco están en la pestaña Diseño.
Diseño
Cuándo usarlo
Usa un acordeón para agrupar bajo títulos breves contenido que la mayoría de lectores puede omitir.
- Preguntas frecuentes y listas de referencia largas.
- Detalles opcionales bajo una respuesta breve.
Cuándo no usarlo
No ocultes información que necesitan todos los lectores ni lo uses para desplazarte por el sitio.
- Para las secciones principales de un sitio, usa una barra lateral. Para contenido entre el que se puede alternar, usa pestañas.
- No pongas un error, un aviso ni un paso obligatorio dentro de un panel cerrado.
- Si solo hay una o dos respuestas breves, muéstralas como texto normal.
Qué hacer y qué no
Cómo escribir el contenido
- Escribe en summary la pregunta o el tema, con mayúscula inicial y en pocas palabras.
- Pon primero la respuesta en el panel. Sé breve y enlaza a otra página para ampliar la información.
- Ordena los paneles según las preguntas de los lectores, empezando por la más frecuente.
Contraste y foco
El texto y el indicador usan el color de texto principal sobre la superficie.
| Parte | Color sobre el fondo | Claro | Oscuro | Alto contraste | Mínimo |
|---|---|---|---|---|---|
Texto de summary | --luz-text-primary on --luz-surface | 16.5:1 | 14.0:1 | 21.0:1 | 4.5:1 |
summary al pasar el puntero | --luz-text-primary on --luz-surface-hover | 14.4:1 | 12.6:1 | 20.1:1 | 4.5:1 |
Anillo de foco | --luz-focus-ring on --luz-surface | 5.9:1 | 7.2:1 | 21.0:1 | 3:1 |
Medido a partir de los valores de los tokens de cada modo y redondeado hacia abajo. El mínimo requerido es el de WCAG 2.2 AA: 4,5:1 para texto y 3:1 para anillos de foco, bordes e iconos.
- Foco: summary tiene el contorno compartido de 2 px
--luz-focus-ring, situado a 2 px del borde del cuadro. - No depende solo del color: el indicador gira para distinguir entre abierto y cerrado; no se usan el borde ni el fondo.
Tokens que usa
Los 6 tokens que lee components/accordion.css, agrupados por familia. Cada familia enlaza a su página, donde aparecen los valores de todos los modos. En Figma son variables con los mismos nombres: consulta Tokens en Figma.
- Spacing and sizing
--luz-space-sm,--luz-space-xs- Radius
--luz-radius-md- Motion
--luz-duration-base
El aspecto de un details individual y de su summary, con sus propios tokens, se define en elements/interactive.css.
El teclado y ARIA están en la pestaña Código.