Accessibility best-practice: landmarks

[CharpentierLucas]

Hello!
After using a few tools to assess accessibility of XWiki and working for some time on WCAG compliance of XWiki, I could witness that a quite important a11y best-practice rule is not followed:
HTML sectioning (or a more diverse alternative, aria-roles) is not used for every part of the interface.

Making sure all content is within some landmarks allows screen-reader users to navigate to a section quickly, and overall help assistive technology understand the structure of the page.

Some resources on the subject:
https://dequeuniversity.com/rules/axe/4.6/region

Landmarks - Accessibility Introduction

Description of HTML5 landmarks: Accessibility Landmarks
Description of aria roles: Using ARIA landmarks to identify regions of a page - WCAG WG

A blind user who may be familiar with a news site’s menu, and is only interested in getting to the top story could easily navigate to the “main” landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.

Video demo of the home page shown with the Landmarks addon for Firefox
(Landmarks – Get this Extension for 🦊 Firefox (en-US))

This test was made on 15.1-rc-1 after fixes for XWIKI-19450 (fixes gave different names to explicit navigation sections).
This tool can detect 10 landmarks on the page, and we see that most of the landmarks are described as “guessed”.
Some of those “guessed” landmark are approximate:

• Navigation in the top left panel “Application” is split in two landmarks instead of the panel being only one navigation landmark
• The main content guessed contains all the extra info about the page: title, breadcrumb, likes, tags, comments,…

For now, only navigation landmarks are used on some elements and are not guessed.

I think adding proper landmarks for sections is important as this will make XWiki behavior with different screen-readers more stable (they won’t need to make guesses) and more in-depth.
I think making sure view pages have correct landmark is the most important. Those pages are the ones where most of the standard user navigation happens and those where disabled users might be the most impacted by the quality of the landmarks.

Those are the landmarks that can be added on view pages:

• Navigation on all panels with the navigation category
• Section: for other panels (unrelated to page content)
• Main: content of the page, with the class=“main”, the XDOM parsed
• Aside (aria-role: complementary) : info supporting the main content
  – page title and all the “page header” with it.
  – “page footer” with tags, comments, attachments, …
• Footer (aria-role: contentinfo): bottom of the page, with the xwiki version number, possibly a license and socials

Note: main, header/banner and footer/contentinfo must not be present twice on the same page. Using them in XWiki landmarks might create regressions if they are already used in the page content.

Currently, the top section is already marked as a navigation, this could be changed to <header>.
The result would be similar to this:

What do you think of this?

I’m looking forward to your comments on the matter.

[vmassol]

@CharpentierLucas

The result would be similar to this:

I haven’t read the links above nor researched the topic but your proposal sounds good to me.

Thanks!

[MichaelHamann]

In general +1. I don’t totally agree with your assessment what the main content should be as I think that the title should be part of the main content (unless it is already provided to screen reader users). Also, I think the “Edit” and “Create” buttons with the content menu should be part of some special role such that they can be easily reached, maybe another navigation role (no idea what the best practice is here)?

[CharpentierLucas]

@MichaelHamann

I don’t totally agree with your assessment what the main content should be as I think that the title should be part of the main content (unless it is already provided to screen reader users).

Okay! I think we can set as main the element with the class xcontent on these view page. I’ll need to check what this class is used for in other pages, but it seems like what you described.

@MichaelHamann

Also, I think the “Edit” and “Create” buttons with the content menu should be part of some special role such that they can be easily reached, maybe another navigation role (no idea what the best practice is here)?

For the edit and create buttons, they could technically have a navigation role (they contain links), however I think complementary is more suited for them. This choice is also motivated by the already high amount of nav landmarks we have in the layout.
Those buttons are not part of the content, but for the most part they are linked to actions that are based on the content. They cannot work independantly from the content.

ARIA: complementary role - Accessibility | MDN

I created an issue on jira, and I’ll start working on it soon if there’s no assignee by then:
https://jira.xwiki.org/browse/XWIKI-20696

[MichaelHamann]

@CharpentierLucas

For the edit and create buttons, they could technically have a navigation role (they contain links), however I think complementary is more suited for them. This choice is also motivated by the already high amount of nav landmarks we have in the layout.

I think that makes sense. Also, I’ve remembered that we have keyboard shortcuts for the most important actions that are represented by these buttons and the menu so most likely it’s not that important to have them that easily accessible.

@CharpentierLucas

I created an issue on jira, and I’ll start working on it soon if there’s no assignee by then:
Loading...

It’s hard for me to judge how important these landmarks are, but from my current understanding they seem quite important for accessibility. If this is correct, I would consider the lack of landmarks a bug and wouldn’t mark it as minor. For me the point with a “bug” is also that we normally only backport bug fixes to the LTS version (currently 14.10.x) (the exception being features or improvements that are required for fixing a bug). Another criteria is the potential for breakages, when a change seems too risky, we also don’t backport it. My understanding is that in this case you would only add a couple of “role”-attributes so this shouldn’t break anything. In general, I would suggest to consider all accessibility improvements bug fixes as in theory XWiki should be WCAG-compliant unless something is really clearly a new feature/improvement that doesn’t fix an actual issue.

[vmassol]

@MichaelHamann

