Document landmark regions for (third-party) block developers

[afercia]

#2380 introduced ARIA landmarks to identify three main regions in the editor. #3084 enforced this content organization introducing keyboard navigation through these regions.

These main regions identify three main UI sections that are logically different by their content nature:

• the top toolbar
• the sidebar
• the editing area

To make this content organization effective, worth considering a few improvements.

All Gutenberg content should be inside one of these three regions. Nothing can be left outside of them. See also https://www.w3.org/WAI/GL/wiki/Using_ARIA_landmarks_to_identify_regions_of_a_page

It is a best practice to include ALL content on the page in landmarks, so that screen reader users who rely on them to navigate from section to section do not lose track of content.

Currently, there are three content areas that should probably be moved in the source:

• the notifications area
• the table of contents
• the meta boxes panel

See screenshot below:

• the notifications area: currently it's not inside one of the main region
• the table of contents: it's inside the editing region named "Editor content". Ideally, this region should exclusively contain editable content or tools related to editing. Instead, word count and ToC are info on the document structure and should be placed outside of the content region (maybe in the sidebar?)
• the meta boxes panel: it's inside the content region but it's not exactly content: maybe it should be in its own region? (a 4th new one?)

Worth noting I'm referring to the placement of content in the source, not to visuals. Ideally, for a11y content order and visual order should match. However, small adjustments can be acceptable.

[afercia]

Agreed during today's bug scrub to change this issue as documentation-oriented. As any content in Gutenberg needs to live inside the landmark regions, this is something that should be well documented.

Specific cases should be addressed in specific issues, for example see #4187 for the Publishing Flow.

[karmatosed]

Removed documentation label as this isn't just a documentation issue, it's a coding issue and high priority. This should be added to documentation once in code.

[samikeijonen]

Any news on this? For example is there a reason why the table of contents is not directly after the button that toggles it?

[afercia]

The table of contents and other “popover” were implemented like a sort of modal, so when they open they’re rendered before the closing body tag.

Discussed during today's accessibility bug-scrub: now that the publishing flow has been placed within its own landmark region, everything should be in a proper place. Seems the only thing left in this issue is adding it to the documentation, to explain plugin developers that all content must be placed within one of the landmarks.

[mtias]

I'm removing this from this milestone as it seems the remaining actionable item is to expand on documentation and usage.