Update accessibility docs #2039
Conversation
Coverage report
This PR does not seem to contain any modification to coverable code. |
gabalafou
force-pushed
the
update-accessibility-docs
branch
from
7faf842
to
04d26d2
Compare
| - We also re-defined our `primary` and `secondary` colors to be more accessible | ||
| and distinct from semantic colors used to denote success, warning, info, and | ||
| danger contexts or information. | ||
| - We simplified the color palette and removed some colors that were problematic | ||
| in meeting WCAG 2 AA or AAA contrast requirements and for certain types of | ||
| colorblindness. | ||
| - We have improved how we assign text colors to interactive elements such as | ||
| buttons and dropdowns to ensure that they meet WCAG 2 AA or AAA contrast | ||
| requirements. |
There was a problem hiding this comment.
just text wrapping
| Creating and publishing content that does not exclude disabled users is a | ||
| complex and iterative task. | ||
|
|
||
| While there is no one-size-fits-all solution to maintaining accessible content, | ||
| the PyData Sphinx Theme and this documentation site use some techniques to avoid common content shortcomings. | ||
| the PyData Sphinx Theme and this documentation site use some techniques to avoid | ||
| common content shortcomings. | ||
|
|
||
| :::{note} | ||
| Issues and pull requests to identify or fix accessibility issues on this theme or site are heartily welcomed! | ||
| Issues and pull requests to identify or fix accessibility issues on this theme | ||
| or site are heartily welcomed! |
There was a problem hiding this comment.
just text wrapping
| We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation. | ||
| The configuration for Lighthouse can be found in the `.github/workflows/lighthouserc.json` file. | ||
| ## Known limitations and manual auditing | ||
|
|
||
| For more information about configuring Lighthouse, see [the Lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md). | ||
| For more information about Accessibility in general, see [](../../user_guide/accessibility.md). |
There was a problem hiding this comment.
Unless somebody says not to, I am going to create a follow-up PR to remove the Lighthouse checks and configuration.
| In your `conf.py` file, | ||
| [specifying the language your docs are written in](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language) | ||
| will propagate to the top-level `HTML` tag. |
There was a problem hiding this comment.
just text wrapping
| sitemap_url_scheme = "{link}" | ||
| html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/") | ||
| sitemap_locales = [None] | ||
| sitemap_url_scheme = "{link}" |
There was a problem hiding this comment.
removed indentation, any reason not to?
There was a problem hiding this comment.
looks fine on the rendered page: https://pydata-sphinx-theme--2039.org.readthedocs.build/en/2039/user_guide/accessibility.html#add-a-site-map
| "text": "PyData Theme", | ||
| "image_dark": "_static/logo-dark.svg", | ||
| "alt_text": "PyData Theme home", |
There was a problem hiding this comment.
This example is misleading because our code now sets alt="" if a theme adopter sets the logo["text"] field. This is to avoid hearing the same text repeated twice by the screen reader, for example: "PyData Theme home PyData Theme".
I created what I think is a more realistic example based on the assumption that most sites will only put their logo in the top left and not the project text.
I guess I should add a note explaining that only one of text or alt_text should be specified; only rarely should both be specified together.
I'm thinking the need for this much nuance also suggests that we should simplify the config somehow.
|
|
||
| [tota11y](https://khan.github.io/tota11y/#Installation) is an open source |
There was a problem hiding this comment.
Tota11y is no longer maintained. A note I found somewhere explains that the maintainers no longer saw the point, given how the improvement in the ecosystem of browser dev tools and other accessibility extensions.
| If in your site's :ref:`custom CSS file <custom-css>` you override the :ref:`CSS | ||
| custom properties <css-variables>` ``--pst-color-*`` (where ``*`` is one of the | ||
| semantic color names, such as ``primary``, ``danger``), badges and buttons will | ||
| automatically use the custom color. |
There was a problem hiding this comment.
Here is just text wrapping
| however, be aware that they do not follow accessibility best practices for | ||
| native button components such as using the correct `ARIA attributes | ||
| <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role>`__. |
There was a problem hiding this comment.
I felt that this did not help the theme adopter because it did not make a recommendation nor was the info helpful enough for a non-accessibility expert to make a judgment call, so I updated it with a specific recommendation (to use sparingly) and a specific example (about how the space bar doesn't work on links that look like buttons).
| sitemap_url_scheme = "{link}" | ||
| html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/") | ||
| sitemap_locales = [None] | ||
| sitemap_url_scheme = "{link}" |
There was a problem hiding this comment.
looks fine on the rendered page: https://pydata-sphinx-theme--2039.org.readthedocs.build/en/2039/user_guide/accessibility.html#add-a-site-map
Co-authored-by: Daniel McCloy <[email protected]>
|
Thanks for reviewing @drammock |
This pull request brings the accessibility docs up to date.
Some of the changes in this pull request involve hard-wrapping the text in the docs files. I feel like this itself is an accessibility improvement as long lines are harder to read. It's also makes text diffing in git better.