Missing H1 heading in the admin

[Cheffheid]

The h1 header made its exit with the arrival of the admin bar and it's time to bring it back to restore a good header structure in the admin.

As stated in the ​most recent accessibility test summary, more discussion is required on how to fix this as the accessibility team is divided on how to properly solve this.

What needs to be decided is where it's going to go, and what it will say.

[rianrietveld]

Thanks for opening this ticket @Cheffheid. Maybe it's heading instead of header?

[valendesigns]

We could add the H1 to the site name in the admin bar, but only when you're in the admin panel. The front-end would stay as it is now.

[afercia]

Replying to valendesigns:

We could add the H1 to the site name in the admin bar

That wouldn't be a good use of H1, the site name information is already available in the <title> tag. The H1 should reflect the main topic of each specific screen so if you're in the Media Library it should have as text "Media Library" and so on. Users need to know where they are as first thing. That's not just for "abstract" compliance with the specs, it's what users actually use to navigate the page, see what's the first thing screen reader users do to find information in a page: ​http://webaim.org/projects/screenreadersurvey5/#finding

If you're interested in accessibility, feel free to join us on Slack > Accessibility. Trac maybe is not the best place to have long conversations about semantics.

[GaryJ]

Discussion amongst johnbillion, Rian and myself at WordCamp London.

We could replace the h2 with the h1 but that would require bumping h3 to h2, h4 to h3 and h5 to h4, so no levels were missed out.

However, plugins and themes may also already be using h2 on their settings screens, so the updated levels would need classes, and those classes used (as they should be anyway) to visually style as to what they are now. i.e.

.wrap > h1,
.wrap > .admin-h1, /* new h1 */
.wrap h2 {
 /* Existing .wrap h2 styles */
}

.wrap > .admin-h2, /* new h2 */
.wrap h3 {
 /* Existing h3 styles */
}
 etc.

As an aside, the h5 of the "Show on Screen" Screen Options heading would also need appropriate class for styling.

The patch would be massive (change all the admin headings, plus CSS), so would need to committed as soon as it was ready to avoid it going stale.

[joedolson]

I'm totally game for this proposal; but I do think it would be a good idea to make it a team effort and get buy in before starting it. Like Gary mentions, we'll need to do it and commit it quickly in order to avoid hours of labor updating stale patches...

[joedolson]

Change leading H2s to H1s; update CSS & JS

[joedolson]

With the attached patch in place, all main admin H2s are promoted to H1s, and some associated CSS/JS issues are amended.

This doesn't handle promoting the rest of the page hierarchy; that should probably be a separate ticket, if we choose to do it.

[afercia]

Some historical background: the missing h1 was used for the site name in all the admin screens, with a link back to the front page. It was removed with the refactoring of the admin bar, see how it looked in WordPress 3.0 in the screenshot below, here displaying also a link to the Privacy Settings screen:

Before than this and for a long time, the header had "<-- Visit Site" cuddled next the site name h1 to make it more discoverable. See screenshot below (WordPress 2.7):

Thanks very much to @boren for helping us to rebuild some history.

[afercia]

Refreshed patch to add the network headings and a few more ones. JShinted and rebuilt from the root.

[obenland]

It would be interesting to know how many plugins would break. Plugins that decorate the h2 title and use selectors like core uses now.

Given how it touches pretty much every admin screen, I think this is something that probably should have gone in 6 weeks ago, not two weeks before beta. Thoughts?

[joedolson]

I'm not sure it would be that hard on plugins; plugins that create their own settings screens also add their own headings, which would still be whatever the plug-in chose, and they could change their own heading structure as they had time.

Plugins that decorate the H2 on core admin pages would almost certainly break; but I'm not sure what that would entail. I'm not immediately seeing *why* a plug-in would do that.

In my limited testing with plug-ins and this patch, I didn't encounter any problems; but it was quite limited.

The hard thing about this patch is that it needs to go in quickly whenever it's made; because it crosses so many screens, it'll go stale quickly.

The only way we'll really find out how much impact this has on plug-ins is by committing it and getting some broad testing; we could search the plug-in directory for instances of .wrap h2, but only instances targeting core admin pages would be relevant.

[obenland]

Replying to joedolson:

The only way we'll really find out how much impact this has on plug-ins is by committing it and getting some broad testing;

That's why I was saying that getting it in two weeks before beta might be too late to achieve that. @helen, what do you think?

[rianrietveld]

Isn't beta for testing?

[DrewAPicture]

Replying to rianrietveld:

Isn't beta for testing?

It is for testing, you're correct. What's at issue here is the level of testing that would be required to make sure this is ready – both by core developers and the wider plugin/theme communities. Typically something like this should soak in trunk for almost the entire duration of the development window leading up to beta – or at least a sizable chunk of it.

Therefore, dropping it in just a week or two before beta would considerably shorten that testing window. To do something at this scale, we'd be better off dropping it in right after 4.3 is branched/ships.

