steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-10 14:01:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Adds accessible titles to nested page nav toggle (#950)

Browse Source 
Adds accessible nav elements for nested pages

Why are these changes being introduced:

* The current links to show/hide the nested pages use a visual only
  svg image with no accessible affordance provided so screenreaders
  will not be able to provide appropriate context for users as to what
  they should expect when clicking these links
* You can see the problem by running a tool like ANDI on the current
  main branch of this repository and then running it again on this
  branch. ANDI shows what a screenreader would read.
* You can also use a tool like Voiceover to hear the importance of what
  this introduces to users that use that technology. Before this change,
  Voiceover would read all of these navigation links as
  "link image just-the-docs" but with this change it will read
  `link image toggle links in <categoryName> category`

Relevant ticket(s):

* This was discussed as part of the larger WCAG compliance ticket
  https://github.com/just-the-docs/just-the-docs/issues/566

How does this address that need:

* This adds an `aria-label` to the link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label

Document any side effects to this change:

It appears it might be prefereable to use `aria-labelledby` whenever
possible, but from what I can tell these links are just the visual cue
of the svg with no other affordance given to users to understand what
they'll do so there is nothing to point `aria-labelledby` at.

An `svg` title was considered, but in reading more about it it seemed
like `aria-label` was more appropriate as it puts the label on the `a`
rather than the `svg` which feels more accurate.

* https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title
* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby

Co-authored-by: Matt Wang <matt@matthewwang.me>
This commit is contained in:
Jeremy Prevost 2022-09-06 14:57:34 -04:00 committed by GitHub
parent c3344441aa
commit 84179b0a33
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 6 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
_includes/nav.html
View File

@ -62,7 +62,9 @@
{%- unless node.nav_exclude -%}
<li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
{%- if node.has_children -%}
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
</a>
{%- endif -%}
<a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
{%- if node.has_children -%}
@ -76,7 +78,9 @@
{%- unless child.nav_exclude -%}
<li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
{%- if child.has_children -%}
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ child.title }} category">
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
</a>
{%- endif -%}
<a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
{%- if child.has_children -%}