Accessibility issues with handbook layout

[adamwoodnz]

From Alex Stine on Slack:

Here is a quick list:

• The Improve it on GitHub link is not descriptive enough.
• Same for See list of changes link.
• The link NextGetting Started has no spacing and is announced as 2 words instead of 3.
• The handbook chapters heading 2 is the first heading on the page. This design needs to be reworked, no questions asked.
• The skip to main content link does not land you in the main content, it lands you in all the items before the main heading 1.
• The main landmark should not wrap navigational elements such as the Chapters heading 2 or the search form above it.

[adamwoodnz]

cc @fcoveram @ndiego, not sure how hard this will be to fix yet

[ndiego]

• The handbook chapters heading 2 is the first heading on the page. This design needs to be reworked, no questions asked.
• The skip to main content link does not land you in the main content, it lands you in all the items before the main heading 1.
• The main landmark should not wrap navigational elements such as the Chapters heading 2 or the search form above it.

Are these three items due to the fact that the Chapters list is inside <main> and not wrapped in an <aside> tag? I was comparing the current layout with other sites like Mozilla and the React docs. In both cases, they have a heading that is not an H1 that is the first on the page, but, it's not in <main> and is wrapped in an <aside>.

cc @alexstine

[alexstine]

@ndiego It would be more valid if it were wrapped in an <aside> tag but it would be even better if the heading 1 came first. Headings should represent importance on a page so I always have argued that the <aside> should appear directly after <main> in the DOM.

[adamwoodnz]

Pretty sure I'll be able to reorder the content and keep the visual layout. It's next on my list after the ToC styling.

[adamwoodnz]

Should the Table of Contents also be an aside?

Something like

<header { including breadcrumbs and search } >
<main>
<aside class="chapter-list">
<aside class="table-of-contents">
<footer>

The visual layout will be tough to achieve if so. It would help greatly if it was immediately after the h1 within main.

[alexstine]

@adamwoodnz I think they are both wrapped in <nav> by default? If this is the case, they don't need their own <aside>. There should really only ever be one <aside> on a page if possible.

[adamwoodnz]

• The link NextGetting Started has no spacing and is announced as 2 words instead of 3.

Are the 'Previous' and 'Next' bits actually useful with a screen reader? I notice there is a rel="next" attribute on the anchor too.

Trying to decide whether to add punctuation (the design has a middot, but it's not implemented as text), or make the link content only the page title for screen readers.

[alexstine]

Next and previous are useful labels if it conveys specific actions. For example, Next section: section name or Next chapter: chapter name.

[adamwoodnz]

• The Improve it on GitHub link is not descriptive enough.
• Same for See list of changes link.

What would you suggest for these?

Help improve this document
See the history of this document

Visual for designers:

[alexstine]

@adamwoodnz

The Improve it on GitHub link is not descriptive enough.

Improve on GitHub: doc title here

Same for See list of changes link.

Document revisions: doc title here

It needs to convey current context.

[adamwoodnz]

The layout updates have just been deployed, GitHub links and pagination to follow.

[alexstine]

@adamwoodnz Would it be possible to also move the meta information inside the complementary landmark? It would likely be more discoverable just above the Chapters heading. Other than that, really much improved. Thanks.

[adamwoodnz]

Would it be possible to also move the meta information inside the complementary landmark?

This will be difficult to achieve as visually the complementary landmark sits to the left of main in a sidebar. It will take quite a refactor, but could be possible.

Issue created.