[joedolson]

I'm fine with that; the fact that this wasn't done sooner is entirely my fault - I'd intended to get this done in the first week of 4.3, but failed to do that. Dropping it in as soon as 4.3 ships would be smart.

[afercia]

Thanks @obenland an @DrewAPicture, fine. Meanwhile it would be useful to have a look at plugins that decorate the core headings, do you have some examples?

[helen]

I'm okay with doing this now, FWIW. Sorry I wasn't around four days ago to say that, but it's still fine now :) Backing it out is not the end of the world if something comes up.

[obenland]

In 32974:

Proper heading for admin screens.

First step towards restoring a good heading structure in wp-admin.
The previous <h1> contained the site title and a link to the front page and was removed with the toolbar refactoring in 3.2.

Props joedolson, afercia.
Fixes #31650.

[afercia]

First findings about small things to fix:

• reset padding on .about-wrap h1 for the about/credits/freedoms pages
• bottom margin for the .themes-php .wrap h2 now h1 in themes.php
• Menu locations tabs

Should patches be uploaded here or in separate tickets? Also, thanks to @obenland and @helen :)

[afercia]

Reopening to keep track of some needed CSS tweaking, for first round see 32975 thanks to @obenland.

[afercia]

A few more CSS tweaking, most notably for the editor "Focus" opacity.

[wonderboymusic]

In 32977:

After [32974], tweak some CSS for focus, etc.

See #31650.

[wonderboymusic]

Removing keyword so it leaves my report - it can be added later if any new commit candidates materialize.

[SergeyBiryukov]

Should we replace .add-new-h2 class with .add-new-h1?

[afercia]

Replying to SergeyBiryukov:

Should we replace .add-new-h2 class with .add-new-h1?

Related: #26601 where the Add new should be moved out of the headings.

[helen]

We'd have to add an alias for .add-new-h1 if we wanted it, and need to keep .add-new-h2 for now. Would be worth writing all that up on Make/Core when it's settled because it's frequently used.

[obenland]

@ocean90 and I were trying to come up with a less tag-specific name for it, so we don't have to change it again in case we decide to move it in the future. .heading-action maybe?

[GaryJ]

Slightly more verbose, but .page-title-action? Makes it clear it's about the action next to the page title, and not some other (section) heading action.

[ryan]

This needs before and after screenshots posted here or on make/flow. This opens up the audience to non-devs and makes assembling visual history as was done in comment:21 much easier.

@afercia, interested in turning that comment into a visual history post on make/flow?

[obenland]

There is no visual difference, the styles stayed the same. Only the underlying markup changed.

[ryan]

Replying to obenland:

There is no visual difference, the styles stayed the same. Only the underlying markup changed.

Let's prove it with a few screenshots. Screenshots as a reflex is full of virtue. Before and after on desktop. Before and after on a phone. Call that good enough.

[trishasalas]

I've got these screens open for #26601, I'll take some screenshots.

[afercia]

Replying to ryan:

@afercia, interested in turning that comment into a visual history post on make/flow?

@boren hi, maybe not a real before/after set of screenshots because there are really no visual differences but your idea of some visual history intrigues me. If this goes in 4.3 it would probably need a post on make core to inform users and plugin authors about the headings changes roadmap. Some visual history could help to explain them why we're doing this and what they can expect in the next steps.

[obenland]

Replying to GaryJ:

Slightly more verbose, but .page-title-action? Makes it clear it's about the action next to the page title, and not some other (section) heading action.

I like it.

[ryan]

Replying to afercia:

Replying to ryan:

@afercia, interested in turning that comment into a visual history post on make/flow?

@boren hi, maybe not a real before/after set of screenshots because there are really no visual differences but your idea of some visual history intrigues me. If this goes in 4.3 it would probably need a post on make core to inform users and plugin authors about the headings changes roadmap. Some visual history could help to explain them why we're doing this and what they can expect in the next steps.

Preserving institutional memory visually through such a post is appealing. I want to make it a habit.

[obenland]

Added patch 31650.diff​ to replace .add-new-h2 instances.

@helen, how do we usually handle deprecating CSS selectors?

[obenland]

In 33067:

Use a less element-specific class name for links within page titles.

After [32974] these links are no longer within an h2, making the class name
inaccurate. add-new-h1 has the potential to expose the same problem for in a
possible future change.

Fixes #31650.

[obenland]

In 33084:

Site Icon: Switch to using H1 headings.

See #31650.

Props afercia.
Fixes #32885.

[afercia]

In 33909:

Accessibility: bump H3 headings to H2 on User Edit and Your Profile screens.

Ongoing effort to restore a good headings hierarchy in the admin screens after the reintroduction of the missing main <h1> in [32974].

Fix a typo in the DocBlock for the additional_capabilities_display filter.

Props metodiew.
Fixes #33606. See #31650.