Accessibility guide for developers

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 Do's and Don'ts to prevent accessibility problems.

In terms of development, I think this should be our rule book:
 * Try to enable our users (and that means all of them)
 * Try to work around issues of accessibility if that is possible, but not at all costs
 * We should use an approach y users with disabilities, to an acceptable degree, a useful and operable website." - German Language Wikipedia Accessibility Test According to WCAG 2.0 (archived from the original) by Third Age Online.

Banned usernames

User:Victoriavirus User:Riddle Drive User:No 13th Floor User:Closed Wiki User:Corona Street User:Australiavirus User:Map of World User:The Chemical Warfare

How accessibility works
Some important concepts that you should keep in mind.

Accessibility measurements in many forms
Accessibility is about a variety of things, please consider the following:
 * Something should be understandable: that means textually, visually, logically and in complexity.
 * Some users need a screen reader to interact, but just as, if not more common are: a loupe, higher contrast, a text to speech engine, custom CSS settings, or a special type of keyboard/input device.
 * It needs to be reachable; responsiveness, affordability, location, language, hardware, etc.

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 eco system, they are outside of the scope of this document.

Keyboard navigation
We call this keyboard navigation, but what it really means is: Don't rely on a pointer device (touch, mouse).
 * Keyboard navigation is about manipulating the focus and executing actions with your keyboard.
 * Elements that are tab-able are focus-able, but not everything that is focus-able is tab-able.
 * Everything you are able to do with a mouse should be possible to do with a keyboard.
 * Keyboard navigation information can be used by screen readers to enhance their experience.

Screen reader

 * A screen reader uses a different 'cursor', which usually walks the logical structure of the DOM.
 * The focus tends to follow the screen reader cursor and vice versa, but they are not the same
 * A screen reader uses the 'accessibility' APIs, which you could consider to be a input/output 'view' on top of the normal DOM.
 * ARIA are DOM annotations that enhance or manipulate how the DOM logic is transformed into the accessibility APIs. It is not an alternative to writing proper HTML and JavaScript. Keyboard navigation is simply achieved by logical DOM orderǃ For more on ARIA see w3.org explanation and mozilla.org explanation.
 * A screen reader is not limited to navigating by the logical DOM structure, it's just the default. A screen reader can read what is under the mouse pointer for instance, and VoiceOver for iOS uses a screen cursor that is manipulated by thumb positioning and gestures on the touch screen. It can navigate by landmark areas, an auto-generated Table of Contents, or even user defined 'bookmarks' inside a page.
 * From the above point of multiple navigation methods, follows: There is a beginning and an end, but also left, right, top and bottom. You should not rely on these in your communication too much, but you don't need to fully deny their existence either. Do not confuse the visual capabilities of the user with spatial awareness that the screen reader might be able to convey to the user. Example:
 * a long sentence [image] the above image shows...
 * a long sentence [image][image] the left image shows, the right image shows...
 * a long sentence [image][image] the above image shows...
 * a long sentence [image][image][image] the left image shows, the right image shows...
 * a long sentence [image][image] something totally different. the left image shows, the right image shows...

