Add landmark roles to WordPress admin areas

[joedolson]

Right now, the WordPress admin pages have ARIA landmark roles available for navigation only. This patch adds role="main" to the wpcontent container and role="contentinfo" to the wpfooter container.

[joedolson]

Adds landmark roles in admin

[afercia]

Would be a nice opportunity to fix also the admin menu landmark role, worth noting role=navigation is not allowed on ul elements, see ​http://www.w3.org/TR/html5/grouping-content.html#the-ul-element and should be set on its wrapper (adminmenuwrap).
Worth considering also to move the "Skip to main content" link as first thing inside adminmenuwrap: all content should be inside landmarks.

[joedolson]

That seems totally reasonable. I don't think it should have any consequences for the appearance or behavior of the skip link, so it seems very plausible.

New patch coming.

[joedolson]

Moves navigation role, moves skip link into navigation role.

[SergeyBiryukov]

31450.2.patch​ hides the skip link under Toolbar, see before/after screenshot​.

[joedolson]

Damn, you're right. I was hoping to avoid CSS work on this, but I'll add that to the patch.

[joedolson]

OK. So, this is a stacking context issue. Because the main admin navigation is positioned and has a z-index value, it's placed in a stacking context below the adminbar. Changing the z-index on the admin menu makes the skip to content link work, but then the skip to toolbar link appears behind the adminbar.

Still working on this. The two links need to be in a common stacking context, it seems.

[afercia]

Looking a bit into this, I wouldn't touch this z-index madness :) Ideally, there should be just one stacking context based on a general wrapper element. By the way there would probably be unpredictable consequences, for example about plugins that add items in the admin bar.
One way to solve the issue (tested) is to add a wrapper div e.g.:

<div id="nav-main" role="navigation" aria-label="<?php esc_attr_e( 'Main menu' ); ?>">
<a tabindex="1" href="#wpbody-content" class="screen-reader-shortcut"><?php _e( 'Skip to main content' ); ?></a>
<div id="adminmenuback"></div>
<div id="adminmenuwrap">
<ul id="adminmenu">
...
</ul>
</div>
</div>

This way the new wrapper div will still use the original stacking context, no CSS changes required. Yes it's one more div... I know.

Would like to hear your thoughts about one thing that always bothered me :) the placement of the "Skip to toolbar" link:

<a class="screen-reader-shortcut" href="#wp-toolbar" tabindex="1"><?php _e('Skip to toolbar'); ?></a>

Would it make sense to change its placement conditionally based on is_admin()?
If is admin: output it right after the "Skip to main content" link
If is front end: output it in the admin bar.

[joedolson]

Yes, adding another wrapper had occurred to me, as well. There are *so many* wrappers already, I was reluctant...but I don't see another reasonable alternative. Z-index stacking contexts are a painful rabbit hole.

I think yes, it would make sense to alter the placement of skip to toolbar conditionally; I'll go ahead and integrate that into this patch, since it's fairly closely related along with everything else we're doing.

[joedolson]

Adds new container so skip link can be in appropriate context.

[joedolson]

New patch adds additional container: #adminmenumain surrounding existing admin menu code, to place screen reader shortcut into standard stacking context.

Also moves skip to toolbar link into admin menu context when in admin, but leaves in place in toolbar when on front-end.

[afercia]

Added bonus: we could probably remove tabindex="1" when in the admin :)

[joedolson]

Could, yes. Is there any practical reason that you know of that the tabindex still exists on the main skip to content link? I couldn't see any benefit to that; I'm not sure why it's there. There's no filterable region above the menu header, so no plug-in would be able to insert another link above it. I can't see that it's accomplishing anything.

[joedolson]

Removes tabindex on admin skiplinks.

[joedolson]

Added a new patch to remove tabindex on skiplinks in the admin. I can't see any purpose to it anymore. There's still a benefit to tabindex=1 on the front-end toolbar, but not in the admin.

[afercia]

Replying to joedolson:

