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

 * 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 : null value if purely decorative; or move to CSS background image)
 * title attribute for links :
 * Use the proper HTML element : use the HTML element fitting the function (so you should prefer elements over span, div and a elements)
 * Contrast :
 * The focus pseudo class : if you use :hover, also use :pseudo
 * Use lang and hreflang attributes :
 * 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.
 * 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

Don't

 * There is common advise to use -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.

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.

Consider

 * roles
 * 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/
 * The WCAG 2.0 guidelines