Skip to content link missing in many pages or not working properly

[afercia]

"Skip links" are one of the most simple and better known ways to improve accessibility for keyboard users and assistive technologies users. They allow to bypass blocks of content that are repeated on multiple pages, typically: navigation menus.

They're implemented since years in WordPress core and the bundled themes. They're also part of the WCAG recommendation:

Success Criterion 2.4.1 Bypass Blocks
​https://www.w3.org/TR/WCAG21/#bypass-blocks

In order to be effective, a skip link used to bypass the top navigation needs to:

• be the first focusable element in a page
• be revealed on focus
• point to the main content in the page

Far from pretending to be a complete analysis of all the .org network pages, I've gone through the main pages linked in the main navigation menus. To recap:

• Home: no skip link
• Showcase: no skip link
• Themes: no skip link
• Plugins: skip link is not the first focusable element
• Mobile: no skip link
• Support: skip link is not the first focusable element
• Get involved (Make): no skip link
• About: skip link is not the first focusable element and it doesn't appear on focus (conflicts with clip-path: inset(50%); inherited by social-icons.css)
• Blog: no skip link
• Hosting: no skip link

I realize the .org network is made of different templates coming from different sources and I guess it's a complicated setup. However, it would be great to make sure the skip to content link is actually present in all pages and works properly.

[tellyworth]

be the first focusable element in a page

This means it needs to go before <div id="head-search"> in the wporg-header, is that correct? Can it go before the h1?

[tellyworth]

One possible solution as applied to the plugins directory

[afercia]

@tellyworth thanks for looking into this!

Can it go before the h1?

Yes. it does need to be before the .org logo h1.

[tellyworth]

In 8227:

Plugin dir theme: move skip-link so it's the first focusable element on the page.

See #4109

[tellyworth]

@afercia I've deployed this for the plugin directory only as a test. Can you confirm that it's the correct fix please? If so I'll use a similar method for other sites.

[afercia]

@tellyworth thank you. Looks good to me! Just two considerations:

• the positioning is a bit off because #wporg-header has a position: relative; so the top position of the skip link is based on this. Not sure position: relative; is really necessary?
• maybe in the future worth revisiting the "Skip to toolbar" link which has a tabindex="1" attribute so when tabbing it's actually the first "tabbable". It behaves differently compared to the bundled themes because:
  • in the bundled themes, the toolbar is displayed only to logged-in users: in the accessibility team we discussed this a long time ago and agreed it is acceptable
  • instead, in some sections of .org, the toolbar is always displayed: also non logged-in users will get the "Skip to toolbar" link before the "Skip to content" link, which is a bit unexpected. Can't think of a simple solution though.

[tellyworth]

Replying to afercia:

• the positioning is a bit off because #wporg-header has a position: relative; so the top position of the skip link is based on this. Not sure position: relative; is really necessary?

I don't know what a suitable positioning would be. Given that the header is reused across many sites, let's treat that as a separate issue.

• instead, in some sections of .org, the toolbar is always displayed: also non logged-in users will get the "Skip to toolbar" link before the "Skip to content" link, which is a bit unexpected. Can't think of a simple solution though.

I thought tabindex="0" might do the trick given that it indicates DOM ordering, but it turns out no, that doesn't override an explicit tabindex. So yeah, I don't have a solution for that either. Thanks for those points though, that's all useful to know. I think we can call r8227 an incremental improvement on what existed prior, even though there's scope for further design improvement. I'll see about deploying an equivalent fix to those other sites in the meantime.

[tellyworth]

In 8237:

Showcase theme: add skip-to-content link.

There's some missing CSS needed for this to be visible when focused.

See #4109

[tellyworth]

In 8238:

Theme directory theme: add skip-to-content link.

See #4109

[tellyworth]

In 8239:

Support: add skip-to-content link to header.

See #4109

[afercia]

@tellyworth thank you.

There's some missing CSS needed for this to be visible when focused.

Please note the screen-reader-text CSS ruleset should be updated everywhere to the latest used in core. Also, on some pages, plugins add their own stylesheet (e.g. social-icons.css) with their own screen-reader-text ruleset. This may produce conflicts and make the skip link not appear when focused.

The ruleset in core now uses clip-path: inset(50%); so when some visually hidden element needs to be revealed, also clip-path needs to be reset to clip-path: none;. More details on ​https://make.wordpress.org/core/2017/10/22/changes-to-the-screen-reader-text-css-class-in-wordpress-4-9/

[tellyworth]

In 8241:

Main: move skip-to-content link so it's the first focusable element.

Needs CSS work.

See #4109

[tellyworth]

In 8244:

Themes: fix rosetta headers broken by earlier skip-to-content commit r8238

See #4174, #4109

[tellyworth]

In 8245:

Main: don't overwrite in_wrapper if already set.

See #4174, #4109

[tellyworth]

In 8246:

Support theme: don't overwrite in_wrapper if already set.

See #4174, #4109

[tellyworth]

In 8247:

Showcase theme: don't overwrite in_wrapper if already set.

See #4174, #4109

[tellyworth]

In 8248:

Plugins theme: don't overwrite in_wrapper if already set.

See #4174, #4109

[ocean90]

The function signature esc_html( 'Skip to content', 'wporg-plugins' ) doesn't exist. I guess you meant to use esc_html__().

[tellyworth]

Well that was a dumb mistake, fortunately with no serious effects. Thanks for spotting it!

[tellyworth]

In 8257:

Header: should be esc_html() not esc_html().

Thanks @ocean90

See #4109

[tellyworth]

In 8258:

Breathe: add skip-to-content link.

See #4109

[tellyworth]

In 8259:

Themes: should be esc_html(), not esc_html()

See #4109

[dufresnesteven]

This ticket is a bit difficult to track with all the changes, here is an attempt to summarize where we are at.

Page	Theme	Change Set	Complete	Notes
/themes	Themes	8259	✅
/plugins	Plugins	8248	✅
/themes	Rosetta	8244	✅
/	Main	8245	✅
/about	Main	8245	✅
/showcase	Showcase	8247	✅	but doesn't get activated.
/support	Support	8246	✅
make.wordpress.org	Makehome		✅
make.wordpress.org/*	Breathe	8258	✅
/Hosting			✅
/Mobile			✅

General Notes

The WP Toolbar skip link seems to be the first focusable item on the page. This isn't very intuitive. The document structure is definitely to blame. It seems like @tellyworth has tried tabindex="0", which didn't work. If we can move it up in the header and add tabindex="1" we may get a better result.

@tellyworth Let me know if i missed anything or have the themes mixed up. I'll jump in and try to help this along.

[dufresnesteven]

What's in attachment:4109.diff​?

Changes

1. Update skip link to have tabindex="1"
2. Fix some issues where the skip link was defined but in the right require WPORGPATH . 'header.php' scope.
   1. Support
3. Update Gruntfiles to make sure it doesn't normalize the zindeces
   1. This throttles down the z-index which then doesn't let the elements compete with external JS from the toolbar
4. Overwrite some styles in _bbpress.scss that were colliding with accessibility styles.

Next Steps

1. We need to move $wporg_global_header_options['in_wrapper'] up just under the body tag in header.php.
2. We need to add the same skip link logic to
   1. /Mobile
   2. /Hosting

Deployment Details

1. Need to rebuild all grunt driven styles
   1. Plugins
   2. Themes
   3. Support
   4. Main

[dufresnesteven]

r16062-dotorg

WPORG Homepage: Add in 'skip to content' link & associated css.

See: ​https://meta.trac.wordpress.org/ticket/4109

[dufresnesteven]

The table in this comment: https://meta.trac.wordpress.org/ticket/4109#comment:23, reflects the current state.

With the breadth of this ticket, it's possible that some things are not addressed or can be improved. With that being said, I feel confident that we can close this ticket and either reopen if there are more high priority changes, or create new tickets to keep the scope smaller and actionable.