Improve the headings hierarchy in the site editor page

[afercia]

Fixes https://github.com/WordPress/gutenberg/issues/42373

What?

Changes some heading levels and removes some headings to make the headings hierarchy a bit more meaningful and not skip levels.

Why?

A good headings structure is not just about good semantics. Headings are also a navigational tool for screen reader users, as they can use dedicated commands to jump through headings, get a sense of the overall content, and navigate a page. This principle applies also to administration user interfaces, where headings can be used to identify the main parts of the interface.

How?

• This PR should be coordinated with the core Trac ticket https://core.trac.wordpress.org/ticket/56228 where the main H1 heading of the site editor page is moved to the core PHP side. This change makes the H1 the first thing in the main content and it's consistent with the post editor.
• The current H1 heading on the Site Editor page is changed to H2.
• Other headings levels are changed, to not skip levels.
• Some headings are removed, as they don't make much sense in the overall hierarchy. This mostly applies to some headings in some popovers.

Testing Instructions

• Hint: use the HeadingsMap browser extension. It's available for Chrome and Firefox.
• Apply the patch for the core part that is attached to https://core.trac.wordpress.org/ticket/56228
• Go to the Site Editor.
• Use HeadingsMap and check the main H1 is a visually hidden heading with text 'Edit site'.
• Check the Document Actions visually hidden heading is now a H2. E.g. 'Editing template; Home'.
• Click the Document Actions chevron icon button to open the template details popover.
• Check the template title in the popover is not a H4 any longer. It's now a styled paragraph.
• Open the Navigation left sidebar and check the heading 'Editor' is now a H2.
• Click 'Templates' or 'Template Parts' in the navigation to open the templates list.
• Inspect the headings in the templates list and check they're now H3.
• Disable JAvaScript in your browser and refresh the page.
• Observe there's now a visible H1 heading 'Edit site' and a no-js WordPress notice.

Screenshots or screencast

[github-actions[bot]]

Size Change: +19 B (0%)

Total Size: 1.37 MB

Filename	Size	Change
build/components/index.min.js	208 kB	+4 B (0%)
build/edit-site/index.min.js	64.3 kB	+13 B (0%)
build/edit-site/style.css	10.1 kB	+2 B (0%)

ℹ️ View Unchanged

