Accessibility best-practice: landmarks

Development
#1

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
https://a11y-101.com/development/landmarks

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))
LandmarksDisplayHome

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



What do you think of this?

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

1 Like
#2

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

Thanks!

#3

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)?

#4

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.

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.
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role

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

#5

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.

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.

1 Like
#6

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.