ARIA Rule

aria-braillelabel must have a matching text label aria-braille-equivalent

aria-braillelabel and aria-brailleroledescription let you give a braille display a shorter or contracted version of a control's name or role. They sit on top of the ordinary name, they do not replace it. If the element has a braille label but no accessible name, speech users get nothing at all and braille users get a label with no fallback.

WCAG 2.2 A 4.1.2 Name, Role, Value

Websight reports this as aria-braille attributes must have a non-braille equivalent

Who it affects

Someone using a screen reader with speech only reaches a button that has a braille label and a blank spoken name. They hear button and nothing else.

Someone using a braille display on a browser that does not support the braille attributes yet falls back to the ordinary name, which is empty, so the control is unlabelled for them too.

Someone using voice control cannot say the control's name because it only exists in braille form.

Broken versus fixed

Both examples are live and rendered in a sandboxed frame. The broken one is deliberately broken.

Broken

The cross is obvious to a sighted person. A screen reader announces just: button. The braille label is set, but there is no spoken name for it to be a shorter form of.

Fixed

Announced: Close, button. A braille display that understands aria-braillelabel shows cls instead; one that does not shows Close.

Show the markup behind both examples
Broken
<style>body{font-family:system-ui;padding:16px;margin:0}.toast{display:flex;align-items:center;gap:12px;max-width:320px;padding:12px 14px;border:1px solid #cbd5e0;border-radius:8px;background:#f7fafc}.x{margin-left:auto;border:0;background:none;padding:4px;cursor:pointer}</style>
<div class="toast" role="status">
  Settings saved
  <button class="x" aria-braillelabel="cls">
    <svg width="14" height="14" viewBox="0 0 14 14"><path d="M2 2l10 10M12 2L2 12" stroke="#2d3748" stroke-width="2"/></svg>
  </button>
</div>
Fixed
<style>body{font-family:system-ui;padding:16px;margin:0}.toast{display:flex;align-items:center;gap:12px;max-width:320px;padding:12px 14px;border:1px solid #cbd5e0;border-radius:8px;background:#f7fafc}.x{margin-left:auto;border:0;background:none;padding:4px;cursor:pointer}</style>
<div class="toast" role="status">
  Settings saved
  <button class="x" aria-label="Close" aria-braillelabel="cls">
    <svg width="14" height="14" viewBox="0 0 14 14"><path d="M2 2l10 10M12 2L2 12" stroke="#2d3748" stroke-width="2"/></svg>
  </button>
</div>

Test it by hand in two minutes

  1. Search the page source for aria-braillelabel and aria-brailleroledescription. Most sites have none, so each hit is worth a look.
  2. For each hit, check the same element also has an ordinary name: visible text, an aria-label, an aria-labelledby, or an alt on the image inside it.
  3. If aria-brailleroledescription is present, check aria-roledescription is also present on the same element.
  4. Turn on VoiceOver or NVDA and Tab to the element. You should hear a real name, not just the role.

The fix

Before
<button aria-braillelabel="cls"><svg aria-hidden="true">...</svg></button>
After
<button aria-label="Close" aria-braillelabel="cls"><svg aria-hidden="true">...</svg></button>

Write the normal name first. Then decide whether the braille version is worth having at all; most of the time the ordinary name is fine on a braille display too.

Braille role description without a spoken one

Before
<div role="group" aria-brailleroledescription="sld">...</div>
After
<div role="group" aria-roledescription="slide" aria-brailleroledescription="sld">...</div>

aria-brailleroledescription needs aria-roledescription on the same element, and that in turn needs a real role.

Common mistakes

  • Treating aria-braillelabel as a substitute for aria-label because the braille version looked shorter and neater.
  • Copying the braille attributes from a component library sample without the aria-label that went with them.
  • Putting the braille label on the element and the spoken label on a different one.
  • Assuming every browser and screen reader honours the braille attributes; support is still patchy, so the ordinary name is what most people get.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is one of the checks for:

The scanner can see a braille attribute on an element whose accessible name (or aria-roledescription) is empty. It cannot judge whether the braille text is a sensible contraction of the spoken one. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

not run A aria-roledescription must only be used on elements with a role aria-roledescription aria-roledescription lets you swap the word a screen reader uses for a role: say slide instead of group, or page instead of tab panel. A ARIA buttons, links and menu items need a name aria-command-name When you give an element role="button", role="link" or role="menuitem", you are promising assistive technology that it is a control.

Scan your own page for this and 63 other checks

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.