Accessibility guide for developers/ar

إن مسألة تيسير الوصول ذات أهمية بالغة لمستخدمينا ويمكننا تحسين مستوى تيسير الوصول لو نظرنا بعين الاعتبار إلى بضع أفكار وقواعد أساسية. إن مسألة تيسير الوصول تصبح صعبة المنال منذ أنه لا توجد معايير قياسية فنية ثابتة ويقبلها الجميع ينتج عنها نتائج متساوية ولكل المستخدمين. لا تسرد هذه الصفحة أو تناقش مشاكل تيسير وصول بعينها موجودة في برمجيات ميدياويكي. تحاول هذه الصفحة التركيز على خيارات التقنية وكذا ما يجب فعله وتجنب فعله لتلافي حدوث مشاكل تتعلق بتيسير الوصول.

من ناحية تطوير البرمجيات، أرى أن هذه الصفحة يجب أن تصبح دليل قواعد نتبعه:


 * حاول تيسير الاستخدام لكافة المستخدمين (ويعني هذا كلهم دون استثناء)
 * حاول البحث عن سبيل للتغلب على مسائل تيسير الوصول لو كان هذا ممكنا، إلا أن هذا يجب ألا يكون مهما كلّف الأمر
 * يجب علينا أن نتبع سبيل التحسين التدريجي بديلا عن اتباع سبيل تقليل الإمكانات الذي يراعي الجميع.
 * تنفيذ أمور ذات مسوّغ تقني

علينا ألا ننسى أبدا أننا نعتبر بالفعل من بين يسيري الوصول.

كيفية عمل أمور تيسير الوصول
بعض المفاهيم الهامة التي يجب عليك أن تنظر إليها بعين الاعتبار.

مقاييس تيسير الوصول تستعين بأشكال كثيرة
إن تيسير الوصول يتناول تشكيلة مختلفة من الأمور، لذا يرجى النظر بعين الاعتبار لما يلي:


 * أن يكون أمر ما يسير الاستيعاب: يعني هذا أن يكون يسير الاستيعاب من نواحي النص والمظهر والمنطق وحينما يكون جزءا من كل
 * يحتاج بعض المستخدمين لاستخدام قارئ للشاشة لتيسير التفاعل، ألا أن ثمة أمور أخرى أكثر انتشارا من هذه وهي: عدسة مكبرة أو رفع مستوى التباين أو استخدام محرك يحول النصوص إلى كلام منطوق أو إعدادات سي إس إس مخصصة أو نوع خاص من لوحات المفاتيح أو أجهزة الإدخال.
 * يجب أن تكون في المتناول أي سريعة الاستجابة وقليلة التكلفة ومتوفرة في المنطقة الجغرافية وبلغة المستخدم ونوع العتاد المطلوب لها وخلافه.

بعبارة موجزة، لا يجوز اختصار تيسير الوصول في مجرد تيسير الوصول على لوحة المفاتيح أو مجرد تيسير الوصول إلى قارئ للشاشة. غالبا ما نصب جهودنا على هذين الاثنين لأنهما في العادة يقعان ضحية للإغفال. إلا أن هذه المسائل يمكن حلها وغالبا ما تقدم أساسا لأية أنواع أخرى من التحسينات الممكن تنفيذها.

تميل بعض من مسائل تيسير الوصول إلى أن تكون مشاكل في تصميم المنتج أو خيارات استراتيجية أو اختيار الجمهور المستهدف أو خلافه. منذ أن هذه الجوانب يصعب تسجيلها كتابة في قواعد مكتوبة تنطبق بوجه عمومي على منظومة ميدياويكي بوجه عام، هي خارج نطاق تغطية هذه الوثيقة.

استخدام لوحة المفاتيح في التنقل
ربما نطلق على هذا الأمر «keyboard navigation»، إلا أنه يعني في الواقع: لا تركز على استخدام جهاز تأشير (لوحة تعمل باللمس أو فأرة).


 * إن استخدام لوحة المفاتيح في التنقل يستند إلى الاستعانة بالتركيز وتنفيذ الأعمال باستخدام لوحة مفاتيح الجهاز المستخدم.
 * العناصر التي يمكن استخدام زر التبويب «Tab» للذهاب إليها يمكن التركيز عليها، بينما أن العناصر التي يمكن التركيز عليها لا يمكن استخدام زر التبويب للذهاب إليها.
 * كل شيء يمكن لك أن تفعله مستخدما الفأرة يجب أن يكون ممكنا باستخدام لوحة المفاتيح.
 * يمكن لقارئات الشاشة استخدام معلومات التصفح باستخدام لوحة المفاتيح في تحسين خبرة استخدامها.

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 an 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


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


 * 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 and thus the text will not be read either. (aria-label is often the better choice).
 * Lastly, this enlarges the render surface needed to calculate the final webpage and this can impact performance on mobile devices.
 * Insightful overview of 'hide text offscreen' tricks are given by Jonathan Snook.
 * Things should not be repeated often. If you have a 100 links on a page that can open a dialog, then don't add 100 labels to those 100 links telling the user that it can be used to open a dialog. Telling a user how to use/what to do with the interface is a good thing, doing it consistently is simply annoying. Find a different way to explain it once (an  might be an idea in this case ?).
 * with an onclick handler. VO reads such JS as "internal link Hide". Use a proper button, or, with 'space' and 'enter' key handlers in the onclick. But no href attribute.

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 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.
 * Workarounds : 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).

Consider

 * ARIA Roles
 * If a div or span behaves like an actual button use . also   and
 * Be careful with roles. For instance, don't add  to a   element, since the   element has an implicit , which will be overwritten. Instead use  . Similarly for   which has an implicit
 * If a button creates a popupdialog, use.
 * Use  for contexts where this is not fully logical by itself (so everywhere except 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

 * Usage of  in labels. Ending a label with a dot, causes the screen reader to make a fullstop. See also: 24592 where the lack of fullstops creates unintelligible sentences.

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)