kbd shortcode has accessibility issues

[cwickham]

For JS formats, e.g. HTML, the kbd shortcode sniffs the users OS and inserts icons for the shortcut keys, e.g. {{< kbd mac=Shift-Command-O >}} becomes ⇧ ⌘ 0.

Replacing the words with icons is making things much worse for those using screen readers, e.g. (thanks @ateucher and @gtritchie ) for ⇧, ⌘, ⌃, ⌥ NVDA on Windows reads: "upwards hollow arrow", "Mac command key", and says nothing about the Ctrl or the option symbols.

[cscheid]

We should definitely fix this, and I can take point, but I could use some help. @ateucher, @gtrichie, do you mind giving me some suggestions here? Thanks!

[gtritchie]

The safest approach for screen readers is to use text, so:

Shift
Command (macOS)
Windows Logo Key or Windows Key
Option or Opt (macOS)
Alt (Windows)
Ctrl or Control
Page Up, Page Down
Home, End
Delete
Backspace
Enter, Return
Caps Lock
ESC, Esc

https://support.apple.com/en-ca/guide/mac-help/cpmh0011/mac

[cscheid]

@gtritchie Ok, let me rephrase. Is there a way to keep the graphical output and indicate to screen readers what the screen-readable content is?

[gtritchie]

Let me do some tinkering and I'll reply back here in a bit.

The keyboard shortcut symbols are, I'd argue, not particularly accessible in general, it's not just a concern for screen reader users.

That said, let me see if I can come up with a usable pattern.

[gtritchie]

The simplest approach I can come up with is to mark the symbols themselves as hidden from screen readers, and include the text representation adjacent to them, visually hidden, but still in the accessibility tree.

You'll need to define a visually-hidden css class (or can use the one from bootstrap, etc.). Here's a typical example from https://piccalil.li/quick-tip/visually-hidden/

.visually-hidden {
  border: 0;
  clip: rect(0 0 0 0);
  height: auto;
  margin: 0;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
  white-space: nowrap;
}

Another example: https://css-tricks.com/inclusively-hidden/, and a longer discussion https://www.scottohara.me/blog/2023/03/21/visually-hidden-hack.html. Another interesting read on this topic: https://benmyers.dev/blog/native-visually-hidden/

Then, to use the Shift symbol, do this:

<span aria-hidden="true">⇧</span><span class="visually-hidden">Shift</span>

This looks exactly the same but will read reliably with any screen reader.

You could also consider adding a tooltip so a mouse-user who isn't familiar with the symbols can hover over it and get a hint, but that's probably overkill (and doesn't help a keyboard-only user).

<span title="Shift" aria-hidden="true">⇧</span><span class="visually-hidden">Shift</span>

[gtritchie]

An alternative to that is to use images instead of symbol characters, and use alt="Shift". That's what Apple did on this page: https://support.apple.com/en-ca/guide/mac-help/cpmh0011/mac

[cscheid]

This is super helpful. I'll give this a shot in the next couple of days and get back to you all. Thanks!

[mcanouil]

Maybe of interest: https://github.com/orgs/community/discussions/17926