Make WordPress Core

Opened 3 months ago

Last modified 3 weeks ago

#47123 assigned defect (bug)

The post(s) navigation landmark needs to be labelled

Reported by: afercia Owned by: williampatton
Milestone: 5.3 Priority: normal
Severity: normal Version:
Component: Bundled Theme Keywords: has-screenshots
Focuses: accessibility, template Cc:

Description (last modified by afercia)

Basically all the Bundled Themes use previous / next navigation in the single post and pagination links in the posts / comments archives.

The markup output is responsibility of the core function _navigation_markup, which prints out an unlabelled <nav> element:

<nav class="navigation post-navigation" role="navigation">

Why it is a problem

This <nav> element defines an ARIA landmark by default: landmarks help assistive technology users to perceive the page main sections and jump through them. However, when a landmark is used more than once in a page, it needs to be distinguished from the other ones to let users understand what the landmark is about.

For example, in Twenty Nineteen there may be up to 4 navigation landmark, plus the WordPress toolbar when logged in. These landmarks are well labelled except the post / posts navigation one. See screenshot from the VoiceOver landmarks list:


Users won't have a clue what that landmark region is about.

Suggested solution

To properly label this landmark, there's the need to add an aria-label attribute with a meaningful text. The following W3C examples clarify further:

W3C landmarks example with detailed instructions:

If a specific landmark role is used more than once on a web page, it should have a unique label.
Avoid using the landmark role as part of the label. For example, a navigation landmark with a label "Site Navigation" will be announced by a screen reader as "Site Navigation Navigation". The label should simply be "Site".

W3C example using equivalent HTML5 sectioning elements
e.g. main, nav, aside ... define ARIA landmarks by default


_navigation_markup is used by other functions with different context: single views, archies, post, comments...:

  • the_post_navigation() / get_the_post_navigatio()n
  • the_posts_navigation() / get_the_posts_navigation()
  • the_posts_pagination() / get_the_posts_pagination()
  • the_comments_navigation() / get_the_comments_navigation()
  • the_comments_pagination() / get_the_comments_pagination()

Therefore, the aria-label value should be meaningful for all these different cases.

Note: in some cases, the <nav> element contains also a visually hidden heading, e.g.:
<h2 class="screen-reader-text">Post navigation</h2>

In these cases it's worth evaluating to use aria-labelledby on the <nav> element, targeting the hidden heading.

I'd like to hear the accessibility team thoughts on this. From a technical perspective, this would be a bit challenging, as _navigation_markup is used in different scenarios.

Note: filing under the "Bundled Theme" component even if this is output by core, as it impacts themes templating. Please do feel free to assign to a more appropriate component if desired.

Change History (7)

#1 @afercia
6 weeks ago

  • Description modified (diff)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

5 weeks ago

#3 @SergeyBiryukov
5 weeks ago

To properly label this landmark, there's the need to add an aria-label attribute with a meaningful text.

Could the existing post type / taxonomy label items_list_navigation be used here? The defaults are:

  • Post types, non-hierarchical: Posts list navigation
  • Post types, hierarchical: Pages list navigation
  • Taxonomies, non-hierarchical: Tags list navigation
  • Taxonomies, hierarchical: Categories list navigation

#4 @afercia
5 weeks ago

@SergeyBiryukov interesting, thanks! I'm afraid these existing labels wouldn't be appropriate though because:

  • we need a label also for comments
  • the word list suggests there's a list: that's true for the posts tables (where these labels are currently used) but in this navigation there's no list, there's just a navigation
  • more importantly: the labels should not contain the word navigation: that's already automatically announced by screen readers because of the <nav> element

For example, in the case of comments, the ideal markup would be:

<nav class="navigation comment-navigation" role="navigation" aria-label="Comments">
	<h2 class="screen-reader-text">Comments navigation</h2>
	<div class="nav-links"> ... </div>

Maybe we could try to use the object plural name, not sure if that's reliable enough to have a meaningful name for the navigation.

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

3 weeks ago

#6 @williampatton
3 weeks ago

  • Owner set to williampatton
  • Status changed from new to assigned

#7 @afercia
3 weeks ago

  • Milestone changed from Awaiting Review to 5.3

Discussed during today's accessibility bug scrub. Moving to 5.3 consideration.

Note: See TracTickets for help on using tickets.