Could, yes. Is there any practical reason that you know of that the tabindex still exists on the main skip to content link?

I think it was there just because "Skip to toolbar" had one too.

[joedolson]

Cool. Just had to keep up with the cool kids.

It seemed odd to me; but that does make some sense. Without tabindex, the skip to toolbar would have appeared before the skip to content, which would be less than ideal. Better to have them both in the content in the appropriate tab order instead, definitely.

[afercia]

Reported by one of our testers in the last testing session:

ARIA landmarks work great but I'm assuming there is nothing in the "main" area as it just goes into a navigation role.

Investigating a bit on this and maybe we should disambiguate the 2 navigation landmarks, for reference:
​http://www.w3.org/WAI/GL/wiki/Using_ARIA_landmarks_to_identify_regions_of_a_page
There are cases when a particular landmark role could be used more than once on a page, such as on primary and secondary navigation menus. In these cases, identical roles should be disambiguated from each other using a valid technique for labelling regions (see examples below).

Basically, two same-type landmarks should be disambiguated using headings (if any) or aria-labelledby (if there are visible elements that can be referenced) or aria-label.

I would propose to add aria-label attributes on the 2 navigation roles and remove a couple of duplicated roles, see attached refreshed patch.

Tested witn Firefox + NVDA where pressing "d" jump to the next landmark. Please consider that NVDA automatically reads out the first text available after each landmark so it will read out:

[press d]

Main menu navigation landmark
Skip to main content link

[press d]

clickable Toolbar navigation landmark [see note 1]
list with 5 items
About WordPress subMenu link

[press d]

out of list
main landmark
Help collapsed link [see note 2]

[press d]

content info landmark
Thank you for creating with WordPress visited link . [see note 3]

[press d]

no next landmark

Notes:

1. reads out "clickable" because of tabindex="0", wondering if it's really needed
2. the "Help" tab is the first text in the main content, see discussion about missing h1 in the admin
3. "." is read out as "dot" because it's outside the link

[joedolson]

I think that we can actually add an H1 to the admin fairly easily, just by adding it shown only when is_admin is true in the adminbar, as a wrapper on the site title. I was planning on adding that in an updated patch; but if you're in a good place to do this now, you should do that. I was also going to add an H2 to the screen options panel, to improve the overall heading structure.

Let me know if you can do that now; I won't be able to get to it until later today.

[afercia]

I was thinking maybe better to carefully consider this, adding the missing H1 is essential but maybe should be handled with care, for example considering also what plugins can add in the admin. See discussion on Slack, starting from:
​https://wordpress.slack.com/archives/accessibility/p1426174058001453

[Gab Nino]

Hi Andrea,

