aria-braille attributes must have a non-braille equivalent

The aria-braillelabel and aria-brailleroledescription attributes were introduced to give authors fine-grained control over how content is presented on refreshable braille displays. For example, a visual “4 stars” rating might be represented as **** in braille to save space and improve readability on a limited-cell display. Similarly, a custom role description like “slide” might be abbreviated to “sld” for braille output.

However, these braille-specific attributes are designed as overrides, not standalone values. They modify how an existing accessible name or role description is rendered in braille. If no accessible name or role description exists, there’s nothing for the braille attribute to override. The WAI-ARIA specification states that braille attributes without their non-braille equivalents should be ignored, but assistive technologies may not handle this consistently. Some screen readers might display the braille-only text while others ignore it entirely, leading to an unpredictable experience.

Who is affected

This issue primarily impacts users who are blind or deafblind and rely on refreshable braille displays. It can also affect users with mobility impairments who use assistive technologies that interpret ARIA attributes. When braille attributes lack their non-braille counterparts, these users may encounter missing labels or confusing role information, making it harder — or impossible — to understand and interact with content.

Related WCAG success criteria

This rule maps to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that all user interface components have an accessible name and role that can be programmatically determined. Using aria-braillelabel without a proper accessible name, or aria-brailleroledescription without aria-roledescription, means the element’s name or role description is not reliably communicated to assistive technologies. This applies to WCAG 2.0, 2.1, and 2.2 at Level A, as well as EN 301 549 guideline 9.4.1.2.

How to fix it

• Add a non-braille equivalent. If an element has aria-braillelabel, ensure it also has an accessible name — via aria-label, aria-labelledby, visible text content, or the alt attribute on images. If an element has aria-brailleroledescription, ensure it also has aria-roledescription.
• Check attribute placement. The aria-braillelabel or aria-brailleroledescription attribute might be on the wrong element. Verify it’s on the same element that has the corresponding accessible name or role description.
• Remove unnecessary braille attributes. If the braille attribute isn’t serving a meaningful purpose (e.g., if the braille text would be the same as the accessible name), remove it entirely.

Examples

Incorrect: aria-braillelabel without an accessible name

The image has an empty alt attribute, so it has no accessible name. The aria-braillelabel has nothing to override.

<img alt="" aria-braillelabel="****" src="stars.jpg">

Correct: aria-braillelabel with an accessible name

The button has an accessible name from the image’s alt text. The aria-braillelabel overrides how that name appears on a braille display.

<button aria-braillelabel="****">
  <img alt="4 stars" src="stars.jpg">
</button>

Incorrect: aria-brailleroledescription without aria-roledescription

The element has a braille role description but no aria-roledescription to serve as the non-braille equivalent.

<div
  role="article"
  aria-labelledby="slideheading"
  aria-brailleroledescription="sld">
  <h1 id="slideheading">My vacation in Rome</h1>
</div>

Correct: aria-brailleroledescription with aria-roledescription

Both aria-roledescription and aria-brailleroledescription are present, so the braille display can use the abbreviated version while screen readers use the full role description.

<div
  role="article"
  aria-labelledby="slideheading"
  aria-roledescription="slide"
  aria-brailleroledescription="sld">
  <h1 id="slideheading">My vacation in Rome</h1>
</div>

Incorrect: aria-braillelabel on the wrong element

The aria-braillelabel is on a <span> that has no accessible name, even though the parent button does.

<button aria-label="Close">
  <span aria-braillelabel="cls">X</span>
</button>

Correct: aria-braillelabel on the element with the accessible name

The aria-braillelabel is placed on the same element that has aria-label.

<button aria-label="Close" aria-braillelabel="cls">
  <span>X</span>
</button>

Learn more:

Deque Reference

Deque University - How To Fix

→