I would suggest to consider all accessibility improvements bug fixes as in theory XWiki should be WCAG-compliant unless something is really clearly a new feature/improvement that doesn’t fix an actual issue.

It depends about the topic and the risk of backporting it. Being less accessible is not always a bug, same as being less usable because the UX is not great. The most important is the stability of the LTS.

Also we’re not supposed to backport all bugs to the LTS, only important ones.

[CharpentierLucas]

@MichaelHamann

I don’t totally agree with your assessment what the main content should be as I think that the title should be part of the main content (unless it is already provided to screen reader users).

I did some more searching as I’m now working on XWIKI-18838: main landmark for all pages and setting a proper main and being regular with what we mean by them is mandatory.

The content of a <main> element should be unique to the document. Content that is repeated across a set of documents or document sections such as sidebars, navigation links, copyright information, site logos, and search forms shouldn’t be included unless the search form is the main function of the page.

So as you said, the main should include the title (unique to this page), but if possible avoid the breadcrumb (repeated/navigation).
Even though the edit, create and more actions buttons are not visually unique, they are functionally unique (i.e. clicking on ‘edit’ here will perform the unique action ‘edit ’).

[mflorea]

@CharpentierLucas

So as you said, the main should include the title (unique to this page), but if possible avoid the breadcrumb (repeated/navigation).
Even though the edit, create and more actions buttons are not visually unique, they are functionally unique (i.e. clicking on ‘edit’ here will perform the unique action 'edit ').

The breadcrumbs are also specific to the page (so unique). It’s like a “file path” (each file has its own file path). Each page has its own different breadcrumbs (because the breadcrumbs include the title of the page). Sure some parts of the breadcrumbs are shared with other pages, but I think we have to look at it as a single element (we cannot split it in two landmarks). So for me it makes sense to have it in the main landmark.

[CharpentierLucas]

The content of a <main> element should be unique to the document. Content that is repeated across a set of documents or document sections such as sidebars, navigation links, copyright information, site logos, and search forms shouldn’t be included unless the search form is the main function of the page.

From <main>: The Main element - HTML: HyperText Markup Language | MDN.
I took this quote since it seemed like the usage notes were easier to understand. Hereafter is the definition of <main> from MDN too:

The <main> HTML element represents the dominant content of the <body> of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application.

The breadcrumbs are unique, but a breadcrumb is still a list of navigation links. Breadcrumbs are not related to the content of the document, but to the document itself and the structure of the wiki.

We should also consider what we want the user to see when they navigate to the main content. In most cases the breadcrumbs would be the first element.

This is not so clear, so let’s take the use case of a blind user using a screen reader to read content about … goats on a page and see what would happen:

0. The user followed a link about grey goats. The page loads, the user is at the top of the page.
1. Get to the main landmark (easy, one or a couple keypresses depending on the screen reader). The user expects to be reading about grey goats from now on.
2. Go through the breadcrumb. The breadcrumb is information related to the page but not information about goats.
3. Read the title: Grey goats. The user can confirm that they are on the right page.
4. Read the page content: Grey goats are a species of mountain goats […]

Here is a demo I made quickly to highlight this use case
Screen reader: NVDA.
Bottom right: the output of the screen reader, written down.
Bottom left: my keyboard/mouse inputs.
Green/red rectangles: current focus of the screen reader
Pink rectangles: landmarks on the page.

The goat page has no breadcrumb inside it and the administration page does. One key thing that was highlighted by this demo and didn’t think about is that the landmark name reflects the first element. If the title is the first element, it’s way easier to understand than having the breadcrumb used like a title. I guess we could fix this by adding an aria-labelledby to the main if the label is not the first item.

I think keeping the breadcrumb in there would be annoying since it’s mandatory to go past it to access content. Moreover it’s not really useful since:

• the breadcrumb itself has its own landmark that makes it easy to access with landmark navigation (depending on the screen reader, can be the same complexity or a bit more difficult to reach than the main content).
• the user can already confirm they are on the right page from the title of the page.

For the same reasons, we could also decide to leave the edit/create/more actions buttons out. But I think it’s more difficult to do since they are currently in between the title and the page content in the DOM.
In consideration to the user, I think leaving the breadcrumb out of the main landmark would be better.
What do you think of this?

[mflorea]

@CharpentierLucas

the user can already confirm they are on the right page from the title of the page.

A wiki page is not uniquely identified by its title but by it location. In practice most pages have a different title, but it’s not exotic to have multiple pages with the same title, in different locations. I suppose it’s fine to leave the breadcrumbs outside of the main landmark, provided there’s a simple / quick way for a blind person to find the location of the current page (its breadcrumb).

[CharpentierLucas]

@mflorea

I suppose it’s fine to leave the breadcrumbs outside of the main landmark, provided there’s a simple / quick way for a blind person to find the location of the current page (its breadcrumb).

This is planned in the solution for XWIKI-20696

A sighted user will not read the breadcrumb everytime when landing on a page. We “say” that in the UI by making the breadcrumb font smaller and lighter than the regular content. We “say” this to limited sight users by not putting it into the <main> region.
The background and position of the breadcrumb in the UI serves the same role as making it a <nav> landmark, it “says” something along the lines of:

• this is one unit (and not just a bunch of unrelated anchors)
• this is an important section, keep it in mind, you might need it at some point.