From 5527df91921b54b9fd1eb9aca3aabe91ec58a9c7 Mon Sep 17 00:00:00 2001 From: Thibaud Colas Date: Thu, 5 Oct 2023 06:11:57 +0100 Subject: [PATCH] Added accessibility guidelines for contributors. --- docs/internals/contributing/accessibility.txt | 171 ++++++++++++++++++ .../contributing/bugs-and-features.txt | 3 + .../contributing/writing-code/index.txt | 1 + .../writing-code/submitting-patches.txt | 2 + .../contributing/writing-code/unit-tests.txt | 5 + docs/spelling_wordlist | 1 + 6 files changed, 183 insertions(+) create mode 100644 docs/internals/contributing/accessibility.txt diff --git a/docs/internals/contributing/accessibility.txt b/docs/internals/contributing/accessibility.txt new file mode 100644 index 0000000000..cd5f2727e1 --- /dev/null +++ b/docs/internals/contributing/accessibility.txt @@ -0,0 +1,171 @@ +============= +Accessibility +============= + +The Django project is committed to ensuring that websites built with Django are +usable by everyone, including people with disabilities. Django's built-in +components, such as the admin interface and default form rendering, should +adhere to established accessibility standards and meet our own targets for +supporting specific input devices and assistive technologies. + +.. _accessibility-standards: + +Accessibility standards +======================= + +We work to conform with the `Web Content Accessibility Guidelines`_ (WCAG), +version 2.2, at the AA level. WCAG is the most established standard for web +accessibility. `AA-level guidelines`_ are the most common legal compliance +target worldwide. + +We also aim to follow other best practices, such as: + +* WCAG 2.2 `AAA-level guidelines`_ – stricter criteria that go beyond the AA + level. +* The upcoming `WCAG 3.0`_ guidelines – a new, evolving standard that aims to + unify and improve upon previous versions of WCAG. +* `Authoring Tool Accessibility Guidelines`_ (ATAG) 2.0 – guidelines for + software and services that are used to produce web content. + +To learn more about accessibility without diving straight into standards, we +recommend `The A11Y Project`_, a community-driven effort to make digital +accessibility easier. + +.. _Web Content Accessibility Guidelines: https://www.w3.org/TR/WCAG22/ +.. _AA-level guidelines: https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=aaa +.. _AAA-level guidelines: https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=a%2Caa +.. _WCAG 3.0: https://www.w3.org/TR/wcag-3.0/ +.. _WCAG 3.0: https://www.w3.org/TR/wcag-3.0/ +.. _Authoring Tool Accessibility Guidelines: https://www.w3.org/TR/ATAG20/ +.. _The A11Y Project: https://www.a11yproject.com/ + +.. _accessibility-support-targets: + +Support targets and testing +=========================== + +Beyond standards, we want to make sure Django actually works for people using a +wide range of input devices and assistive technologies. This has benefits to +make sure Django works better `for everyone`_. The best way to do this +effectively is to take accessibility considerations into account as part of +designing features. If in doubt, consult with users who rely on assistive +technologies or with accessibility experts. You can reach out to the +`Accessibility team`_ via the `Accessibility Django forum topic`_ or via the +``#accessibility`` channel on the `Django Discord server`_. + +.. _for everyone: https://en.wikipedia.org/wiki/Curb_cut_effect + +.. _accessibility-testing-baseline: + +Testing baseline +---------------- + +Design the UI with accessibility in mind, and the testing will only be needed +as a final check. For more complex interfaces, confer with other contributors +to decide on testing targets. Reach out to the `Accessibility team`_ for +support and to coordinate testing. + +Always test user interface changes with: + +* Keyboard-only navigation. Common issues include: + + * An interactive element can't be reached using the Tab or arrow keys. + * An interactive element "traps" input focus and prevents navigating away. + * An interactive element doesn't give a visible indication when it has input + focus. + * The focus order is inconsistent with the logical order that's communicated + visually. + +* The `Accessibility Insights`_ browser extension's automated checks feature, + or an equivalent tool with the `Axe`_ checker. + +Where the UI changes could affect those modalities, also test with: + +* Touch-only navigation. Common issues include: + + * A touch target (interactive element) is too small. + * Hover-based based interaction which does not translate to touch, such as a + hover only tooltip. + +* 400% browser zoom. Common issues include: + + * Content is cut off or disappears when zoomed. + * Content that does not inherently require a two-dimensional layout causes + scrolling in both directions (vertical and horizontal). Two-dimensional + scrolling is acceptable for content like images, maps, videos, and data + tables, which require both dimensions to be usable. + +* Forced-colors mode (for example Windows Contrast Themes). Note that this can + be tested via the ``"high_contrast"`` mode in the :ref:`screenshot tests + `. Common issues include: + + * Over-reliance on color for meaning, which is lost in forced-colors mode. + * Use of ``!important`` or inline styles may break forced-colors mode. + +.. _assistive-technologies: + +Recommended assistive technologies +---------------------------------- + +Where the UI changes could affect assistive technologies, here are popular free +options we recommend testing with. + +For Windows: + +* `NVDA`_ - recommended with Firefox ESR +* `Narrator`_ - recommended with Microsoft Edge +* Windows Magnifier +* Windows Speech Recognition +* `Contrast themes`_ + +For macOS: + +* `VoiceOver`_ - recommended with Safari +* macOS Zoom +* macOS Voice Control + +For Linux: + +* `Orca`_ - recommended with Firefox ESR + +For mobile or tablet: + +* VoiceOver on iOS, or TalkBack on Android + +The following are popular licensed options. If you are a user of these, or can +work with a user holding a license, also test against: + +* `JAWS`_ on Windows +* `Dragon`_ on Windows + +.. _Accessibility Insights: https://accessibilityinsights.io/ +.. _Axe: https://github.com/dequelabs/axe-core +.. _NVDA: https://www.nvaccess.org/ +.. _Narrator: https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1 +.. _VoiceOver: https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web +.. _TalBack: https://support.google.com/accessibility/android/answer/6283677 +.. _Contrast themes: https://support.microsoft.com/en-us/windows/change-color-contrast-in-windows-fedc744c-90ac-69df-aed5-c8a90125e696 +.. _JAWS: https://www.freedomscientific.com/products/software/jaws/ +.. _Dragon: https://www.nuance.com/en-gb/dragon.html +.. _Orca: https://help.gnome.org/users/orca/stable/ + +.. _accessibility-known-issues-how-to-help: + +Known issues and how to help +============================ + +There are parts of Django that do not meet our accessibility targets. We +actively work on fixing issues, both as part of ongoing maintenance and bigger +overhauls. To learn about known issues, and get involved, see: + +* ``#accessibility`` on the `Django Discord server`_. +* The `Accessibility Django forum topic`_. +* `Accessibility issues on the ticket tracker`_. +* Our `django accessibility improvements`_ project board. +* The `Accessibility team`_. + +.. _Django Discord server: https://chat.djangoproject.com +.. _Accessibility Django forum topic: https://forum.djangoproject.com/c/internals/accessibility/26 +.. _Accessibility issues on the ticket tracker: https://code.djangoproject.com/query?status=!closed&keywords=~accessibility +.. _django accessibility improvements: https://github.com/orgs/django/projects/7 +.. _Accessibility team: https://www.djangoproject.com/foundation/teams/#accessibility-team diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 53ff3596cc..0a80ea5f28 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -82,6 +82,9 @@ guidelines to follow: * Make sure to set the UI/UX flag on the ticket so interested parties can find your ticket. +* If the issue relates to accessibility, please link to the relevant + :ref:`accessibility standard ` if applicable. + .. _requesting-features: Requesting features diff --git a/docs/internals/contributing/writing-code/index.txt b/docs/internals/contributing/writing-code/index.txt index 72cc264524..a72b6c8b41 100644 --- a/docs/internals/contributing/writing-code/index.txt +++ b/docs/internals/contributing/writing-code/index.txt @@ -40,6 +40,7 @@ It's important to understand how we work and the conventions we adopt. coding-style javascript + ../accessibility ../committing-code We maintain a curated list of small issues suited to first-time or less diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index b8ead27ded..9844d5e2c7 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -413,6 +413,8 @@ All code changes * If the change is backwards incompatible in any way, is there a note in the release notes (``docs/releases/A.B.txt``)? * Is Django's test suite passing? +* If the change affects the Django admin or rendered HTML output, has + :ref:`accessibility testing ` been done? All tickets ----------- diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index f7651f1d4f..1c993f5fc6 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -271,6 +271,11 @@ faster and more stable. Add the ``--headless`` option to enable this mode. .. _selenium.webdriver: https://github.com/SeleniumHQ/selenium/tree/trunk/py/selenium/webdriver +.. _screenshot-tests: + +Screenshot tests +~~~~~~~~~~~~~~~~ + For testing changes to the admin UI, the selenium tests can be run with the ``--screenshots`` option enabled. Screenshots will be saved to the ``tests/screenshots/`` directory. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 37205dcdea..0923fae08e 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -509,6 +509,7 @@ titlecase tokenized toolkits toolset +tooltip trac tracebacks Transifex