[5.2.x] Added accessibility guidelines for contributors.

Backport of 5527df91921b54b9fd1eb9aca3aabe91ec58a9c7 from main.

6 files changed, 183 insertions, 0 deletions

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
+  <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 <accessibility-standards>` 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 fe354a0ba1..5fe3a151de 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/docs/internals/contributing/writing-code/submitting-patches.txt
@@ -408,6 +408,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 <accessibility-testing-baseline>` 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 71aaa6dccb..03218e26cc 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 e9441c62d9..61b3b65a98 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -507,6 +507,7 @@ titlecase
 tokenized
 toolkits
 toolset
+tooltip
 trac
 tracebacks
 Transifex