Regla de accesibilidad: aria-roledescription debe estar en elementos con un rol semántico

Acerca de esta regla de accesibilidad

Por qué es importante

El atributo aria-roledescription permite a los autores proporcionar una descripción localizada y legible del rol de un elemento. Por ejemplo, podrías usarlo para describir un role="slider" como “selector de prioridad” para que un lector de pantalla anuncie algo más significativo al usuario. Sin embargo, este atributo solo funciona cuando el elemento ya tiene un rol que las tecnologías de asistencia puedan identificar.

Cuando aria-roledescription se coloca en un elemento sin rol semántico — como un <div>, <span> o <p> simple — no hay un rol que la descripción pueda refinar. Esto crea una situación confusa donde las tecnologías de asistencia pueden anunciar una descripción sin contexto, no anunciar nada en absoluto, o comportarse de forma impredecible. En algunos casos, esto puede romper la accesibilidad de secciones completas de una aplicación.

Este problema afecta principalmente a usuarios ciegos, usuarios sordociegos y usuarios con discapacidades motoras que dependen de lectores de pantalla u otras tecnologías de asistencia para entender y navegar el contenido de la página. Cuando la información del rol es sin sentido o está ausente, estos usuarios pierden la capacidad de entender qué es un elemento de la UI y cómo interactuar con él.

Criterios de éxito WCAG relacionados

Esta regla se relaciona con el Criterio de Éxito WCAG 4.1.2: Nombre, función, valor (Nivel A), que requiere que para todos los componentes de la interfaz de usuario, el nombre, función y valor puedan determinarse programáticamente. Cuando aria-roledescription se aplica a un elemento sin rol semántico, el rol no puede comunicarse apropiadamente, violando este criterio.

Esto aplica a WCAG 2.0, 2.1 y 2.2 en Nivel A, así como a la directriz EN 301 549 9.4.1.2.

Cómo funciona la regla

La regla de Axe aria-roledescription verifica cada elemento que tiene un atributo aria-roledescription y comprueba que el elemento también tenga un rol semántico. Hay tres posibles resultados:

Fallo: El elemento no tiene rol alguno (p. ej., <div>, <span>, <p> sin un atributo role explícito). Estos elementos tienen un rol genérico o ningún rol implícito, por lo que aria-roledescription no tiene nada que describir.
Éxito: El elemento tiene un rol implícito bien soportado (como <button>, <img>, <nav>) o un rol explícito (como role="combobox").
Incompleto (necesita revisión): El elemento tiene un rol que puede no estar ampliamente soportado por las tecnologías de asistencia (p. ej., role="rowgroup"). Estos necesitan pruebas manuales para verificar que funcionen correctamente.

Cómo solucionarlo

Identifica los elementos señalados por la regla — tienen aria-roledescription pero no rol semántico.
Decide si el elemento realmente necesita aria-roledescription. En muchos casos, la solución es simplemente eliminarlo.
Si la descripción es necesaria, ya sea:
- Usa un elemento HTML semántico que tenga un rol implícito (p. ej., reemplaza <div> con <button>).
- Añade un atributo role explícito al elemento para que la descripción tenga contexto.
Asegúrate de que el valor de aria-roledescription refine significativamente el rol — debe describir una versión más específica de lo que es el elemento, no contradecirlo.

Ejemplos

Incorrecto: `aria-roledescription` en elementos sin rol semántico

Estos elementos no tienen rol implícito o explícito, por lo que aria-roledescription no tiene nada que describir.

<p aria-roledescription="my paragraph">
  This is some text.
</p>

<div aria-roledescription="my container">
  Some content here.
</div>

<span aria-roledescription="my label">Name</span>

Un <p> no tiene un rol ARIA correspondiente, y un <div> o <span> simple no se mapea a ningún rol (o al rol genérico generic). Los lectores de pantalla no pueden usar la descripción de forma significativa.

Correcto: `aria-roledescription` en elementos con rol implícito

Estos elementos HTML tienen roles semánticos incorporados, por lo que la descripción refina algo real.

<img
  aria-roledescription="illustration"
  src="diagram.png"
  alt="System architecture overview" />

<button aria-roledescription="play control">
  Play
</button>

El elemento <img> tiene un rol implícito de img, y <button> tiene un rol implícito de button. Los valores de aria-roledescription proporcionan descripciones más específicas de estos roles.

Correcto: `aria-roledescription` en elementos con rol explícito

<div
  role="combobox"
  aria-roledescription="city picker"
  aria-expanded="false"
  aria-haspopup="listbox">
  Select a city
</div>

<div
  role="slider"
  aria-roledescription="priority selector"
  aria-valuenow="3"
  aria-valuemin="1"
  aria-valuemax="5"
  tabindex="0">
</div>

El atributo role explícito proporciona la base semántica, y aria-roledescription añade una etiqueta más amigable para el usuario de lo que ese rol representa en este contexto específico.

Solución incorrecta: añadir un rol que no coincide solo para satisfacer la regla

No añadas un role que no coincida con el comportamiento real del elemento solo para pasar la verificación.

<!-- No hagas esto -->

<p role="button" aria-roledescription="my paragraph">
  This is some text.
</p>

Si el elemento es solo un párrafo de texto, elimina aria-roledescription completamente en lugar de añadir un rol incorrecto.

Necesita revisión: `aria-roledescription` en elementos con soporte limitado del rol

Algunos roles tienen soporte inconsistente en las tecnologías de asistencia. Estos se marcarán como necesitando revisión manual.

<h1 aria-roledescription="page title">Welcome</h1>

<div role="rowgroup" aria-roledescription="data section">
<!-- row content -->

</div>

El rol heading y el rol rowgroup pueden no soportar consistentemente aria-roledescription en todos los lectores de pantalla. Prueba estos casos manualmente con tecnologías de asistencia reales para confirmar que la descripción se anuncia correctamente.

Learn more: