Consistent labelling for the editor ARIA landmark regions

afercia commented 1 year ago

Description

The labels of the ARIA landmarks in the Editor are supposed to start with the word Editor.

That's because, when the Editor is not in Fullscreen mode, there are a few more ARIA landmarks that come from the 'classic' admin pages. When the Editor was introduced in core, it was decided to distinguish the Editor landmarks from the classic ones by prepending the word 'Editor'.

Typically, these are the ARIA landmarks in the 'classic' pages:

'Main menu'
'Toolbar'
main (unlabelled <main> element)
content information (unlabelled <footer> element)

Screenshot to illustrate the need to distinguish the editor landmarks from the classic ones:

However, some Editor ARIA landmarks that have been introduced at a later time don't start with the word 'Editor'. For example:

'Document Overview'
'List View'
'Save sidebar'

This inconsistency doesn't help users and breaks a naming convention that was decided long time ago. I think it's worth reevaluating the labelling of all the landmarks.

Landmarks in the Post Editor:

'Editor top bar'
'Block Library'
- 'Block pattern categories'
- 'Media categories'
'Document Overview'
'Editor content'
'Editor settings'
'Editor publish'
'Editor footer'

Landmarks in the Site Editor:

'Navigation sidebar'
navigation (unlabelled <nav> element)
'Editor content'
'Editor top bar'
'Block Library'
- 'Block pattern categories'
- 'Media categories'
'List View'
'Editor settings' (shows both the Settings and the Styles sidebars)
'Save sidebar'
'Editor footer'

Landmarks in the Widgets page:

'Widgets top bar'
'Widgets and blocks'
'Widgets settings'
'Widgets footer'

For better consistency, this should be improved in order to:

either make the labelling always start with 'Editor' ('Widgets' for the Widgets page)
or just remove the word 'Editor', as long as the region names are clear when not in Fullscreen mode

Cc @alexstine

Step-by-step reproduction instructions

Use a screen reader to navigate the ARIA landmarks in the Post editor, Site editor, and Widgets page.
Observe the labelling inconsistencies.
Hint: non screen reader users may want to try this Firefox add-on: https://addons.mozilla.org/en-US/firefox/addon/landmarks/

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

alexstine commented 1 year ago

@afercia I am not sure the extra verbosity is needed here. It should be fairly straight forward for users to understand they are in an editing context when selecting edit, add, or the literal editor. That is an interesting point about full screen mode but I do not think it should change anything. The only difference is the admin menu/toolbar would be displayed.

afercia commented 1 year ago

Cool, thanks. The simpler, the better.

afercia commented 1 year ago

Trying to recap the landmarks naming situation in the table below, where:

Landmarks are sorted by new name in alphabetical order.
I removed some duplicate names.

New name	Old name	Type	Notes
Block Library	no change	region
Block pattern categories	no change	navigation
Content	Editor content	region
content information	no change	unlabeled <footer> element
Document Overview	no change	region
Footer	Editor footer	region
List View	no change	region
main	no change	unlabeled <main> element
Main menu	no change	navigation
Media categories	no change	navigation
Navigation	Navigation sidebar	region
navigation	no change	unlabeled <nav> element	Nested within the Site Editor Navigation sidebar
Publish	Editor publish	region
Save panel	Save sidebar	region
Settings	Editor settings	region	Used for both the Settings sidebar and the Styles sidebar
Toolbar	no change	navigation
Top bar	Editor top bar	region
Widgets and blocks	no change	region

To me, there are a few problematic names that should be more meaningful:

'Footer': doesn't tell what it is about and where it belongs.
'Navigation' (region) and 'navigation' (<nav> element) in the Site Editor: Ideally they should be merged in only one navigation. Also, the name should explain what kind of navigation this is about.
'Toolbar' and 'Top bar': what's the difference? What are they all about?

Worth reminding the new names need ot be unique, for clarity and also because they're used in many E2E tests.

Cc @alexstine I'd greatly appreciate any fedback and proposals for better new names ❤️

alexstine commented 1 year ago

@afercia

'Footer': doesn't tell what it is about and where it belongs.

Should probably call this breadcrumbs? I think that is the only thing in it. This does not make much sense really.

'Toolbar' and 'Top bar': what's the difference? What are they all about?

No idea. Is toolbar referring to the block formatting toolbar?

skorasaurus commented 1 year ago

In case you weren't aware, may want to follow this conversation to ensure consistent terms are used - https://github.com/WordPress/gutenberg/discussions/49837

afercia commented 1 year ago

@alexstine

No idea. Is toolbar referring to the block formatting toolbar?

'Toolbar' is a part of the 'classic' admin interface. It contains:

a link to 'About WordPress'
a link to the front end home page
a link to the available updates
a link to the comments in moderation
etc.

It's present also on the front end, when logged in, and in the Post Editor, when fullscreen mode is disabled.

Visually, it's a horizontal bar at the very top of the page.

alexstine commented 1 year ago

@afercia Hmm, got it. I wonder if that should have been prefixed with "Admin" for "Admin Toolbar". Need some way to tell users that it is global and not part of Gutenberg itself.

WordPress / gutenberg