Docs site accessibility enhancements
AleksandrHovhannisyan opened this issue · comments
I noticed two quick enhancements that may be worth looking into for the docs site. I'd be happy to take these on if that's okay! Summoning @BenDMyers to make sure I didn't miss anything/accidentally propose something inaccessible.
Edit: Disregard—I didn't notice we had .sr-only spans for the emoji Feature set table and the emoji legend
It may be worth hand-rolling a custom HTML table for the feature set table. This would allow us to do two things:
1. Set scope="col" on the ths so that screen readers repeat the column when reading its corresponding value.
2. Set aria-labelledby on the emoji and reference the key/legend down below (with aria-hidden on the legend to avoid duplicate narration for screen reader users).
> Note: Per https://w3c.github.io/aria-practices/#naming_with_aria-labelledby, setting aria-hidden should be safe since aria-labelledby "incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string."
As part of this refactor, to cut down on repetition, we may want to pull out the feature set into a JSON data file and add a separate JSON data file for the legend. The features map to the emoji, and the emoji map to their meaning. That way, we can easily loop over both pieces of data in that file.
Use navs for sidebar navigation
We may want to wrap the two sets of links in the sidebar in navs and set an aria-labelledby pointing to the group titles we currently have (GUIDES and REFERENCE). I propose the same approach here: set aria-hidden on the labels, give them IDs, and point to them from the navs.
Hey, @AleksandrHovhannisyan! This is excellent input.
I believe most of the emoji concerns have been addressed with shortcodes already. If you check the rendered markup for the table, you'll find that each emoji has an adjacent .sr-only span with the same text that's in the legend. It's less auto-magic, but it seems to work sufficiently — please let me know if you think it needs improvement, though! I'm hesitant to use aria-labelledby here, for two main reasons: one, aria-labelledby and similar attributes aren't expected to apply to static text elements, and two, because wiring up anything more complex brings the authoring experience from ergonomic Markdown authoring.
I'm in huge support of the use of nav and aria-labelledby for the sidebar, though it may be worth splitting that out into its own issue.
Oh, I completely missed the sr-only spans. That works!
You mentioned that we should find a way to add scope=col to the header cells, and I agree with that. Preferably, we might be able to find a markdown-it extension that lets us add that? Alternatively, I can write an extension like that, but it likely wouldn't be great 😅
A markdown-it plugin would be great! I've had to hand-roll tables for this reason, and it's always such a pain 😞