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 legible y localizada 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 ningún 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 manera 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 no tiene sentido o falta, estos usuarios pierden la capacidad de entender qué es un elemento de la interfaz 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 mediante programación. Cuando aria-roledescription se aplica a un elemento sin rol semántico, el rol no puede comunicarse adecuadamente, violando este criterio.

Esto se 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 confirma que el elemento también tenga un rol semántico. Hay tres posibles resultados:

Falla: El elemento no tiene ningún rol (por ejemplo, <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.
Pasa: 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 (por ejemplo, role="rowgroup"). Estos necesitan pruebas manuales para verificar que funcionen correctamente.

Cómo solucionarlo

Identifica los elementos marcados por la regla — tienen aria-roledescription pero no tienen 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 (por ejemplo, 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 el rol de manera significativa — 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 manera significativa.

Correcto: `aria-roledescription` en elementos con un 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 un 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 sobre 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 de rol limitado

Algunos roles tienen soporte inconsistente en las tecnologías de asistencia. Estos serán marcados como que necesitan 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: