Description

This is the first draft of a proposal for a set of accessibility guidelines to adopt in the community.

Accessibility guidelines

Introduction

XWiki aims at fulfilling the accessibility requirements for the Web Accessibility Guidelines (WCAG) 2.2 level AA. If you find a problem related to accessibility in XWiki, don't hesitate to report it! Accessibility gets an effort that is more powerful the more actors participate in it.

Unfortunately, there will never be a perfectly accessible XWiki. Accessibility is a nuance, and our view is to keep getting closer to the "accessible" part of the spectrum. Accessibility is a criteria based on user experience, so XWiki's accessibility will evolve with its users and need regular attention. Following these guidelines should be enough to keep a basic level of accessibility in XWiki.

Most of the guidelines come with a set of DO and DON'T entries. In order to understand them all, looking at the way they are rendered in your browser is as important as looking at the way they are implemented using the "Inspect" feature of your browser. Some of those DOs and DON'T will look exactly the same on your browser, in this case it's especially important to check their HTML.

Design

Accessibility is a part of usability, and as such it should not be forgotten while designing. Making sure a design respects those accessibility guidelines will make it easier down the line for implementation and testing, and will end up in a better user experience.

Color Contrast

When picking text and icon colors, make sure they respect a minimum contrast of 4.5. If possible, try to keep this contrast above 7 too.

• WCAG recommendation: Success Criterion 1.4.3 - Contrast (Minimum)
• Checking contrast between two colors
• Understanding what is contrast
• The WebAim contrast checker to find the contrast between two colors on a webpage.
• DO I have enough contrast to be easily read.
• DON'T I don't have enough contrast to be easily read. I rely only on the standard perception of colors to convey my message.

Interactive element size

An interactive element should have a minimum size of 24×24px. If possible, try to keep this size above 44×44px.

• WCAG recommendation: Success Criterion 2.5.8 - Target Size (Minimum)
• For example, an interactive element is any element you could tap when using XWiki on your phone. This guideline makes sure they are not too difficult to interact with, even if your screen is small!
• Understanding the target size guideline
• Bookmarklet to check out what a 44×44px element would look like on your webpage
• DO
• DON'T

Convey meaning

Whenever you want to communicate an information to the user through colors or icons, make sure there is a text alternative to convey this information. If possible, this text alternative should be visible.

• WCAG recommendation: Success Criterion 1.4.1 - Use of Color
• The vision of colour is something that changes for everyone. Some users can't perceive colour information and should have an alternative way to understand your design.
• Icons are convenient but can be confusing for users that are not used to the web. A text alternative is a reliable fallback for them.
• DO The reactor core has melted away!
• DON'T The reactor core has melted away!

Focus state

All interactive elements should have a visible focus state. By default,  this is done with a blue focus ring. However, if this focus ring needs to be removed for design purpose, another way to display the focus state should be considered, for example a change of background and font colors.

• WCAG recommendation: Success Criterion 2.4.7 - Focus Visible
• DO Focus me by using tabs for example! I'll be highlighted with a blue ring
• DON'T Focus me! Did you really focus me?

User flow

When visualizing how users interact with a feature, keep in mind that they won't only use a mouse. They might also use a touchscreen (smartphones), keyboard and screen reader. Interaction patterns such as "drag and drop" become non trivial with some of those combinations and this complexity should be considered when picking a design.

• The focus finder extension for Firefox can help you keep track of the focus when checking the user experience with a keyboard.

Landmarks

Some information are implied in the design and should be conveyed even to users with a limited vision. That's why along designs annotations about semantics should be provided because they still improve the experience for low vision users. For example, HTML provides a few landmarks that make it way easier for screen-reader users to navigate a page.