Development guidelines
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

 * Proper semantic HTML element : Use the HTML element fitting the function, for example
 * Prefer elements over ,   and   elements
 * If you feel the need to bold something, consider if it is not more appropriate to use a header or a  element


 * 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.
 * There should be no gaps in the nesting of the heading levels (So no H2->H4)
 * Headings should be descriptive
 * Headings should be unique within their own level. (There should not be two H3's with the same content under the same H2 section)
 * There should be separation between navigation and content
 * Use a tool like Firefox accessibility evaluation toolbar to easily inspect the structure of all headers.


 * 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. some tests


 * 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.


 * and  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  state.
 * Don't use  otherwise.
 * If you define any pseudo class, like :hover or :active, please also define a  style.


 * Keyboard navigation :The tools should be navigable by keyboard. Please turn that on in your browser if you are a developer.
 * Use tabIndex: 0 to make elements keyboard accessible, which are not keyboard accessible implicitly (Anything but ,, , , , , and ).
 * In this case also add a keydown handler responding to Enter (keyCode 13) and space (keyCode 32).
 * Use tabindex: -1 to remove elements from accessibility. (use this on links that are labels for the action inside an li for instance)
 * Elements that are implicitly keyboard accessible will forward enter/space keydown to the click handler

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.
 * Dialogs etc
 * The element that opens the dialog should have
 * The dialog itself should have
 * The dialog should be inserted in DOM order, or aria owns/controls needs to specify this relation between opening element and dialog
 * When opening the dialog, remember last focused element and shift focus to the first focusable tabbable element inside the dialog
 * When the dialog is modal, make it impossible to interact with the rest of the page
 * Capture clicks outside the dialog and ignore them or let them dismiss the dialog
 * Make sure you cannot tab to links or input elements outside of dialog
 * Make elements outside of the dialog unreachable for screen reader, by using aria-hidden
 * Make sure there is a close mode (esc key and a focusable close button with a descriptive title)
 * Closing should return the (keyboard) focus to the original focus point that you stored when you opened the dialog. For screen readers to return to the same point, be sure to specify the right owner of the dialog, if you have not inserted the dialog in DOM order.
 * Read up: Aria modals, Aria modal dialog, ARIA nonmodal dialog, ARIA tooltips.


 * WCAG 2.1 guidelines : Follow wherever possible
 * And its accompanying documents:
 * A guide to understanding and implementing Web Content Accessibility Guidelines 2.0
 * WCAG 2.1 supplement
 * Techniques and Failures for Web Content Accessibility Guidelines 2.0
 * WCAG 2.1 supplement

Don't

 * There is common advice to use  to push something (often the labels of icon buttons) out of the viewport for visual users and still have it in the accessibility DOM.   is variant of this. This is BAD advice.
 * This breaks our RTL rendering in several browsers. Specifically in rtl mode it creates a large canvas left of the viewport and scrollbars, much as +1000px would create in ltr mode. (If needed,  is preferred over   to avoid this).
 * VoiceOver on mobile is unable to use this text as a fallback, since it is a 'positional' screen reader. You cannot move your finger over this text ://www.w3.org/WAI/tips/ W3C Web Accessibility Initiative: Tips for Getting Started]
 * W3C Web Accessibility Initiative: Web Accessibility Evaluation Tools List
 * Firefox accessibility evalutation toolbar-extension. Can be helpful to spot the most obvious problems.
 * Demo version of JAWS. usable for 40 minutes per computer reboot.
 * Fangs A Firefox tool which gives you a textual emulation of what a screen reader might make of a page.
 * WAVE a Web accessibility evaluation tool
 * Accessible web forms TheDJ (talk) 15:42, 6 August 2013 (UTC)
 * Accessibility simulation on MediaWiki. Experience a page as a color blind person would experience it.
 * Understanding WCAG Level
 * NoCoffee Chrome extension to simulate various vision impairments
 * https://www.deque.com/axe/ good browser extension for accessibility auditing a page
 * https://www.powermapper.com/products/sortsite/checks/accessibility-checks/ webapp for accessibility auditing. See also https://www.powermapper.com/tests/
 * Accessibility and usability cleanup

Papers

 * "Making Wikipedia editing easier for the blind". 2008. M. Claudia Buzzi, Marina Buzzi. IIT-National Research Council. DOI:10.1145/1463160.1463210
 * "Is Wikipedia Usable for the Blind". 2008. Marina Buzzi (IIT), Barbara Leporini (ISTI). p. 15-22.
 * "Wikipedia, the open encyclopaedia: is it really open to blind users?" (Conference paper). 2008. j. ACM. Barbara Leporini. DOI:10.1145/1368044.1368049 (Derived from parent work)