Accessibility guide for developers - MediaWiki (original) (raw)

Languages:

Accessibility is important for our users and we can improve it if we take into account a few basic ideas and rules. Accessibility is difficult insofar as there are no fixed and universally accepted technical standards that actually work consistently and for all users. This page does not list or discuss specific accessibility problems in MediaWiki. It attempts to focus on technology choices and Dos and Don'ts to prevent accessibility problems.

In terms of development, I think this should be our rule book:

Some important concepts that you should keep in mind.

Accessibility measurements in many forms

[edit]

Accessibility is about a variety of things, please consider the following:

In summary, accessibility is not only keyboard accessibility or only screen reader accessibility. We often focus on these two because they traditionally are easily overlooked. But these issues are also solvable and often provide the basis for any other sort of improvements to be possible.

Some accessibility problems tend to be problems with product design, strategic choices, target audience etc. As these areas are more difficult to capture in written down rules that apply universally to the MediaWiki ecosystem, they are outside of the scope of this document.

Keyboard navigation

[edit]

We call this keyboard navigation, but what it really means is: Don't rely on a pointer device (touch, mouse).

There are several standards around accessibility and honestly, almost all of them, although sound on identifying issues, still have significant problems when it comes to technical solutions (They have a high ratio of 'ugly workarounds'). This has been cause of much controversy in the communities. As such, we should identify uncontroversial stuff that we should simply always (or never) do and why. It's much easier to reach certain goals if we separate the uncontroversial stuff from the controversial stuff.

Do use or provide always

[edit]

Proper semantic HTML element

Use HTML elements for their intended purpose. For example:

Logical heading structure

All pages should always have a logical and consistent heading structure. Headings are one of the primary navigation tools used by screen reader users.

  1. There should be no gaps in the nesting of the heading levels. (So no H2->H4.)
  2. Headings should be descriptive
  3. Headings should be unique within their own level. (There should not be two H3s with the same content under the same H2 section)
  4. There should be separation between navigation and content

alt attribute for images with meaningful values

If an image is decorative, use an explicit empty value for the alt attribute; even better, turn it into a CSS background image.

the image alt usually takes precedence over the title attribute of images and even over the title attribute of links that wrap an image.

title attribute for links

These are usually shown as the tooltips

Only use titles if they differ from the link text.

Most link titles are not actually spoken by screen readers, unless the reader has been explicitly configured this way.

lang, dir and hreflang attributes

Using lang and hreflang enables selecting a proper voice in screen readers, picks the right spelling correction in browsers etc.

Sufficient contrast

Always check your colors for sufficient contrast. For text, a higher contrast is needed for smaller text (due to anti-aliasing).

Focus for keyboard navigation

Do not remove outline from focusable elements unless you define your own outline for the :focus state.

Keyboard navigation

Interactive elements of a page should be navigable by keyboard. Please make sure tab key navigation is enabled in your browser and allows you to control each interactive element without making use of a pointing device.

  1. Use tabIndex: 0 to make elements keyboard accessible, which are not keyboard accessible implicitly (Anything but ‎<a>, ‎<area>, ‎<button>, ‎<input>, ‎<object>, ‎<select>, ‎<textarea>).
    1. In this case also add a keydown handler responding to Enter (keyCode 13) and space (keyCode 32).
  2. Use tabindex: -1 to remove elements from accessibility. (use this on links that are labels for the action inside an ‎<li>...‎</li> for instance)
  3. Elements that are implicitly keyboard accessible will forward enter/space keydown to the click handler

Dialogs etc.

When not taking good care of accessibility, dialogs are some of the most inaccessible elements for screen reader and keyboard users.Spend some time on this.

WCAG 2.1 guidelines

Follow wherever possible

And its accompanying documents:

Unicode symbols

Most assistive technologies are not good with symbols. Therefore, try to avoid characters such as ↑, →‎ or more complex characters, because many screen reader won't understand them. If they are required, try to wrap with a span element with the title attribute, so that the title attribute can communicate the implicit meaning within the context to the reader.

Small fonts

Legibility is preferred. If you make something so small that it is hard to read, do you even need it to begin with? Also avoid small fonts with low or mediocre contrast values (even if they fall inside the WCAG guidelines, small sizes require more explicit contrast then large sizes, especially with anti aliasing enabled).

Unusually large fonts

If you make text much larger than normal, it can become similarly hard to read (unless it's very short). This applies mostly to body text, or anything that takes up more than a couple lines. But the larger the text is, the more lines it will take up.

tabIndex > 0

DOM order is preferred wherever possible. DOM order provides context for the actions.

Workaround

Traditionally, accomplishing 'full' accessibility has required a lot of workarounds for html itself, the browsers and even specific screenreader software. However these workarounds often come with side effects, make use of bugs or unspecified behavior and inevitably create technical debt.

MediaWiki, because of the users it seeks to serve, the amount of code, it's (lack) of funding, etc tends to prefer future proof code over code that easily breaks. As such it generally avoids workarounds even if that might sometimes limit the accessibility we can deliver. Decisions on this are often influenced by the relative audience of the feature in MediaWiki. If something is ubiquitous for all users a workaround is more warrented than if the feature affected is only used by a tiny part of the audience (for instance, reading a page vs modifying the configuration of the installation).

  1. ↑ See DOM order at w3.org and Style order Property at w3schools.org