• The HTML landmarks
• Set of bluelines to annotate design files with accessibility information
• This extension for Firefox will list and highlight all landmarks on a page. This makes it easy to see what would be the experience of a screen reader user navigating using landmarks (3.7% of screen reader user's main way to find info - Source).
• DO
• DON'T Leave it up to interpretation. This could just be a couple of links that do not hold particular importance. Design and Development

Development

Semantic HTML

The most important point in developing an accessible front-end is to use standards to convey meaning. The first standard we want to use to its full potential is HTML.

• WCAG recommendation: Success Criterion 1.3.1 - Info and relationships
• What are semantics in HTML? on MDN web docs.
• Making accessible content with HTML on MDN web docs
• DO

  Use semantic elements to convey meaning.

• DON'T Use non semantic elements and complete them with custom styles to convey meaning.
• DON'T Use pseudo classes :before and :after to display any information. They can be used for style purposes though. Any content in those pseudo classes will not be shown to assistive technologies.

Heading levels

Heading levels make most of the structure of content in a web page. They should not be used only for style. Moreover they should be used so that the resulting structure is a clean tree: only use one <h1> and don't skip heading levels.

• WCAG recommendation: Success Criterion 2.4.10 - Section Headings
• Avoid using multiple H1 elements on MDN web docs
• This extension for Firefox will display the heading tree on a page. This makes it easy to see what would be the experience of a screen reader user navigating using headings (71.6% of screen reader user's main way to find info - Source.
• DO Use non semantic elements when there is no particular meaning. Here I just want to have a bigger text.
• DON'T

  Use semantic elements just for their built in styles. Here I created irrelevant meaning and confused the screen reader user.

• DON'T

  Use multiple H1 on the same page.

• DON'T

  Skip heading levels.

Typography

For font-sizes, prefer using relative units like em, rem or percentages instead of absolute units like px. This will facilitate maintenance of the style on the long term and allow for it to adapt to user preferences.

• More about typography units for accessibility
• DO Use relative units.
• DON'T Use absolute units.

Buttons and anchors

It's easy to misuse them, because they both have pretty much the same capabilities. However, for screen reader and assistive technologies users, what could look like a small difference might shape their whole experience differently.
A button does something, an anchor goes somewhere.
This is a baseline on which you can start your reflection on what element to pick.
The tag name and the looks of your element should match. Even though they fulfill similar primary functions, the secondary expectations the user has for them are different. Mismatching nature and looks would break those expectations.

• A guide on links and buttons on CSS Tricks
• DO Hide this page Hiding the page is an action, so we use a button.
• DO See the testing guidelines We expect the user to go somewhere else (the testing section) when interacting with this element, therefore it should be an anchor.
• Edit Editing the page is an action, however it's important to be able to open this action in a new tab, and technically, it could also be viewed as the user moving from one display mode to another (different URLs). "Action links" like this one are a grey area using buttons or anchors are both correct choices.
• DON'T Hide this page When using an anchor instead of a button, it will be difficult or impossible to find a proper href.
• DON'T See the testing guidelines

Alternative text

Images must have a descriptive alternative text. If they hold no semantics whatsoever, use an empty description with alt="".

• WCAG recommendation: Success Criterion - 1.1.1 Non-text Content
• If used properly, an empty alt for an image is better than no alt at all because:
  • No alt means that the image has no alternative text.
  • An empty alt means that the image has no meaning (e.g., icons that repeat the meaning of the text besides them), and therefore an empty alternative text.
• DO
• DO Provide information contextually relevant in the alternative text. See examples on WebAIM
• DON'T Provide an unreadable alternative text. Alternative texts are here for humans to understand.
• DON'T Put an empty alt on a semantically relevant picture
• DON'T XWiki logo -> Put a full alt that would repeat the content besides the picture

Testing

Testing basic accessibility can be simple with the right tools. The tools presented below will help you find accessibility issues of various kinds. The first tool of each list is the main recommendation, but other items might fit your situation better.

Accessibility checklists

The following checklists can guide manual validation of the accessibility of a feature.

• Va11ydette
• The WCAG Conformance Evalution Methodology
• ARA: in french only

Native browser validators

Without anything more than your browser, you can get an idea of the accessibility issues on your page.

• Accessibility inspector: quite technical and needs a bit of getting used to, but very powerful.
• Sa11y: might not work properly on all websites

Browser extensions

• Axe devtools: light and uses the exact same validation heuristics as automated tests.
• WAVE: analysis can also be started from the WAVE WebAIM website
• IBM Equal access accessibility checker : contains two different sets of heuristics to evaluate accessibility.

In-build accessibility testing

The xwiki-platform projects includes accessibility testing in its continuous integration process. When running a build of a module with -Pdocker (activate docker-based functional tests) and -Dxwiki.test.ui.wcag=true (activate WCAG validation), the build will assess all the page objects initialized in the docker-based tests and keep traces of any WCAG violation found. This accessibility validation is based on the axe-core rules.
Those tests can not ensure that a feature is completely accessible, but it can be a big help in finding about half of accessibility violations. You can find more detail about this automatic testing here.

Screen readers

If you want to make sure your component is properly conveyed by screen readers, you might want to use one yourself.

• NVDA (Windows): high rate of use
• Orca (GNOME): very low rate of use
• VoiceOver (iOS/MacOS): low rate of use, often very different than other screen readers in its interpretation
• JAWS (Windows): high rate of use, paid licence or sessions limited to 40 minutes.