Filename	Size
build/a11y/index.min.js	993 B
build/annotations/index.min.js	2.78 kB
build/api-fetch/index.min.js	2.27 kB
build/autop/index.min.js	2.15 kB
build/blob/index.min.js	483 B
build/block-directory/index.min.js	7.2 kB
build/block-directory/style-rtl.css	1.04 kB
build/block-directory/style.css	1.04 kB
build/block-editor/content-rtl.css	4.11 kB
build/block-editor/content.css	4.1 kB
build/block-editor/default-editor-styles-rtl.css	403 B
build/block-editor/default-editor-styles.css	403 B
build/block-editor/index.min.js	203 kB
build/block-editor/style-rtl.css	14.6 kB
build/block-editor/style.css	14.6 kB
build/block-library/blocks/archives/editor-rtl.css	61 B
build/block-library/blocks/archives/editor.css	60 B
build/block-library/blocks/archives/style-rtl.css	90 B
build/block-library/blocks/archives/style.css	90 B
build/block-library/blocks/audio/editor-rtl.css	150 B
build/block-library/blocks/audio/editor.css	150 B
build/block-library/blocks/audio/style-rtl.css	122 B
build/block-library/blocks/audio/style.css	122 B
build/block-library/blocks/audio/theme-rtl.css	138 B
build/block-library/blocks/audio/theme.css	138 B
build/block-library/blocks/avatar/editor-rtl.css	116 B
build/block-library/blocks/avatar/editor.css	116 B
build/block-library/blocks/avatar/style-rtl.css	91 B
build/block-library/blocks/avatar/style.css	91 B
build/block-library/blocks/block/editor-rtl.css	305 B
build/block-library/blocks/block/editor.css	305 B
build/block-library/blocks/button/editor-rtl.css	587 B
build/block-library/blocks/button/editor.css	587 B
build/block-library/blocks/button/style-rtl.css	628 B
build/block-library/blocks/button/style.css	627 B
build/block-library/blocks/buttons/editor-rtl.css	337 B
build/block-library/blocks/buttons/editor.css	337 B
build/block-library/blocks/buttons/style-rtl.css	332 B
build/block-library/blocks/buttons/style.css	332 B
build/block-library/blocks/calendar/style-rtl.css	239 B
build/block-library/blocks/calendar/style.css	239 B
build/block-library/blocks/categories/editor-rtl.css	113 B
build/block-library/blocks/categories/editor.css	112 B
build/block-library/blocks/categories/style-rtl.css	124 B
build/block-library/blocks/categories/style.css	124 B
build/block-library/blocks/code/editor-rtl.css	53 B
build/block-library/blocks/code/editor.css	53 B
build/block-library/blocks/code/style-rtl.css	121 B
build/block-library/blocks/code/style.css	121 B
build/block-library/blocks/code/theme-rtl.css	124 B
build/block-library/blocks/code/theme.css	124 B
build/block-library/blocks/columns/editor-rtl.css	108 B
build/block-library/blocks/columns/editor.css	108 B
build/block-library/blocks/columns/style-rtl.css	409 B
build/block-library/blocks/columns/style.css	409 B
build/block-library/blocks/comment-author-avatar/editor-rtl.css	125 B
build/block-library/blocks/comment-author-avatar/editor.css	125 B
build/block-library/blocks/comment-content/style-rtl.css	92 B
build/block-library/blocks/comment-content/style.css	92 B
build/block-library/blocks/comment-template/style-rtl.css	199 B
build/block-library/blocks/comment-template/style.css	198 B
build/block-library/blocks/comments-pagination-numbers/editor-rtl.css	123 B
build/block-library/blocks/comments-pagination-numbers/editor.css	121 B
build/block-library/blocks/comments-pagination/editor-rtl.css	222 B
build/block-library/blocks/comments-pagination/editor.css	209 B
build/block-library/blocks/comments-pagination/style-rtl.css	235 B
build/block-library/blocks/comments-pagination/style.css	231 B
build/block-library/blocks/comments-title/editor-rtl.css	75 B
build/block-library/blocks/comments-title/editor.css	75 B
build/block-library/blocks/comments/editor-rtl.css	840 B
build/block-library/blocks/comments/editor.css	839 B
build/block-library/blocks/comments/style-rtl.css	637 B
build/block-library/blocks/comments/style.css	636 B
build/block-library/blocks/cover/editor-rtl.css	649 B
build/block-library/blocks/cover/editor.css	651 B
build/block-library/blocks/cover/style-rtl.css	1.61 kB
build/block-library/blocks/cover/style.css	1.6 kB
build/block-library/blocks/details-summary/editor-rtl.css	65 B
build/block-library/blocks/details-summary/editor.css	65 B
build/block-library/blocks/details-summary/style-rtl.css	61 B
build/block-library/blocks/details-summary/style.css	61 B
build/block-library/blocks/details/style-rtl.css	54 B
build/block-library/blocks/details/style.css	54 B
build/block-library/blocks/embed/editor-rtl.css	293 B
build/block-library/blocks/embed/editor.css	293 B
build/block-library/blocks/embed/style-rtl.css	410 B
build/block-library/blocks/embed/style.css	410 B
build/block-library/blocks/embed/theme-rtl.css	138 B
build/block-library/blocks/embed/theme.css	138 B
build/block-library/blocks/file/editor-rtl.css	300 B
build/block-library/blocks/file/editor.css	300 B
build/block-library/blocks/file/style-rtl.css	269 B
build/block-library/blocks/file/style.css	270 B
build/block-library/blocks/file/view.min.js	353 B
build/block-library/blocks/freeform/editor-rtl.css	2.44 kB
build/block-library/blocks/freeform/editor.css	2.44 kB
build/block-library/blocks/gallery/editor-rtl.css	984 B
build/block-library/blocks/gallery/editor.css	988 B
build/block-library/blocks/gallery/style-rtl.css	1.55 kB
build/block-library/blocks/gallery/style.css	1.55 kB
build/block-library/blocks/gallery/theme-rtl.css	122 B
build/block-library/blocks/gallery/theme.css	122 B
build/block-library/blocks/group/editor-rtl.css	654 B
build/block-library/blocks/group/editor.css	654 B
build/block-library/blocks/group/style-rtl.css	57 B
build/block-library/blocks/group/style.css	57 B
build/block-library/blocks/group/theme-rtl.css	78 B
build/block-library/blocks/group/theme.css	78 B
build/block-library/blocks/heading/style-rtl.css	76 B
build/block-library/blocks/heading/style.css	76 B
build/block-library/blocks/html/editor-rtl.css	332 B
build/block-library/blocks/html/editor.css	333 B
build/block-library/blocks/image/editor-rtl.css	830 B
build/block-library/blocks/image/editor.css	829 B
build/block-library/blocks/image/style-rtl.css	652 B
build/block-library/blocks/image/style.css	652 B
build/block-library/blocks/image/theme-rtl.css	137 B
build/block-library/blocks/image/theme.css	137 B
build/block-library/blocks/latest-comments/style-rtl.css	357 B
build/block-library/blocks/latest-comments/style.css	357 B
build/block-library/blocks/latest-posts/editor-rtl.css	213 B
build/block-library/blocks/latest-posts/editor.css	212 B
build/block-library/blocks/latest-posts/style-rtl.css	478 B
build/block-library/blocks/latest-posts/style.css	478 B
build/block-library/blocks/list/style-rtl.css	88 B
build/block-library/blocks/list/style.css	88 B
build/block-library/blocks/media-text/editor-rtl.css	266 B
build/block-library/blocks/media-text/editor.css	263 B
build/block-library/blocks/media-text/style-rtl.css	507 B
build/block-library/blocks/media-text/style.css	505 B
build/block-library/blocks/more/editor-rtl.css	431 B
build/block-library/blocks/more/editor.css	431 B
build/block-library/blocks/navigation-link/editor-rtl.css	716 B
build/block-library/blocks/navigation-link/editor.css	715 B
build/block-library/blocks/navigation-link/style-rtl.css	115 B
build/block-library/blocks/navigation-link/style.css	115 B
build/block-library/blocks/navigation-submenu/editor-rtl.css	299 B
build/block-library/blocks/navigation-submenu/editor.css	299 B
build/block-library/blocks/navigation/editor-rtl.css	2.13 kB
build/block-library/blocks/navigation/editor.css	2.14 kB
build/block-library/blocks/navigation/style-rtl.css	2.22 kB
build/block-library/blocks/navigation/style.css	2.21 kB
build/block-library/blocks/navigation/view-modal.min.js	2.81 kB
build/block-library/blocks/navigation/view.min.js	447 B
build/block-library/blocks/nextpage/editor-rtl.css	395 B
build/block-library/blocks/nextpage/editor.css	395 B
build/block-library/blocks/page-list/editor-rtl.css	401 B
build/block-library/blocks/page-list/editor.css	401 B
build/block-library/blocks/page-list/style-rtl.css	175 B
build/block-library/blocks/page-list/style.css	175 B
build/block-library/blocks/paragraph/editor-rtl.css	174 B
build/block-library/blocks/paragraph/editor.css	174 B
build/block-library/blocks/paragraph/style-rtl.css	279 B
build/block-library/blocks/paragraph/style.css	281 B
build/block-library/blocks/post-author/style-rtl.css	175 B
build/block-library/blocks/post-author/style.css	176 B
build/block-library/blocks/post-comments-form/editor-rtl.css	96 B
build/block-library/blocks/post-comments-form/editor.css	96 B
build/block-library/blocks/post-comments-form/style-rtl.css	501 B
build/block-library/blocks/post-comments-form/style.css	501 B
build/block-library/blocks/post-date/style-rtl.css	61 B
build/block-library/blocks/post-date/style.css	61 B
build/block-library/blocks/post-excerpt/editor-rtl.css	71 B
build/block-library/blocks/post-excerpt/editor.css	71 B
build/block-library/blocks/post-excerpt/style-rtl.css	141 B
build/block-library/blocks/post-excerpt/style.css	141 B
build/block-library/blocks/post-featured-image/editor-rtl.css	588 B
build/block-library/blocks/post-featured-image/editor.css	586 B
build/block-library/blocks/post-featured-image/style-rtl.css	322 B
build/block-library/blocks/post-featured-image/style.css	322 B
build/block-library/blocks/post-navigation-link/style-rtl.css	153 B
build/block-library/blocks/post-navigation-link/style.css	153 B
build/block-library/blocks/post-template/editor-rtl.css	99 B
build/block-library/blocks/post-template/editor.css	98 B
build/block-library/blocks/post-template/style-rtl.css	281 B
build/block-library/blocks/post-template/style.css	281 B
build/block-library/blocks/post-terms/style-rtl.css	96 B
build/block-library/blocks/post-terms/style.css	96 B
build/block-library/blocks/post-time-to-read/style-rtl.css	69 B
build/block-library/blocks/post-time-to-read/style.css	69 B
build/block-library/blocks/post-title/style-rtl.css	100 B
build/block-library/blocks/post-title/style.css	100 B
build/block-library/blocks/preformatted/style-rtl.css	103 B
build/block-library/blocks/preformatted/style.css	103 B
build/block-library/blocks/pullquote/editor-rtl.css	135 B
build/block-library/blocks/pullquote/editor.css	135 B
build/block-library/blocks/pullquote/style-rtl.css	335 B
build/block-library/blocks/pullquote/style.css	335 B
build/block-library/blocks/pullquote/theme-rtl.css	167 B
build/block-library/blocks/pullquote/theme.css	167 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css	122 B
build/block-library/blocks/query-pagination-numbers/editor.css	121 B
build/block-library/blocks/query-pagination/editor-rtl.css	221 B
build/block-library/blocks/query-pagination/editor.css	211 B
build/block-library/blocks/query-pagination/style-rtl.css	288 B
build/block-library/blocks/query-pagination/style.css	284 B
build/block-library/blocks/query-title/style-rtl.css	63 B
build/block-library/blocks/query-title/style.css	63 B
build/block-library/blocks/query/editor-rtl.css	463 B
build/block-library/blocks/query/editor.css	463 B
build/block-library/blocks/quote/style-rtl.css	222 B
build/block-library/blocks/quote/style.css	222 B
build/block-library/blocks/quote/theme-rtl.css	223 B
build/block-library/blocks/quote/theme.css	226 B
build/block-library/blocks/read-more/style-rtl.css	132 B
build/block-library/blocks/read-more/style.css	132 B
build/block-library/blocks/rss/editor-rtl.css	149 B
build/block-library/blocks/rss/editor.css	149 B
build/block-library/blocks/rss/style-rtl.css	289 B
build/block-library/blocks/rss/style.css	288 B
build/block-library/blocks/search/editor-rtl.css	165 B
build/block-library/blocks/search/editor.css	165 B
build/block-library/blocks/search/style-rtl.css	408 B
build/block-library/blocks/search/style.css	406 B
build/block-library/blocks/search/theme-rtl.css	114 B
build/block-library/blocks/search/theme.css	114 B
build/block-library/blocks/separator/editor-rtl.css	146 B
build/block-library/blocks/separator/editor.css	146 B
build/block-library/blocks/separator/style-rtl.css	234 B
build/block-library/blocks/separator/style.css	234 B
build/block-library/blocks/separator/theme-rtl.css	194 B
build/block-library/blocks/separator/theme.css	194 B
build/block-library/blocks/shortcode/editor-rtl.css	329 B
build/block-library/blocks/shortcode/editor.css	329 B
build/block-library/blocks/site-logo/editor-rtl.css	489 B
build/block-library/blocks/site-logo/editor.css	489 B
build/block-library/blocks/site-logo/style-rtl.css	203 B
build/block-library/blocks/site-logo/style.css	203 B
build/block-library/blocks/site-tagline/editor-rtl.css	86 B
build/block-library/blocks/site-tagline/editor.css	86 B
build/block-library/blocks/site-title/editor-rtl.css	116 B
build/block-library/blocks/site-title/editor.css	116 B
build/block-library/blocks/site-title/style-rtl.css	57 B
build/block-library/blocks/site-title/style.css	57 B
build/block-library/blocks/social-link/editor-rtl.css	184 B
build/block-library/blocks/social-link/editor.css	184 B
build/block-library/blocks/social-links/editor-rtl.css	674 B
build/block-library/blocks/social-links/editor.css	673 B
build/block-library/blocks/social-links/style-rtl.css	1.4 kB
build/block-library/blocks/social-links/style.css	1.39 kB
build/block-library/blocks/spacer/editor-rtl.css	359 B
build/block-library/blocks/spacer/editor.css	359 B
build/block-library/blocks/spacer/style-rtl.css	48 B
build/block-library/blocks/spacer/style.css	48 B
build/block-library/blocks/table/editor-rtl.css	433 B
build/block-library/blocks/table/editor.css	433 B
build/block-library/blocks/table/style-rtl.css	651 B
build/block-library/blocks/table/style.css	650 B
build/block-library/blocks/table/theme-rtl.css	157 B
build/block-library/blocks/table/theme.css	157 B
build/block-library/blocks/tag-cloud/style-rtl.css	251 B
build/block-library/blocks/tag-cloud/style.css	253 B
build/block-library/blocks/template-part/editor-rtl.css	404 B
build/block-library/blocks/template-part/editor.css	404 B
build/block-library/blocks/template-part/theme-rtl.css	101 B
build/block-library/blocks/template-part/theme.css	101 B
build/block-library/blocks/text-columns/editor-rtl.css	95 B
build/block-library/blocks/text-columns/editor.css	95 B
build/block-library/blocks/text-columns/style-rtl.css	166 B
build/block-library/blocks/text-columns/style.css	166 B
build/block-library/blocks/verse/style-rtl.css	99 B
build/block-library/blocks/verse/style.css	99 B
build/block-library/blocks/video/editor-rtl.css	552 B
build/block-library/blocks/video/editor.css	555 B
build/block-library/blocks/video/style-rtl.css	179 B
build/block-library/blocks/video/style.css	179 B
build/block-library/blocks/video/theme-rtl.css	139 B
build/block-library/blocks/video/theme.css	139 B
build/block-library/classic-rtl.css	179 B
build/block-library/classic.css	179 B
build/block-library/common-rtl.css	1.12 kB
build/block-library/common.css	1.12 kB
build/block-library/editor-elements-rtl.css	75 B
build/block-library/editor-elements.css	75 B
build/block-library/editor-rtl.css	11.6 kB
build/block-library/editor.css	11.6 kB
build/block-library/elements-rtl.css	54 B
build/block-library/elements.css	54 B
build/block-library/index.min.js	204 kB
build/block-library/reset-rtl.css	478 B
build/block-library/reset.css	478 B
build/block-library/style-rtl.css	12.8 kB
build/block-library/style.css	12.8 kB
build/block-library/theme-rtl.css	698 B
build/block-library/theme.css	703 B
build/block-serialization-default-parser/index.min.js	1.13 kB
build/block-serialization-spec-parser/index.min.js	2.83 kB
build/blocks/index.min.js	51.1 kB
build/commands/index.min.js	14.8 kB
build/commands/style-rtl.css	1.1 kB
build/commands/style.css	1.09 kB
build/components/style-rtl.css	11.7 kB
build/components/style.css	11.7 kB
build/compose/index.min.js	12.4 kB
build/core-data/index.min.js	16.3 kB
build/customize-widgets/index.min.js	12.2 kB
build/customize-widgets/style-rtl.css	1.41 kB
build/customize-widgets/style.css	1.41 kB
build/data-controls/index.min.js	718 B
build/data/index.min.js	8.68 kB
build/date/index.min.js	40.4 kB
build/deprecated/index.min.js	518 B
build/dom-ready/index.min.js	336 B
build/dom/index.min.js	4.76 kB
build/edit-post/classic-rtl.css	571 B
build/edit-post/classic.css	571 B
build/edit-post/index.min.js	35 kB
build/edit-post/style-rtl.css	7.59 kB
build/edit-post/style.css	7.58 kB
build/edit-site/style-rtl.css	10.1 kB
build/edit-widgets/index.min.js	17.3 kB
build/edit-widgets/style-rtl.css	4.56 kB
build/edit-widgets/style.css	4.56 kB
build/editor/index.min.js	45.9 kB
build/editor/style-rtl.css	3.49 kB
build/editor/style.css	3.48 kB
build/element/index.min.js	4.95 kB
build/escape-html/index.min.js	548 B
build/format-library/index.min.js	7.26 kB
build/format-library/style-rtl.css	557 B
build/format-library/style.css	556 B
build/hooks/index.min.js	1.66 kB
build/html-entities/index.min.js	454 B
build/i18n/index.min.js	3.79 kB
build/is-shallow-equal/index.min.js	535 B
build/keyboard-shortcuts/index.min.js	1.79 kB
build/keycodes/index.min.js	1.94 kB
build/list-reusable-blocks/index.min.js	2.14 kB
build/list-reusable-blocks/style-rtl.css	865 B
build/list-reusable-blocks/style.css	865 B
build/media-utils/index.min.js	2.99 kB
build/notices/index.min.js	977 B
build/plugins/index.min.js	1.94 kB
build/preferences-persistence/index.min.js	2.23 kB
build/preferences/index.min.js	1.35 kB
build/primitives/index.min.js	960 B
build/priority-queue/index.min.js	1.52 kB
build/private-apis/index.min.js	942 B
build/react-i18n/index.min.js	702 B
build/react-refresh-entry/index.min.js	8.44 kB
build/react-refresh-runtime/index.min.js	7.31 kB
build/redux-routine/index.min.js	2.75 kB
build/reusable-blocks/index.min.js	2.26 kB
build/reusable-blocks/style-rtl.css	265 B
build/reusable-blocks/style.css	265 B
build/rich-text/index.min.js	11.1 kB
build/server-side-render/index.min.js	2.09 kB
build/shortcode/index.min.js	1.52 kB
build/style-engine/index.min.js	1.55 kB
build/token-list/index.min.js	650 B
build/url/index.min.js	3.74 kB
build/vendors/inert-polyfill.min.js	2.48 kB
build/vendors/react-dom.min.js	41.8 kB
build/vendors/react.min.js	4.02 kB
build/viewport/index.min.js	1.09 kB
build/warning/index.min.js	280 B
build/widgets/index.min.js	7.3 kB
build/widgets/style-rtl.css	1.18 kB
build/widgets/style.css	1.18 kB
build/wordcount/index.min.js	1.06 kB

