For a number of years, the headings hierarchy in the admin screens have been setup without careful thought. WordPress 4.4 aims to fix this. This work is mainly focused on helping those users of assistive technologies such as screen readers, and is a continuation of the work started in 4.3 on restoring the H1 (heading level 1) to the admin screens.
If you’re a plugin or theme author and you’re providing custom admin screens for settings, etc., there are a few things you should check and update.
Why it matters
Headings provide document structure, which can directly aid keyboard navigation. Users of assistive technologies use headings as the predominant mechanism for finding page information. When heading levels are skipped, it’s more likely for these users to be confused or experience difficulty navigating pages.
Putting it simply, one of the first things screen reader users do in a web page to find relevant content is to press the 1 key on their keyboard to jump to the first <h1> heading and then they will try the key 2 to find the <h2> headings and so on. Thus, it’s extremely important for WordPress to provide a correct headings hierarchy, ensuring no headings levels are skipped.
How to fix your Plugin or Theme
Restructure the document headings hierarchy to ensure that heading levels are not skipped. The main heading should be a <h1> and any subsequent headings should (likely) be bumped one level up. There should be no skipped levels. Check your headings in the Admin, for example in settings pages, list tables, screen options, (dashboard) widgets, and meta boxes.
See for example the screenshot below, the first heading (Sharing Settings) should be a <h1> followed by a <h2> for Sharing Buttons.
Your plugin screens should start with a H1!
List Table headings
List tables (such as on wp-admin/edit.php ) have now additional headings added, though you won’t see them. These headings are hidden with the .screen-reader-text CSS class and are intended to allow users to jump to the relevant sections in these screens.
Note: For more in-depth information on using the core .screen-reader-text class, the Accessibility team has a great write-up on it.
The screenshot below illustrates the new headings in the Posts and Categories screens.
In the screen wp-admin/edit.php the heading structure is now:
- H1: Posts
- H2: Filter posts list (visually hidden)
- H2: Posts list navigation (visually hidden)
- H2: Posts list (visually hidden)
In the screen wp-admin/edit-tags.php?taxonomy=category the heading structure is now:
- H1: Categories
- H2: Categories list navigation (visually hidden)
- H2: Categories list (visually hidden)
- H2: Add new category
The hidden headings in the default posts and taxonomies lists.
If your plugin or theme provides custom post types or custom taxonomies, these new headings will use their default values “Post” and Category”:
The hidden headings in the custom posts and taxonomies lists.
New post type and taxonomy labels in 4.4
In order to provide for better heading text, some new labels have been added for use with register_post_type() and register_taxonomy().
For register_post_type():
'filter_items_list' => __( 'Filter your-cpt-name list', 'your-plugin-text-domain' ),
'items_list_navigation' => __( 'Your-cpt-name list navigation', 'your-plugin-text-domain' ),
'items_list' => __( 'Your-cpt-name list', 'your-plugin-text-domain' ),
For register_taxonomy():
'items_list_navigation' => __( 'Your-tax-name list navigation', 'your-plugin-text-domain' ),
'items_list' => __( 'Your-tax-name list', 'your-plugin-text-domain' ),
Here’s an example for a custom post type:
Using the new labels to provide proper headings for a custom post.
Screen Options tab changes
Some plugins add custom options in the Screen Options tab. Previously, a h5 heading was used for the options “title”. In WordPress 4.4, the Screen Options tab has been revamped and together with other changes, it has been decided to remove the h5 heading which didn’t allow for a good headings hierarchy.
Each group of options is now within its own form fieldset and uses a legend element as “title”. You’re strongly encouraged to change the HTML you use for your plugin options and use the new markup.
The new Screen Options tab: each option is in a separate fieldset.
Dashboard widgets and meta boxes changes
All Dashboard widgets and meta boxes headings changed from an H3 to an H2.
<h2 class="hndle ui-sortable-handle">
<span>your-widget-title</span>
</h2>
If you are a theme or plugin developer: please check the heading structure in the content of your widgets and meta boxes, use an H3 and lower in the right order and context.
Get ahead of 4.4 and update now!
Now is a great time to update your plugins and themes! The power of the Web is in its universality. Help us to make the Web a place designed to work for all people. Any feedback and thoughts are more than welcome, please let us know in the comments below.
Samuel Wood (Otto) 1:07 am on November 19, 2015 Permalink | Log in to Reply
Nice Simpsons reference.
“That’s where I saw the leprechaun. … He told me to burn things.”
chatmandesign 2:28 pm on November 19, 2015 Permalink | Log in to Reply
api.w.org is not a valid domain. Was that supposed to be an abbreviation for api.wordpress.org?
Daniel Bachhuber 2:28 pm on November 19, 2015 Permalink | Log in to Reply
It will shortly become a valid domain.
Ryan McCue 12:35 am on November 20, 2015 Permalink | Log in to Reply
It’s only a namespace, so it doesn’t need to resolve to anything in particular.
In the future though, it’ll probably redirect to the documentation.