Page MenuHomePhabricator

Review and rewrite accessibility guide
Open, MediumPublic


This task is part of a project to establish a formal review process and set of standards for Wikimedia technical documentation. For more information, visit the project page on




To do

Replace this section with the latest version of the review template

Event Timeline

Giving a heads-up to @TheDJ as the original page author. I'd say currently parts of the page are written like a personal essay, and some stuff I have a harder time to understand (which might be fine, I'm not a developer). I'm also wondering what / if there is anything rather MediaWiki specific, or rather general HTML (or JS).

(Note to myself: Furthermore, I remember that four years ago when visiting the WMDE office, they had at least the "Physical or motor disabilities" and "Screenreaders" posters from on the wall.)

Aklapper renamed this task from Review accessibility guide to Review and rewrite accessibility guide.Feb 6 2022, 9:44 PM
Aklapper raised the priority of this task from Low to Medium.Mar 3 2022, 5:09 PM

Feedback and sharing thoughts is welcome:

I went through mw:Accessibility_and_usability_cleanup and considered the following pages [partially] useful (as some mix audiences, e.g. page content vs code development, and some are either outdated or seem to be work in progress):

There were also pages that did not seem useful when it comes to developer focus:

Note that there is also . Also see the scope list on that page.

I drafted some attempts to structure page content, and wondered how detailed to go versus duplicating W3C/WAI guidelines.
Like an introduction with

Accessibility is about designing software with the smallest possible limitations, independent of hardware, software, language, bandwidth, and visual, mental, speech or motor abilities. Good software design improves inclusion and equal access for everyone.<ref></ref>

This may include aspects such as<ref>[[meta:Wikimedia Accessibility User Group#Scope]]</ref> [[w:anxiety|anxiety]], [[w:attention deficit hyperactivity disorder|attention deficit hyperactivity disorder]] and [[w:autism|autism]], [[w:deafness|deafness]], [[w:digital divide|digital divide]], [[w:dyslexia|dyslexia]], [[w:Language barrier|language barriers]], [[w:Persons with reduced mobility|reduced mobility]], [[w:social discrimination|social discrimination]], or [[w:visual impairment|visual impairment]].

''For specific technical issues, see the [[phab:maniphest/query/8NmpeEbYMSWm/#R|software bugs and feature requests related to accessibility]] in [[Phabricator]] instead.''

and then going for sections

  • Assistive technology software (explanation of things that it does, and naming some of them)
  • Recommendations for software developers (covering aspects like semantic HTML elements, Navigation, Symbols and Characters, Decorative symbols and images, Fonts, Keyboard shortcuts and access keys, Colors and contrast, Captchas)
  • Resources for software developers (linking to W3C WAI and to )
  • Software tools for developers (linking to docs for web browsers' developer tools and to external stuff like WAVE)
  • See also
  • References

However, there'd be still a good level of duplication.

So I propose to

  • check whether the design.wm.o page should also cover:
    • Avoid fonts not commonly available on systems (as we end up with issues like T306317)
    • Never use bold text as the only means of implying importance (though that might be more i18n than a11y?)
    • Check if lang, dir, hreflang for screen reader software is worth mentioning
    • Do not state that "Images have to provide alt attributes with alternative text" as purely decorative images should use aria-hidden="true" role="presentation"?
    • Cover using Unicode symbols (with their intended meaning!) instead of images and its pros and cons (screenreader support)
    • Cover Captchas?
    • Mention skipping navigation elements under keyboard interaction?
    • Cover keyboard shortcuts and mnemonics?
    • Cover that tables are for tabular data and not for layout (though this blurs into "content" obviously)
    • Mention using CSS for decorative text like square brackets?

I'm also curious what might be the outcome of T310033: [Spike] Define questions that we want to ask experts testing modern Vector with screenreader users. And wonder if and should be linked from somewhere but we already have a horrible pattern of "Let's throw billions of links at people to overwhelm them".

Also looks like @Volker_E et al plan to look a bit into a11y docs this very week

My idea is, and I've put this onto the cleanup talk page, to have a four-level checklist/information hub with general recommendations and then slightly different content for product managers, designers and developers on top.

Fully agree, that it makes 0 sense to try replicating the real WCAG standard docs. It's better to strongly interlink both inside and outside documentation.

I will just state a few things that I applied to my original document and why I applied them.

  • It is specifically targeting developers, because developers generally have very wide spectrum of things they are supposed to know, but often just don't know. It was as an accompanying document to all the other developer guidelines they are supposed to 'always take into account', one spot, one set of guidelines.
  • It explains that accessibility has more aspects than just the technical aspects communicated to screenreaders (because we think in tech solutions)
  • It explains that in the tech part, there are two very distinct things to work on: keyboard accessible vs screenreader accessible
  • It gives understandable tech solutions instead of pages and pages of details to wade through (no one got time to read WCAG [and actually wcag was still a mess back then])

This approach was based on my experiences trying to explain accessibility to fellow developers.

Never use bold text as the only means of implying importance (though that might be more i18n than a11y?)

This is because using pure bold is an indication that you should be using strong or a header or some other semantic element

Mention using CSS for decorative text like square brackets?

Just a note that browsers are working on making CSS content accessible.

I've been a real fan of the (original) document. What I'd suggest for the “Accessibility measurements in many forms” section is now to orient on the 4 WCAG 2 POUR principles – perceivable, operable, understandable and robust – indicative for pretty much all of what should be considered though.

@TheDJ: Just to make this explicit, I like a lot of parts of the original document. I just don't have a better idea than merging when it comes to how to bring relevant stuff to devs together in preferably 1 document instead of fragmentation in way too many.