Validación HTML: Valor incorrecto "button" para el atributo "role" en el elemento "h1" (o h2, h3, h4, h5, h6).

Acerca de este problema HTML

La especificación ARIA en HTML define qué roles están permitidos en cada elemento HTML. Los elementos de encabezado (<h1>–<h6>) tienen un rol implícito de heading, y el conjunto de roles que se les puede asignar explícitamente es limitado. El rol button no está entre ellos, por lo que aplicar role="button" directamente a un elemento de encabezado es inválido.

Esto importa por varias razones. Primero, los encabezados juegan un papel crítico en la estructura del documento y la accesibilidad — los usuarios de lectores de pantalla se basan en los encabezados para navegar y entender la jerarquía de la página. Asignar role="button" a un encabezado anula su significado semántico, lo que confunde a las tecnologías de asistencia. Segundo, los navegadores y lectores de pantalla pueden manejar semánticas conflictivas de manera impredecible, llevando a una experiencia inconsistente para los usuarios. Tercero, viola la especificación HTML del W3C, lo que significa que tu marcado no pasará la validación.

Por qué esta combinación es problemática

Cuando aplicas role="button" a un elemento, las tecnologías de asistencia lo tratan como un botón interactivo. Esto reemplaza completamente la semántica nativa de encabezado del elemento. Los usuarios que navegan por encabezados ya no encontrarían ese encabezado en su lista, y los usuarios que navegan por controles interactivos se encontrarían con un “botón” que podría no comportarse como tal (careciendo de soporte de teclado, gestión de foco, etc.).

Si realmente necesitas algo que se vea como un encabezado pero actúe como un botón, hay enfoques válidos para lograr esto sin romper la semántica.

Cómo solucionarlo

Hay varias estrategias dependiendo de tu intención:

Usa un elemento <button> estilizado como un encabezado. Este es a menudo el enfoque más limpio cuando el propósito principal es la interactividad. Puedes estilizar el botón con CSS para que coincida con la apariencia de tu encabezado.
Envuelve el encabezado en un <div> con role="button". Esto preserva el encabezado en el esquema del documento mientras hace que el contenedor sea interactivo. Sin embargo, ten en cuenta que el rol button aplica role="presentation" a todos los elementos descendientes, lo que significa que las tecnologías de asistencia eliminarán la semántica de encabezado del <h2> dentro de él. El contenido del texto sigue siendo accesible, pero no será reconocido como un encabezado.
Coloca un <button> dentro del encabezado. Esto mantiene intacta la semántica del encabezado para la estructura del documento mientras hace que el texto dentro de él sea interactivo. Este patrón se usa comúnmente para componentes de estilo acordeón y es el enfoque recomendado por las Prácticas de Autoría WAI-ARIA.

Ejemplos

❌ Inválido: `role="button"` en un encabezado

<h2 role="button">Toggle Section</h2>

Esto desencadena el error de validación porque button no es un rol permitido para elementos de encabezado.

✅ Solución: usa un `<button>` estilizado como un encabezado

<button type="button" class="heading-style">Toggle Section</button>

.heading-style {
  font-size: 1.5em;
  font-weight: bold;
  background: none;
  border: none;
  cursor: pointer;
}

✅ Solución: envuelve el encabezado en un contenedor con `role="button"`

<div role="button" tabindex="0">
  <h2>Toggle Section</h2>
</div>

Ten en cuenta que este enfoque hace que el <h2> pierda su semántica de encabezado para las tecnologías de asistencia, ya que el rol button no admite hijos semánticos. También recuerda agregar tabindex="0" para que el elemento sea enfocable con el teclado, e implementar manejadores keydown para Enter y Espacio para replicar el comportamiento nativo del botón.

✅ Solución: coloca un `<button>` dentro del encabezado (recomendado para acordeones)

<h2>
  <button type="button" aria-expanded="false">
    Toggle Section
  </button>
</h2>

Este es el patrón más robusto. El encabezado permanece en el esquema del documento, y el botón dentro de él es completamente interactivo con soporte de teclado integrado. Los usuarios de lectores de pantalla pueden encontrarlo tanto al navegar por encabezados como al navegar por elementos interactivos. El atributo aria-expanded comunica si la sección asociada está abierta o cerrada.