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.

[chrisvanpatten]

@afercia Would it be okay to merge this in with #10373?

EDIT: I may have misread the original issue; it sounds like this is more for developers, so they know where to place their custom plugin content?

[chrisvanpatten]

Okay, re-reading this it seems like it is a question of documenting where custom plugin developers should literally place their markup within the source of a page, so it is assigned correctly to a landmark.

However, do developers have that level of control? If you're registering a plugin with the plugin API (for a modal or sidebar or whatever), won't it automatically put your markup in the correct place, so you should be already inside of a landmark region?

[afercia]

it is a question of documenting where custom plugin developers should literally place their markup within the source of a page

Yes 🙂

do developers have that level of control? If you're registering a plugin with the plugin API (for a modal or sidebar or whatever), won't it automatically put your markup in the correct place

I only know of the Plugin Sidebar developed at Yoast, and it is automatically rendered in its own landmark region. I don't know enough about other technical details to say if it's possible to render plugins content in other places.

[chrisvanpatten]

Got it, thanks @afercia :) We'll investigate whether it is possible to put plugins in other places, or whether this is handled automatically. Pinging @tofumatt who might have come across this at some point. If it's done automatically we may not need documentation, but should certainly make sure it's addressed as it's definitely an important issue.

[spencerfinnell]

Is there any news on this? Been wondering about this lately as well. Lots of plugins that need space outside of the editor area larger than the sidebar. Having an area under the editor where the metaboxes would be nice.

[chrisvanpatten]

@spencerfinnell Right now you might consider a modal triggered from a menu item in the plugin menu. There currently isn’t a way to add below the editor canvas outside of metaboxes.

[spencerfinnell]

@chrisvanpatten that’s what I thought, but hopefully it doesn’t stay that way. Lots of clicks and lack of discovery compared to metaboxes.

[afercia]

Discussed during today's accessibility bug-scrub and agreed to add, for now, a short sentence to explain why it's important to have content within landmark regions.

In the future, we'll evaluate if this needs to be documented and better explained also in the developers handbook.

[mkaz]

@afercia I read through this issue and saw the discussion from today's bug scrub in Slack. Do you have a suggested spot you would like to add the sentence? Here is the sentence I was going to add, pulled from above, but haven't quite figured out a good spot to put it.

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.

I was thinking that maybe we could add an accessibility.md document in this directory, similar to the internalization page, and we can include any other additional information:
https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers/developers

[afercia]

@mkaz thanks. The sentence looks good to me.

accessibility.md is an interesting idea, I'd defer to @chrisvanpatten. That page could be used for more details and links to resources. For example, I'd link to the ARIA 1.1 authoring practices (note: 1.2 is coming soon) where everything is explained already, with examples:

General Principles of Landmark Design:
https://www.w3.org/TR/wai-aria-practices-1.1/#general-principles-of-landmark-design

General example:
https://www.w3.org/TR/wai-aria-practices/examples/landmarks/

HTML5 elements that by default define ARIA landmarks:
https://www.w3.org/TR/wai-aria-practices/examples/landmarks/HTML5.html