“Buttons do not have an accessible name”: cómo solucionar este error de Lighthouse

Si alguna vez has pasado tu sitio web por Google Lighthouse o PageSpeed Insights, probablemente te hayas encontrado con advertencias que, a primera vista, parecen bastante más complicadas de lo que realmente son.

Una de ellas es:

Buttons do not have an accessible name

O, en español, algo así como:

Los botones no tienen un nombre accesible

La buena noticia es que normalmente es un problema bastante sencillo de solucionar. Y, de paso, permite entender algo importante sobre accesibilidad web: un botón no solo tiene que verse bien; también tiene que indicar qué hace cuando es interpretado por tecnologías de asistencia.

¿Qué significa “nombre accesible”?

Un nombre accesible es el texto que las tecnologías de asistencia utilizan para identificar un elemento de la interfaz y explicar cuál es su propósito.

En el caso de un <button>, normalmente ese nombre proviene del propio contenido del botón. Por ejemplo:

<button>Buscar</button>

Aquí no hay demasiado misterio. Un lector de pantalla puede identificarlo como un botón y obtener su nombre a partir del texto “Buscar”.

El problema aparece cuando diseñamos un botón utilizando solamente un icono:

<button>
    <i class="fa fa-search"></i>
</button>

Visualmente, para nosotros es bastante evidente:

🔍 = Buscar.

Pero un lector de pantalla no necesariamente puede interpretar ese icono como nosotros.

El resultado puede ser, en términos prácticos, algo parecido a:

“Botón”

Y ahí aparece el problema.

La persona sabe que existe un botón, pero no necesariamente sabe para qué sirve.

¿Por qué ocurre tanto con los botones de iconos?

Es bastante habitual encontrarlos en interfaces modernas.

Tenemos botones para:

• Buscar 🔍
• Abrir el menú ☰
• Cerrar una ventana ×
• Añadir a favoritos ❤️
• Añadir un producto al carrito 🛒
• Compartir
• Reproducir contenido
• Abrir un panel lateral

En todos estos casos el diseñador puede pensar que el icono es suficientemente claro.

Pero un icono no siempre comunica su función de la misma manera para todas las personas.

De hecho, MDN recomienda que los botones tengan un nombre accesible y señala específicamente el caso de los botones que solamente contienen iconos.

Y aquí aparece una regla bastante sencilla:

Si un botón hace algo, debemos asegurarnos de que su propósito pueda identificarse aunque no podamos ver el icono.

1. La opción más sencilla: utilizar texto visible

Cuando el diseño lo permite, esta suele ser la solución más clara.

En lugar de:

<!-- ❌ Solo icono -->
<button>
    <i class="fa fa-search"></i>
</button>

Podemos utilizar:

<!-- ✅ Icono + texto -->
<button type="button">
    <i class="fa fa-search"></i>
    Buscar
</button>

Ahora tenemos un botón que visualmente dice exactamente lo que hace.

Además, no estamos solucionando el problema únicamente para lectores de pantalla. El texto también ayuda a las personas que no reconocen inmediatamente el significado de un determinado icono.

Por ejemplo, una lupa probablemente sea bastante evidente. Pero otros iconos pueden ser mucho más ambiguos.

Cuando puedes poner texto visible, normalmente es la solución más sencilla y comprensible.

2. Cuando el diseño necesita solamente un icono: aria-label

Pero ¿qué ocurre si estamos diseñando una interfaz donde el botón tiene que ser solamente un icono?

Por ejemplo, el típico botón para cerrar una ventana:

<button>
    ×
</button>

O un botón de búsqueda que solamente muestra una lupa.

En estos casos podemos utilizar aria-label:

<button type="button" aria-label="Buscar">
    <i class="fa fa-search" aria-hidden="true"></i>
</button>

El usuario seguirá viendo solamente la lupa, pero el botón tendrá un nombre accesible: “Buscar”.

aria-label está precisamente pensado para proporcionar un nombre cuando no existe un texto visible adecuado que pueda utilizarse para identificar el elemento.

Otro ejemplo:

<button type="button" aria-label="Cerrar">
    ×
</button>

O:

<button type="button" aria-label="Añadir al carrito">
    <i class="fa fa-shopping-cart" aria-hidden="true"></i>
</button>

¿Y por qué aria-hidden="true" en el icono?

Si el icono solamente tiene una función decorativa y ya hemos proporcionado el nombre del botón mediante aria-label, podemos indicarle a las tecnologías de asistencia que ignoren ese icono:

<i class="fa fa-search" aria-hidden="true"></i>

De esta forma, el elemento importante es el botón y su nombre es “Buscar”, en lugar de intentar interpretar también el icono.

3. Texto que existe, pero no se ve: sr-only o visually-hidden

Existe otra alternativa bastante útil: mantener el texto en el HTML pero ocultarlo visualmente mediante CSS.

Por ejemplo:

<button type="button">
    <i class="fa fa-shopping-cart" aria-hidden="true"></i>
    <span class="sr-only">Añadir al carrito</span>
</button>

La idea es que el texto siga formando parte del contenido accesible aunque no aparezca visualmente en pantalla.

Frameworks como Bootstrap ofrecen clases para este propósito; en versiones modernas de Bootstrap, por ejemplo, es habitual utilizar visually-hidden.

La ventaja de este enfoque es que el nombre del botón está directamente en su contenido, en lugar de depender exclusivamente de un atributo ARIA.

¿Cuál de las tres opciones debería utilizar?

Podemos simplificarlo bastante:

En general, el texto visible es la opción más sencilla. Si no es posible por motivos de diseño, aria-label es una solución perfectamente válida para un botón que necesita un nombre accesible.

Un detalle importante: no todo se soluciona con aria-label

Es tentador pensar:

“Lighthouse me reclama un botón. Le pongo aria-label y listo.”

Y muchas veces efectivamente funciona.

Pero ARIA no debería utilizarse como sustituto de HTML semántico cuando el HTML ya nos ofrece una solución adecuada.

Por ejemplo, si podemos utilizar un <button>, es preferible utilizar un botón real antes que convertir un <div> en algo que se comporte como botón mediante role="button".

El elemento <button> ya proporciona comportamiento e interacción apropiados. Un role="button" por sí solo no convierte mágicamente un <div> en un botón completamente funcional.

Por eso, una estructura como esta:

<div role="button">Buscar</div>

no debería ser nuestra primera opción.

Mucho mejor:

<button type="button">Buscar</button>

Y si solamente necesitamos el icono:

<button type="button" aria-label="Buscar">
    <i class="fa fa-search" aria-hidden="true"></i>
</button>

¿Y si utilizo WordPress?

Aquí es donde el problema se vuelve especialmente interesante.

Si desarrollas tus propios temas o plugins, puedes corregirlo directamente en el HTML.

Pero si utilizas WordPress con Elementor, Bootstrap, un tema comercial o algún constructor visual, es bastante habitual encontrarse con botones generados automáticamente.

Un caso típico es el botón del menú móvil:

☰

Visualmente funciona perfectamente.

Pero detrás puede existir un botón que no tiene ningún texto que permita identificar su función.

Lo mismo puede ocurrir con:

• Botones de búsqueda.
• Botones para cerrar ventanas modales.
• Botones de sliders.
• Botones de redes sociales.
• Botones para abrir menús laterales.
• Botones de favoritos.
• Botones de reproducción.

En estos casos conviene revisar las opciones del propio componente.

En Elementor, por ejemplo, dependiendo del widget utilizado, podemos encontrar opciones relacionadas con atributos personalizados. Cuando el componente permite añadir atributos, podemos terminar con algo como:

aria-label|Buscar

La idea es que el HTML generado termine incluyendo:

aria-label="Buscar"

Eso sí: siempre conviene comprobar el HTML final generado por el constructor, porque diferentes widgets y plugins pueden implementar estas opciones de manera distinta.

¿Cómo comprobar si realmente lo solucionamos?

Una vez realizado el cambio, vuelve a ejecutar Lighthouse o PageSpeed Insights.

Si el botón problemático era:

<button>
    <i class="fa fa-search"></i>
</button>

y ahora tenemos:

<button type="button" aria-label="Buscar">
    <i class="fa fa-search" aria-hidden="true"></i>
</button>

deberíamos haber proporcionado al botón un nombre accesible.

También es buena idea revisar el HTML generado desde las herramientas de desarrollador del navegador. Así podemos comprobar que el atributo realmente está llegando al HTML final y no se está eliminando o modificando mediante JavaScript.

No es solamente para mejorar la puntuación de Lighthouse

Aquí hay una diferencia importante.

Es fácil caer en la idea de que todo lo que aparece en Lighthouse es simplemente una lista de cosas que debemos arreglar para conseguir un número más alto.

Pero la accesibilidad no debería tratarse solamente como una competición por conseguir un 100/100.

Si solucionamos este problema, no estamos simplemente haciendo feliz a Lighthouse.

Estamos haciendo que nuestros controles sean más comprensibles para personas que utilizan lectores de pantalla u otras tecnologías de asistencia. Los nombres accesibles permiten identificar qué hace un elemento interactivo.

Y eso es bastante más importante que la puntuación que aparece al final del informe.

En resumen

La advertencia:

Buttons do not have an accessible name

normalmente significa que tenemos un botón cuyo propósito no puede identificarse correctamente mediante tecnologías de asistencia.

La solución suele ser bastante sencilla:

Texto visible:

<button type="button">
    Buscar
</button>

Icono + aria-label:

<button type="button" aria-label="Buscar">
    <i class="fa fa-search" aria-hidden="true"></i>
</button> 

Texto visualmente oculto:

<button type="button">
    <i class="fa fa-search" aria-hidden="true"></i>
    <span class="visually-hidden">Buscar</span>
</button>

Tres soluciones para un problema que, en muchos casos, se puede corregir en cuestión de minutos.

Y quizá esa sea una de las mejores cosas de este tipo de advertencias de Lighthouse: algunas no requieren rehacer todo el sitio ni convertirse en experto en accesibilidad. A veces basta con mirar ese pequeño botón que lleva meses mostrando una lupa y preguntarse:

“¿Pero cómo sabe alguien que no puede verla qué hace este botón?”

Ahí es cuando la accesibilidad empieza a tener sentido.