New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document landmark regions for (third-party) block developers #3217

Open
afercia opened this Issue Oct 28, 2017 · 9 comments

Comments

Projects
None yet
7 participants
@afercia
Contributor

afercia commented Oct 28, 2017

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

screen shot 2017-10-28 at 16 29 46

  • 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

This comment has been minimized.

Contributor

afercia commented Mar 1, 2018

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.

@afercia afercia added this to the Merge Proposal milestone Mar 19, 2018

@karmatosed karmatosed modified the milestones: Merge Proposal, Merge Proposal: Accessibility Apr 12, 2018

@karmatosed

This comment has been minimized.

Member

karmatosed commented Apr 13, 2018

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

This comment has been minimized.

Contributor

samikeijonen commented Apr 25, 2018

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

This comment has been minimized.

Contributor

afercia commented Jul 9, 2018

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

This comment has been minimized.

Contributor

mtias commented Oct 3, 2018

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

@mtias mtias removed the Priority High label Oct 3, 2018

@mtias mtias removed this from the Merge: Accessibility milestone Oct 3, 2018

@tofumatt tofumatt changed the title from Components and features should be logically placed within the main regions to Docs: Document landmark regions for (third-party) block developers Oct 5, 2018

@tofumatt tofumatt changed the title from Docs: Document landmark regions for (third-party) block developers to Document landmark regions for (third-party) block developers Oct 5, 2018

@tofumatt tofumatt changed the title from Document landmark regions for (third-party) block developers to Document landmark regions for (3rd-party) block developers Oct 5, 2018

@tofumatt tofumatt changed the title from Document landmark regions for (3rd-party) block developers to Document landmark regions for (third-party) block developers Oct 5, 2018

@aaronjorbin aaronjorbin added this to the Merge: Accessibility milestone Oct 7, 2018

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 6, 2018

@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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 6, 2018

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

This comment has been minimized.

Contributor

afercia commented Nov 6, 2018

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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 6, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment