WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 2 years ago

Last modified 2 years ago

#31650 closed defect (bug) (fixed)

Missing H1 heading in the admin

Reported by: Cheffheid Owned by: joedolson
Milestone: 4.3 Priority: normal
Severity: normal Version: 3.3
Component: Administration Keywords: has-patch
Focuses: accessibility Cc:

Description

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.

Attachments (4)

31650.patch (27.8 KB) - added by joedolson 2 years ago.
Change leading H2s to H1s; update CSS & JS
31650.2.patch (38.1 KB) - added by afercia 2 years ago.
31650-css-tweaking.patch (1.6 KB) - added by afercia 2 years ago.
31650.diff (14.6 KB) - added by obenland 2 years ago.

Download all attachments as: .zip

Change History (63)

#1 @SergeyBiryukov
3 years ago

  • Summary changed from The missing H1 header to Missing H1 header in the admin

#2 @rianrietveld
3 years ago

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

#3 @Cheffheid
3 years ago

  • Summary changed from Missing H1 header in the admin to Missing H1 heading in the admin

#4 follow-up: @valendesigns
3 years ago

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.

#5 in reply to: ↑ 4 @afercia
3 years ago

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.

#6 @GaryJ
3 years ago

  • Keywords needs-patch added

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.

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


3 years ago

#8 @joedolson
3 years ago

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...

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


2 years ago

#10 @johnbillion
2 years ago

  • Milestone changed from Awaiting Review to Future Release

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


2 years ago

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


2 years ago

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


2 years ago

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


2 years ago

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


2 years ago

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


2 years ago

#17 @joedolson
2 years ago

  • Owner set to joedolson
  • Status changed from new to accepted

#18 @afercia
2 years ago

  • Milestone changed from Future Release to 4.3

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


2 years ago

@joedolson
2 years ago

Change leading H2s to H1s; update CSS & JS

#20 @joedolson
2 years ago

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.

#21 @afercia
2 years ago

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:

https://cldup.com/9FceDmFzmY.png

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):

https://cldup.com/6icB05QuYo.png

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

@afercia
2 years ago

#22 @afercia
2 years ago

  • Keywords has-patch added; needs-patch removed

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

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


2 years ago

#24 @obenland
2 years ago

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?

#25 follow-up: @joedolson
2 years ago

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.

#26 in reply to: ↑ 25 @obenland
2 years ago

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?

#27 follow-up: @rianrietveld
2 years ago

Isn't beta for testing?

#28 in reply to: ↑ 27 @DrewAPicture
2 years ago

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.

#29 @joedolson
2 years ago

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.

#30 @afercia
2 years ago

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?

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


2 years ago

#32 @helen
2 years ago

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.

#33 @afercia
2 years ago

  • Keywords commit added

#34 @obenland
2 years ago

  • Resolution set to fixed
  • Status changed from accepted to closed

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.

#35 @afercia
2 years ago

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 :)

#36 @afercia
2 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

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

#37 @afercia
2 years ago

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

#38 @wonderboymusic
2 years ago

In 32977:

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

See #31650.

#39 @wonderboymusic
2 years ago

  • Keywords commit removed

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

#40 follow-up: @SergeyBiryukov
2 years ago

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

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


2 years ago

#42 in reply to: ↑ 40 @afercia
2 years ago

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.

#43 @helen
2 years ago

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.

#44 @obenland
2 years ago

@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?

#45 follow-up: @GaryJ
2 years ago

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.

#46 follow-up: @ryan
2 years ago

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?

#47 follow-up: @obenland
2 years ago

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

#48 in reply to: ↑ 47 @ryan
2 years ago

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.

#49 @trishasalas
2 years ago

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

#50 in reply to: ↑ 46 ; follow-up: @afercia
2 years ago

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.

#51 in reply to: ↑ 45 @obenland
2 years ago

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.

#52 in reply to: ↑ 50 @ryan
2 years ago

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.

This ticket was mentioned in Slack in #core by obenland. View the logs.


2 years ago

@obenland
2 years ago

#54 @obenland
2 years ago

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

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

#55 @obenland
2 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

#56 @obenland
2 years ago

In 33084:

Site Icon: Switch to using H1 headings.

See #31650.

Props afercia.
Fixes #32885.

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


2 years ago

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


2 years ago

#59 @afercia
2 years ago

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.

Note: See TracTickets for help on using tickets.