Accessibility guide for developers

Accessibility is important for our users and most of it is easy to facilitate if we just take into account a few basic ideas and rules. Accessibility is also very difficult in that there are no fixed and universally excepted technical standards. This page does not list or discuss specific accessibility problems in MediaWiki. It attempts to focus on technology choices and on 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 for every price
 * We should use an approach of Progressive enhancement over that of Graceful degradation.
 * Implement things that are technological sound

We should never forget that we already are considered to be quite accessible.

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.

Always

 * Use the proper HTML element : use the HTML element fitting the function (so you should prefer elements over span, div and a elements)
 * Logical header structure : All pages should always have a logical and consistent header structure.
 * 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.


 * alt attribute for images : 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


 * 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 screenreaders, unless the reader has been explicitly configured this way


 * Contrast : Check your colors for sufficient contrast
 * The focus pseudo class : if you use :hover, also use :focus
 * Use lang and hreflang attributes : this makes it possible to select a proper voice, and picks the right spelling correction etc.
 * Use lists for logically grouped data : move hlist of en.wp into core to facilitate this?
 * 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 accessibly 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 form 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


 * Bolding and notes : If you feel the need to bold something, consider if it is not more appropriate to use a header or a strong/em element
 * WCAG 2.0 guidelines : follow wherever possible

Don't

 * There is common advise to use left: -1000px to push something out of the viewport for visual users and still have it in the accessibility DOM. This is BAD advice, it 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, top: -1000px is preferred over left: -1000px and combine it with the attribute aria-hidden="true".

Avoid

 * Unicode symbols : Most assistive technologies are not good with symbols. Therefore, try to avoid characters such as &uarr;, →‎ or more complex characters, because many screenreader 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).
 * tabIndex > 0 : DOM order is preferred wherever possible. DOM order provides context for the actions.

Consider

 * Roles
 * If a div or span behaves like an actual button use role="button". also role="dialog" and role="alert"
 * Be careful with roles. For instance, don't add role="button" to a  element, since the   element has an implicit role="columnheader", which will be overwritten. Instead use role="columnheader button". Similarly for  which has an implicit role="listitem"
 * If a button creates a popupdialog, use aria-haspopup.
 * Use aria-labelled-by for contexts where this is not fully logical by itself (so everywhere but for labels in forms and headers in tables).
 * avoid tables for layout purposes. We have some places where they are hard to get rid of (use WAI-ARAI ?)
 * hide stuff: http://www.paciellogroup.com/blog/2012/05/html5-accessibility-chops-hidden-and-aria-hidden/
 * skip/jump to links

Things to discuss

 * Roving tabindex vs. aria-activedescendant (roving more compatible, aria-activedescendant more 'compatible?'
 * Should we mark Hide used for onclicks as role=button ? VO reads such JS as "internal link Hide"
 * Usage of . in labels. Ending a label with a dot, causes the screenreader to make a fullstop. See also: 24592 where the lack of fullstops creates unintelligible sentences.
 * It seems that setting the ariaProperties with .prop isn't working in at least Safari+VO. Possible root cause, the DOM is duplicated and .prop only updates the plain DOM object, not the accessibility DOM object ?
 * aria-label is not used by JAWS (14) if you put it on a span (with contents?). The element needs to be either a control/widget or to have a role. TheDJ (talk) 13:44, 18 August 2013 (UTC)

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)