_{compressed-size-action}

[afercia]

Rebased and adjusted on top of latest trunk.

[github-actions[bot]]

Flaky tests detected in d04251efd4e9709298fa63d51d7bb72cde1a7e5f. Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4045143620 📝 Reported issues:

• #36939 in specs/editor/plugins/custom-post-types.test.js

[afercia]

I rebased and adjusted on top of latest trunk. Some of the changes originally proposed in this PR already landed in trunk, see for example the heading level change in https://github.com/WordPress/gutenberg/pull/43151/

The pending issue about the main H1 can be split into a separate issue. In the meantime, I'd love to see this PR merged ❤️

[alexstine]

@afercia If you can rebase this one more time, I'll give it a quick review/approve. Happy to see this go in even if we're still trying to figure out the h1. Sorry, I was under the impression that the h1 discussion needed resolution first. Did not mean to leave you hanging here.

[ndiego]

@alexstine @afercia any updates here? We are running out of time to get this included in 6.3. Thanks!

[alexstine]

I am on a working vacation right now so do not have time to take on additional work. :(

[afercia]

@ndiego thanx for the ping. Part of the headings hierarchy was already improved by @youknowriad in https://github.com/WordPress/gutenberg/pull/51696

I think there's still room for improvements but I'll split them in a future PR.

More importantly, the CSS adjustments included in this PR need to ship to fix the WP admin page site-editor.php when JavaScript is disabled. Currently, with JS off the layout is totally broken. I'm going to close this PR and submit a new one that will need to be merged for WP 6.3.

See: https://core.trac.wordpress.org/ticket/56228 https://core.trac.wordpress.org/changeset/56025 https://github.com/WordPress/wordpress-develop/pull/4695

Screenshot of the site-editor.php whit JS off: