Skip to content

Update accessibility docs #2039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Nov 19, 2024
Merged

Update accessibility docs #2039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
04d26d2
Update accessibility docs
gabalafou Nov 14, 2024
009404d
Update docs/community/topics/accessibility.md
gabalafou Nov 14, 2024
e972f97
Apply suggestions from code review
gabalafou Nov 18, 2024
0596d92
[pre-commit.ci] Automatic linting and formatting fixes
pre-commit-ci[bot] Nov 18, 2024
d838c69
update wording
gabalafou Nov 14, 2024
b1ff8f0
add note about Polypane
gabalafou Nov 18, 2024
1f60768
update logo recommendations
gabalafou Nov 18, 2024
4a40120
don't repeat yourself
gabalafou Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 56 additions & 13 deletions docs/community/topics/accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,63 @@
# Accessibility checks
# Accessibility checks and manual auditing

```{note}
April-2023: we are currently
[re-evaluating how we do accessibility checks](https://github.com/pydata/pydata-sphinx-theme/issues/1168)
and reporting, so this may change soon.
As part of our commitment to making this theme accessible, we run automated
checks against all of the pages under [](../../examples/kitchen-sink/index.rst).

The accessibility check is run every time that a pull request is created on
GitHub. We forbid merging a pull request into the codebase if it breaks this
check.

## Running the checks locally

If you are [developing the theme locally](../setup.md), the simplest way to run
the accessibility checks on your computer is:

```sh
tox run -m a11y
```

In general, accessibility-checking tools can find a limited number of common HTML patterns that assistive technology
can't help users understand.
## Technical details

The main two technologies we use to write and run accessibility checks are
[Playwright for Python](https://playwright.dev/python/) and
[axe-core](https://github.com/dequelabs/axe-core).

Playwright is the successor to a similar library called Puppeteer. It provides a
way to programmatically script a web browser to open, operate, inspect, and test
web pages. Axe-core is a suite of accessibility checks written as a JavaScript
program. The program is meant to be injected into a web page. Once injected, it
examines the page for common accessibility failures, such as low contrast text.
Our accessibility test suite uses Playwright to inject Axe-core into each of the
Kitchen Sink pages plus a few other key pages in this documentation. We also
wrote a few other Playwright scripts to ensure that certain theme components can
be accessed using only the keyboard. All of our tests currently live in a file
called
[test_a11y.py](https://github.com/pydata/pydata-sphinx-theme/blob/main/tests/test_a11y.py).
:::{note}
We would love contributions that add more accessibility checks to our test
suite.
:::

We have also made these tests part of our continuous integration process, so
they are run in the cloud before we merge in new changes to the theme. We
use the following tools:

- GitHub Actions to provision machines in the cloud
- `tox` to install the needed dependencies on those machines
- `Pytest` with the Playwright plug-in to run the tests.

## Accessibility checks as part of our development process
Look for the string "accessibility" in the file
[CI.yml](https://github.com/pydata/pydata-sphinx-theme/blob/main/.github/workflows/CI.yml)
to find how we have configured GitHub Actions.

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).
We are well aware that automated checks fall far short of comprehensive
Comment on lines -14 to -18
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless somebody says not to, I am going to create a follow-up PR to remove the Lighthouse checks and configuration.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine by me

accessibility auditing and testing, so we also conducted an accessibility audit
of three pages from the theme docs. We collected those findings in an issue on
GitHub, [May 2024 PyData Theme audit
findings](https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/72)

We have also recently added automated tests using [Playwright](https://playwright.dev/python/) and [axe-core](https://github.com/dequelabs/axe-core) to improve our accessibility testing and reporting.
Nearly all of the issues have been fixed, but of course things do break / have
already broken, and some things may have never been discovered, so please
[create a GitHub issue](https://github.com/pydata/pydata-sphinx-theme/issues/new) if you find something inaccessible.
121 changes: 65 additions & 56 deletions docs/user_guide/accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
# Accessibility

Creating and publishing content that does not exclude disabled users is a complex and iterative task.
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!
:::

## What We've Done
Expand All @@ -26,12 +29,15 @@ page that lacks metadata, please open a pull request to add it!
to choose from at https://github.com/Quansight-Labs/accessible-pygments.
- We recently revisited the PyData Sphinx theme color palette to ensure that
the colors we use meet WCAG 2 AA or AAA contrast requirements.
- 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.
- 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.

### Keyboard Navigation Support

Expand All @@ -41,6 +47,11 @@ links and other interactive elements, we have worked to ensure they:
- Have a visible focus indicator (WCAG 2.4.7)
- Can be accessed via keyboard navigation (WCAG 2.1.1)

### Testing and auditing

We have also added automated tests and conducted manual audits. See
[](../community/topics/accessibility.md).

## What You Can Do

### Site configuration
Expand All @@ -55,10 +66,12 @@ specifying at least the baseline natural language will help assistive technology
identify if the content is in a language the reader understands.

:::{hint}
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.
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.

```python
language = "en"
language = "en"
```

:::
Expand All @@ -80,71 +93,67 @@ For a simple site (no extra languages or versions), ensure `sphinx-sitemap`
is installed in your documentation environment, and modify your `conf.py`:

```python
extensions += ["sphinx_sitemap"]
extensions += ["sphinx_sitemap"]

html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/")
sitemap_locales = [None]
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}"
```

:::

### Logo best practices

If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme.
If you have a logo, you can add alt-text to it by adding the following to your
`conf.py`:
We recommend that you support dark mode by providing either a single version of
your logo that works well in both light and dark modes, or two separate
versions. We also recommend that you provide alt text for your logo if you do
not provide visible text.

```python
"logo": {
"text": "PyData Theme",
"image_dark": "_static/logo-dark.svg",
"alt_text": "PyData Theme home",
Comment on lines -100 to -102
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Agree, let's add a note about this.

I'm thinking the need for this much nuance also suggests that we should simplify the config somehow.

+1, do you have any ideas?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if there really is a way to simplify it because users would encounter the same issue if they were writing HTML. But I guess this is a good example of why I personally dislike config files, because it's a bit hard to convey through the config object itself how its state will affect the state of the end application.

Anyway, I realized that all of this is covered in much greater detail in a separate page, Branding and logo. So in my last commit I slimmed down this section and linked to that page.

},
```
These recommendations are covered in detail at the page [](./branding.rst)

Note the use of "home" in the alt text to indicate that the logo is also a link to the home page.
### Test and inspect your site

### In the Browser
Several browser tools exist for interactively debugging the accessibility
of a single page at a time and can be useful during the content development
cycle.

Several in-browser tools exist for interactively debugging the accessibility
of a single page at a time and can be useful during the content development cycle.
Non-interactive tools also exist for use with CI (continuous integration).

### Built-in tools
#### Browser tools
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to include polypane? IMO is a great tool, the downside is one needs a license.

Copy link
Collaborator Author

@gabalafou gabalafou Nov 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I had the same thought on my first pass but didn't add it because the document was structured a bit differently and I wasn't sure if we should promote a paid product.

But given that we both find it useful, I agree with you that it could help some people to know about it, so I added a sentence about it.


Most major browsers, including [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
and [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference),
have accessibility tools built-in as part of their web developer tools.
These tools can help to quickly identify accessibility issues and often include links to standards.
Most major browsers, including Firefox and Chrome, have built-in accessibility
tools as part of their web developer tools. These tools can help to quickly
identify accessibility issues and often include links to standards:

#### tota11y
- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
- [Chrome DevTools Accessibility](https://developer.chrome.com/docs/devtools/accessibility/reference)

[tota11y](https://khan.github.io/tota11y/#Installation) is an open source
"bookmarklet" which modifies the currently-loaded page in place and highlights
several accessibility issues.
There are also a few browser extensions that some of the maintainers of this
theme use when working to make websites more accessible. Some of these include:

#### WAVE
- [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/)
- [Axe DevTools](https://www.deque.com/axe/browser-extensions/)
- [WAVE](https://wave.webaim.org/extension/)

[WAVE](https://wave.webaim.org/extension/) is a proprietary (but _gratis_)
browser extension which can highlight multiple issues.
We have also found [Polypane](https://polypane.app/) to be a great tool (but it
is not free and requires a license).

:::{warning}
Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues.
They are not a replacement for manual testing and having a perfect score on any of these tools does not mean that
the site can be used by disabled users but instead signals that it follows some accessibility best practices.
:::

### In Continuous Integration
#### Continuous Integration tools

Several automated tools are available for assessing _glaring_ accessibility
issues across some pages at once, usually with many configurable options.
Two accessibility testing tools designed for continuous integration are
[Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/getting-started.md)
and [Pa11y CI](https://github.com/pa11y/pa11y-ci).

#### Lighthouse
The [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action)
may be helpful if the code for your site is hosted on GitHub.

[Lighthouse](https://developers.google.com/web/tools/lighthouse) provides an automated assessment of basic accessibility issues in addition to search engine
automation, page performance, and other best practices.
If you are curious about how we do accessibility CI for this theme, refer to the
page [](../community/topics/accessibility.md).

:::{hint}
Specifically, [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action)
is run on selected pages from the generated documentation site.
:::{warning}
Note that automated testing and extensions such as the ones mentioned above will
at best catch 30-40% of accessibility issues. They are not a replacement for
manual testing. Having a perfect score on any of these tools does not mean that
your site can be used by disabled users. Instead, a good score signals that your
site follows some best accessibility practices.
:::
20 changes: 12 additions & 8 deletions docs/user_guide/web-components.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,18 @@ Here are some of the available button-style links, also using semantic colors:
.. note::

`Sphinx Design buttons
<https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html>`__
are actually links, meaning they are rendered in HTML with ``<a>`` tags
instead of ``<button>``. Use them if you need a link to look like a button,
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>`__.
Comment on lines -138 to -140
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.
<https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html>`__ are
actually links, meaning they are rendered in HTML with ``<a>`` tags instead
of ``<button>``. Use them if you need a link to look like a button, but try
not to overuse them as they are not considered best practice for
accessibility. (For example, it upsets user interface expectations because
the space bar can be used on ``<button>``-tag buttons but not on ``<a>``-tag
links that look like buttons.)

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.

Cards
=====
Expand Down
2 changes: 1 addition & 1 deletion src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
{% if is_logo %}
{#
Theme switching is only available when JavaScript is enabled.
We thus adds elements that should be present only when javscipt is
We thus adds elements that should be present only when JavaScript is
enabled with a pst-js-only class
#}
{% if default_mode is undefined or default_mode == "auto" %}
Expand Down
Loading