WCAG Compliance

[dking-after]

I'm finding this theme to be very capable. However, one thing that presents an issue is that the built-in styling generates errors when evaluating for WCAG compliance (you can analyze the Just the Docs pages with something like the WAVE plugin for a quick read). With WACG 2.2 coming out later in 2021, there will probably be renewed attention to accessibility issues and, for larger organizations in many countries, compliance with 2.1 is already mandated.

Overall, the default style has a lot of positives: structural elements are strong, keyboard nav works, etc. The chief area for improvement seems to be contrast. It shows up in several areas, including code blocks, labels, buttons.

Obviously, I can (and will) modify SCSS to address this on my site, but it might be worth looking at tweaking the default variables and elements to be WCAG-friendly out of the box. That way Just the Docs users create more accessible sites without having to be well-versed in standards.

Thanks for considering this.

[mattxwang]

Just circling back to this - now that maintenance is more active, I do want to really emphasize our approach to accessibility. Going to pin this issue - would love to have more people chime in!

(I'm happy to work on this, and in particular tweak our defaults; would like more maintainer input, particularly from those with backgrounds in design)

[JPrevost]

In addition to the contrast issue, which as noted are relatively easily solvable, I've currently noted two additional issues I think would be great to see addressed (and I'm not opposed to putting engineering resources into resolving them if the maintainers are interested).

• The svg images in the navigation to signify collapsing the links to sub pages don't have text readable by screenreader but are also not removed from being tabbed to which means users tab to a link with no text and they have to either skip it or guess what it will do. I believe this is fixable by adding a title element to the svg element similar to:

<svg viewBox="0 0 24 24" title="toggle links in {{ node.title }} category">
  <use xlink:href="#svg-arrow-right"></use>
</svg>

The specific wording is my example is bit awkward, but something like that is one possible way to resolve that. (svg title is just one option and others could be considered if that isn't desired. It seemed the easiest way to address this with my limited knowledge of the code base.

• Tab order in general is problematic for screen readers. You have to tab through all of the navigation to get to the main content of a page. Once you select a page, you need to tab through it all again. The best way to resolve this might be to have the content order be the desired tab order... which means a significant change to the main layout file (i.e. moving the navigation in the html after the main content is likely a better dom order but that would require both moving the html blocks and updating css and/or introducing a breaking change to the theme by changing where navigation shows up. There may be simpler ways to address this by including a "jump to main content" link as described here which would be much less work (I haven't confirmed it would fully address the tab order issues I've noted but would be much less intrusive if it works).

If the maintainers would be interested in working through these issues together, I'd be happy to provide Pull Requests to discuss options further over code.

[mattxwang]

Hi @JPrevost, thanks for making your comment! I agree that these are both things we should resolve. I would certainly be open for a PR for either!

Re: svg titles, My understanding is that the <title> element should be used instead of the title attribute (I don't see that as part of the SVG element spec).

Re: tab order, I'll have to think about it a bit more, but an exploratory PR is a great idea!