Accessibility guidelines for all contributors #17338
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,124 @@ | ||||||
| ============= | ||||||
| Accessibility | ||||||
| ============= | ||||||
|
|
||||||
| The Django project is committed to being accessible to everyone in all | ||||||
| possible ways. We work to conform to established accessibility standards, an | ||||||
| also to 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 attempt to follow other best practices, such as: | ||||||
|
|
||||||
| * WCAG 2.2 AAA-level guidelines. | ||||||
| * The upcoming `WCAG 3.0`_ guidelines. | ||||||
|
There was a problem hiding this comment. They’re very far from being broadly applicable but I thought we might as well future-proof. Personally I would recommend following the drafts for contrast in particular, as WCAG 2.x contrast is notoriously poor. |
||||||
| * `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/ | ||||||
| .. _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: | ||||||
|
|
||||||
| Accessibility support targets | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Could you explain your suggestion? I have spent a lot of time on wording choices here, and based this on other existing guidelines that use this wording. There was a problem hiding this comment. Sure, my point was to reduce the repetition of the "Accessibility" prefix in every section title. And to me, "targets" was confusing, after reading the associated paragraph I felt I would like though that we don't prefix every section title with "Accessibility " and just use "". What do you think? |
||||||
| ============================= | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| .. _for everyone: https://en.wikipedia.org/wiki/Curb_cut_effect | ||||||
|
|
||||||
| .. _accessibility-testing-baseline: | ||||||
|
|
||||||
| Accessibility testing baseline | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Can you explain why you’re suggesting this? If I link someone directly to this section, I’d much rather they land on the more descriptive heading which I wrote. There was a problem hiding this comment. Even if someone lands in a heading, the topic of the document is "Accessibility". Having this prefixed on every section title feels redundant and I think it's fair to expect people to be able to scroll up and down for context if they need it. |
||||||
| ------------------------------ | ||||||
|
|
||||||
| 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 | ||||||
|
There was a problem hiding this comment. Is there some resource that we could link to that gives a checklist for what to cover here? I can tab about, etc., but likely there’s lots that I wouldn’t think or know consider. There was a problem hiding this comment. Good point, yes definitely! The TL;DR; is you should be able to do everything with just tab, arrow keys, space and enter. There are some more nuances which a resource will be helpful for. There was a problem hiding this comment. I think this should link to a provided-by-us How-To. There was a problem hiding this comment. Circling back to this, and after having read the linked resources/references on the topic, I think that:
|
||||||
| * The `Accessibility Insights`_ browser extension's automated checks feature, | ||||||
| or an equivalent tool with the `Axe`_ checker. | ||||||
|
There was a problem hiding this comment. Recommending Accessibility Insights from Microsoft specifically because:
There was a problem hiding this comment. In previous PRs, I tried to use this extension. My first frustration is that is not available in Firefox, and I couldn't find any alternative for Firefox. "Forcing" Chrome to contributors feels... a bit too much. Are there options for other browsers that I missed? There was a problem hiding this comment. @nessita the wording as-is says "Accessibility Insights or equivalent tool with the Axe checker", so I don’t understand how you equate this to forcing Chrome on contributors? There are a lot of tools available with this checker (a browser extension for Firefox, lots of command line tools, etc). Do you think we should link to specific options here then? Perhaps link to a list of products / integrations of Axe? There was a problem hiding this comment. I guess my point is that, upon reading this sentence, I'm concerned that this approach might be intimidating for new contributors, as it places the burden of finding an "equivalent tool with the Axe checker" squarely on their shoulders. Does this make sense? |
||||||
|
|
||||||
| Where the UI changes could affect those modalities, also test with: | ||||||
|
|
||||||
| * Touch-only navigation | ||||||
| * 400% browser zoom | ||||||
| * Forced-colors mode (for example Windows Contrast Themes) | ||||||
|
There was a problem hiding this comment. I would love to see each one of these be a link to a How-To provided by us. There was a problem hiding this comment. Just to clarify my point here, I think we need to describe somewhere how to achieve forced-colors mode (I'm honestly asking out of ignorance). Is it a browser setting? Is it browser specific? Is it an operating system setting? |
||||||
|
|
||||||
| .. _assistive-technologies: | ||||||
|
|
||||||
| Assistive technologies | ||||||
| ---------------------- | ||||||
|
|
||||||
| Where the UI changes could affect assistive technologies, here are popular | ||||||
| free options we recommend testing with: | ||||||
|
|
||||||
| * `NVDA`_ on Windows with Firefox ESR | ||||||
|
There was a problem hiding this comment. Does this mean that these tools are not available for non-ESR Firefox? There was a problem hiding this comment. No, it just means we recommend testing with Firefox ESR. There was a problem hiding this comment. Great, perhaps we could rephrase and simplify the language a bit, so it's more accessible for beginners in the topic? (like myself) |
||||||
| * `VoiceOver`_ on macOS with Safari | ||||||
| * `Orca`_ on Linux with Firefox ESR | ||||||
| * `Narrator`_ on Windows with Microsoft Edge | ||||||
| * Windows Magnifier and macOS Zoom | ||||||
| * Windows Speech Recognition and macOS Voice Control | ||||||
| * VoiceOver on iOS, or TalkBack on Android | ||||||
| * `Contrast themes`_ on Windows | ||||||
thibaudcolas marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| If you have the expertise or you can work with someone who does, also test | ||||||
| with: | ||||||
|
|
||||||
| * `JAWS`_ on Windows | ||||||
| * `Dragon`_ on Windows | ||||||
|
There was a problem hiding this comment. These feel essential to me because they are very popular, but I chose to keep them separate because:
|
||||||
|
|
||||||
| .. _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 some parts of Django that do not meet our accessibility targets at | ||||||
| the moment. 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`_. | ||||||
|
|
||||||
| * `Accessibility issues on the ticket tracker`_. | ||||||
| * Our `django accessibility improvements`_ project board. | ||||||
| * The `Accessibility team`_. | ||||||
|
|
||||||
| .. _Django Discord server: https://discord.gg/xcRH6mN4fa | ||||||
| .. _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 | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Including WCAG 2.0 and 2.1 AAA if this isn’t clear. All WCAG 2.0 / 2.1 guidelines are included in 2.2.