probeo

Why does aria-braillelabel need a regular label?

aria-braille-equivalent page

The issue

An element with a braille label and no ordinary name is named only on a braille display. Someone listening with a screen reader hears an unnamed control, because the braille attributes are meant to abbreviate a name that exists, not to replace it.

The cause is the way ARIA defines them. aria-braillelabel is a braille-specific version of the accessible name, and aria-brailleroledescription is a braille-specific version of aria-roledescription. Each assumes the ordinary attribute is there too.

Scope

Each visible element with aria-braillelabel or aria-brailleroledescription is checked. A braille label needs a non-braille accessible name from its content, aria-label or aria-labelledby. A braille role description needs an aria-roledescription.

How to check you have it

  • In probeo: the page reports the aria-braille-equivalent rule, “aria-braille attributes must have a non-braille equivalent”, with serious impact, saying which attribute has no counterpart. It maps to WCAG 4.1.2, Name, Role, Value.
  • By hand: search the source for aria-braille. Each match needs a visible or aria-label name, and each aria-brailleroledescription needs an aria-roledescription on the same element.
  • With a tool: axe DevTools reports the same rule id; the accessibility tree shows the element’s computed name.

The fix

Give the element its ordinary name or role description, and keep the braille attribute as the short form.

<button aria-label="Download report" aria-braillelabel="dl rpt">
  <svg aria-hidden="true">…</svg>
</button>

Done when: every braille attribute has its non-braille equivalent, and the check above comes back clean.

Do not

  • Do not use aria-braillelabel as the only name for a control.
  • Do not add aria-brailleroledescription without the aria-roledescription it abbreviates.

FAQ

When should I use braille attributes at all?

Rarely. They exist for cases where the spoken name reads badly or runs long on a braille display. Most controls should use their ordinary name in both.

Does a visible text label count as the equivalent?

Yes. Any accessible name satisfies it, including the element’s own text content.

Do all screen readers support these attributes?

They are newer additions to ARIA, and support varies. That is one more reason the ordinary name has to be there.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.