Aria-braillelabel and brailleroledescription must be paired

Do not use aria-braillelabel without a name or aria-brailleroledescription without aria-roledescription

Intro:

Use ARIA braille attributes only when the element already exposes the equivalent non-braille information. This appears on custom widgets, images, and controls where braille output is tailored. It primarily affects braille display users and can create inconsistent behavior across assistive technologies.

Why It Matters

Braille displays can present shortened or alternate labels and role descriptions. If a control lacks a real accessible name or role description, the braille-specific properties may be ignored, leaving users with nothing meaningful.

Assistive technologies do not handle these attributes uniformly. Providing the base name and role description ensures the accessibility tree is complete, satisfying WCAG 2.2 expectations for Name, Role, Value (4.1.2).

Common Causes

• Adding aria-braillelabel to an element that has no accessible name.
• Using aria-brailleroledescription without a matching aria-roledescription.
• Placing braille attributes on the wrong node (e.g., parent container instead of the interactive element).
• Relying on braille attributes as the only labeling mechanism.
• Leaving legacy braille attributes in code after UI changes.

How to Fix

1. Locate occurrences:
   • Search for [aria-braillelabel] and [aria-brailleroledescription] across the codebase.
2. For aria-braillelabel:
   • Ensure the same element already has an accessible name via one of: aria-label, aria-labelledby, native text/label, or alt (for images).
   • Keep the braille label a concise, braille-friendly equivalent of the accessible name.
3. For aria-brailleroledescription:
   • On the same element, provide aria-roledescription with the human-readable role description.
   • Make the braille role description a short, clear braille equivalent (e.g., an abbreviation) of aria-roledescription.
4. Put attributes on the correct element:
   • Apply braille properties to the focusable/semantic element itself, not its parent/child.
5. Remove when unnecessary:
   • If the braille attribute adds no value or is incorrect, delete it.
6. Recommendation:
   • Use braille properties sparingly. Do not mask or replace standard roles/labels. They are supplements, not substitutes.

How to Test

Keyboard check:

• Tab through interactive elements. Confirm each focusable control has a visible label or clear text and a programmatic name (use devtools or accessibility inspectors to verify the name).

Screen reader check:

• Desktop: With NVDA or JAWS, navigate to the element. Confirm the control exposes a correct Name and Role. Verify aria-roledescription (when used) is announced or reflected in the accessibility tree.
• Inspect the element in browser accessibility tools: confirm the Computed Name is present and the role is correct; note that braille-specific values may not be shown in all tools.

Mobile/touch check:

• iOS (VoiceOver) or Android (TalkBack): Move focus to the element. Ensure it has a usable spoken name and correct role. If a braille display is available, confirm the braille label/role corresponds to the non-braille equivalents.

Quick automated triage (recommendation, not exhaustive):

• Flag elements with aria-braillelabel that lack aria-label/aria-labelledby and also lack obvious native naming.
• Flag elements with aria-brailleroledescription that lack aria-roledescription.

Checklist:

• The element has a programmatic accessible name when aria-braillelabel is present.
• aria-brailleroledescription is only used when aria-roledescription is present on the same element.
• Braille attributes live on the correct interactive/semantic node.
• Labels/roles remain accurate, concise, and consistent across AT.
• Unneeded or misleading braille attributes are removed.

Good Example

<!-- aria-braillelabel with a proper accessible name -->
<button class="rating-btn" aria-label="4 out of 5 stars" aria-braillelabel="****">★</button>

<!-- aria-brailleroledescription paired with aria-roledescription -->
<section role="group" aria-roledescription="card" aria-brailleroledescription="crd" aria-labelledby="card-title">
  <h2 id="card-title">Billing Summary</h2>
  <p>Total due: $48.20</p>
</section>

Why it’s good:

• The button has a valid accessible name via aria-label; the braille label is a concise equivalent.
• The group has aria-roledescription and a matching braille role description; it is also labeled by a heading.

Bad Example

<!-- No accessible name; braille attribute used as the only label -->
<div class="icon-only" role="button" aria-braillelabel="Pay"> </div>

<!-- Braille role description without its non-braille counterpart -->
<div role="region" aria-brailleroledescription="sec">Order details here</div>

What’s wrong:

• The custom button lacks an accessible name (no aria-label/aria-labelledby or text). The braille label cannot substitute for it.
• The region exposes a braille role description without aria-roledescription.

Quick Checklist

• When aria-braillelabel is present, the element has an accessible name.
• When aria-brailleroledescription is present, aria-roledescription is also present.
• Braille attributes are on the same element that users focus or interact with.
• Non-braille (spoken) name and role remain accurate and understandable.
• Braille equivalents are short and meaningful.
• Do not rely on braille properties as the sole source of labels/roles.
• Remove braille attributes that no longer serve a purpose.