Proposed changes for the landmarks looks better. Are the changes available on the site version we are testing? (/trunk/src/wp-admin/).
I agree with you for adding H1 back. I think it is important to provide logical order for the page structure since the section headers <h1 > to < h6> are extremely important landmarks for people who can not rely on a global vision of the page to get an idea of its organization or to navigate through the content without a mouse. It is also recommended by the WCAG 2.0 (​http://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-sequence.html). However, WCAG 2.0 do not consider logical order errors as an accessibility error but rather as a usability error.

I'm not well familiarized with WordPress structure, but I guess adding back the H1 could create legacy issues with plugin added to the admin. What would it be the best way to convince people about getting back the H1?

Have a great day!

[joedolson]

The issues with H1 are pretty straightforward. If we add it in the main content area, where there are currently H2 headings, it will pretty much be inconsistent with every plug-in and theme that creates any kind of settings page. It won't "break" anything; but the heading hierarchy would be different on core WordPress screens from what it is on any plug-in or theme settings page that doesn't update to match. (Many would, but even more wouldn't.)

Alternately, we can add an H1 into the adminbar. This would essentially set the hierarchy back to what it was before the adminbar was created. Most other headings would not need to change. In my opinion, this is a simpler change, and has many, many fewer long-term consequences.

[afercia]

Replying to joedolson:

Alternately, we can add an H1 into the adminbar. This would essentially set the hierarchy back to what it was before the adminbar was created.

Yup, would be OK to restore the heading hierarchy but what about the actual H1 text? The H1 should be the main topic of the screen so, for example, in the Media Library it should be "Media Library" thus the current H2 would be "duplicated". And what text should be used in options screen added by plugins?

[rianrietveld]

Test results from the wapa11y test team on patch 31450.4

Geof Collis: JAWS 14.5 IE 11
ARIA landmarks work great but I'm assuming there is nothing in the "main" area as it just goes into a navigation role.

John Sexton:

Supernova V14 + IE11 + Win7
Supernova found 6 landmarks through its list landmarks feature.
main menu navigation: top of page
navigation: 11 items
main: top of main column, including top navigation
navigation: joins top navigation
top navigation toolbar navigation: 4 items
content info: thank you message
This only giving 4 effective landmark points:
main menu navigation: which is top of page
navigation: which is the main menu
main + navigation + top navigation toolbar + navigation: top navigation
content info: footer

NVDA + IE11 + Win7
Using the NVDA key D, & shift+D I can navigate to 4 points:
main menu navigation: Top of page, where two skip links are.
Navigation, where there are 11 list items
main, this one gets confusing, as it reads: main landmark, navigation landmark, top navigation toolbar, navigation landmark list with 4 items ...
content info: thank you message

Suggestions:
Remove main menu navigation as it is effectively top of page and most assistive technology includes controls for top of page.

<div id="adminmenumain"><!-- removed: role="navigation" aria-label="Main menu" -->

Change the first navigation to main menu navigation

<div id="adminmenuwrap" role="navigation" aria-label="Main menu"><!-- added: aria-label="Main menu" -->

Move the main to the start of the main content area IE either the help/screen options links (as below) or the first heading.

<div id="wpcontent"><!-- remove:  role="main" -->
<div id="wpbody-content" role="main" aria-label="Main content" tabindex="0"><!-- added: role="main" -->

Remove one of the second navigations leaving only one navigation for the top navigation toolbar

<div id="wpadminbar" class="nojq nojs"><!-- remove:  role="navigation" -->

Gabriela Nino de Rivera Torres
Tools: VoiceOver+Safari 8.0.3 on Mac. FF+NVDA and Windows XP.

Results:
Navigation in both Safari and NVDA was confusing because the names of the roles don't give enough context to the user. In some cases like main or navigation it is really difficult to imagine were I'm heading if I click on those links. Most of the roles sent the user to the top of the page but there is not a role letting the user to go directly to the main content. I agree with John Sexton's suggestions and I would like to add to his list to change the name role for the footer (contentinfo) to something that will explain better the destination of the link like web site information or WordPress information, etc.

Landmarks with Safari and VoiceOver:
Using the rotor, I opened the list menu for landmarks. Here is the list of landmarks:
(I tried to make a print screen of the list, but I could not use shift+command+4 while VoiceOver is on)

Role -> destination
Main menu navigation -> skip to main content link
navigation -> dashboard
main -> WordPress logo
navigation -> somewhere at the top I think
Top navigation toolbar. navigation (not sure where is this one coming from)
content information -> footer information

Landmarks with FF and NVDA: see image:

Michelle DeYoung

62 <div id="wpwrap">
63 <div id="adminmenumain" role="navigation" aria-label="Main menu">
64 <a href="#wpbody-content" class="screen-reader-shortcut">Skip to main content</a>
65 <a href="#wp-toolbar" class="screen-reader-shortcut">Skip to toolbar</a>
66 <div id="adminmenuback"></div>
67 <div id="adminmenuwrap" role="navigation">
68 <ul id="adminmenu">

Remove this landmark role on line 67. Line 63 has a landmark role for the Main Menu Navigation already established.

102 </div>
103 </div><div id="wpcontent" role="main">

Move Main Landmark role at line 103 to Line 133 and add it to the div element that has the aria-label of “Main content”

105 <div id="wpadminbar" class="nojq nojs" role="navigation">
106 <div class="quicklinks" id="wp-toolbar" role="navigation" aria-label="Top navigation toolbar." tabindex="0">
107 <ul id="wp-admin-bar-root-default" class="ab-top-menu">

Remove this landmark role on line 105. Line 106 already had the Top Navigation Toolbar established.

131 <div id="wpbody">
132
133 <div id="wpbody-content" role=”main” aria-label="Main content" tabindex="0">
134 <div id="screen-meta" class="metabox-prefs" role=”navigation” aria-label="Contextual Help Tab”>
135
136 <div id="contextual-help-wrap" class="hidden" tabindex="-1" aria-label="Contextual Help Tab”>
137 <div id="contextual-help-back"></div>
138 <div id="contextual-help-columns">

Added role=”main” from Line 103 . The aria-label already was in the div element.
Add the aria-label from Line 136. Also add the role=”navigation”. One could argue that it might be suited for role=”complementary” as well.
Move the aria-label to Line 134

Note from Rian:
Andrea fixed the double navigation landmark, Michele and Gabriele mentioned, in patch 31450.5.patch

Tobias Clemens Häcker:
Tested with: Wave Toolbar 1.1.8, Browser Mozilla, Windows7

The roles to navigation for the main content: role="main"
and for the footer: role="contentinfo" are displayed correctly.
In the end they add the voice output like "main content" but a more specific voice output that sums up the content of the area would be better. It works fine for navigation.
Area roles are probably more relevant for SEO than for accessibility.

Remarks Rian:

The labeling is confusing. patch 5 is an improvent, but the content of the labels need to give more information about the context. Michelle, Gabriela and John gave some extra improvements.
In the team we discussed if landmarks are used or not, because some testers never use landmarks.
Does a screen reader user then actually know what it means when the landmarks are read out in the content.
Like one tester mentioned, while testing something else: "I see in braille the text: "main content", and I can't figure out where that came from".

@afercia found some statitics:
​http://webaim.org/projects/screenreadersurvey5/
​http://www.paciellogroup.com/blog/2013/02/using-wai-aria-landmarks-2013/

[SergeyBiryukov]

#27638 was marked as a duplicate.

[afercia]

Discussed in the last accessibility team chat and we would recommend this for commit. Just one thought, we're currently proposing this:

<div id="adminmenumain" role="navigation" aria-label="Main menu">
<div class="quicklinks" id="wp-toolbar" role="navigation" aria-label="Toolbar" tabindex="0"> 
<div id="wpbody" role="main">           <-- no label
<div id="wpfooter" role="contentinfo">  <-- no label

but wondering if "main" and "contentinfo" need labels too, maybe not? The first two ones make sense to disambiguate the 2 navigation roles. But maybe it would be a bit weird fur users hearing "contentinfo" announced. Open to suggestions. [edit] Of course this can be done in following iterations. Thanks very much.

[ocean90]

@afercia Which patch should be ready for commit?

[afercia]

@ocean90 31450.5.patch
Add ARIA landmarks to identify regions in the admin screens:

• navigation
• navigation
• main
• contentinfo

Use aria-label attributes on the 2 navigation roles and remove a couple of duplicated roles, to disambiguate the 2 navigation roles.

Landmarks help assistive technology users orient themselves to a page and help them navigate easily to various sections of a page. They also provide an easy way to skip over blocks of content.

[DrewAPicture]

@afercia: 31450.5.patch​ still applies. Does that fully meet your expectations? What's left to do before we can move this for commit consideration?

[afercia]

@drew nothing left here. Discussed, tested and recommended for commit consideration by all accessibility team members :) thanks

[ocean90]

In 31955:

Accessibility: Add landmark roles to WordPress admin areas.

props afercia, joedolson.
fixes #31450.