Skip to content

Commit

Permalink
Update accessibility docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@gabalafou
gabalafou committed Nov 14, 2024
1 parent 1b3e65e commit 7faf842
Show file tree
Hide file tree
Showing 4 changed files with 131 additions and 76 deletions.
64 changes: 51 additions & 13 deletions docs/community/topics/accessibility.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,58 @@
# 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).
We would love contributions that add more accessibility checks to our test
suite.

## Accessibility checks as part of our development process
We have also made these tests part of our continuous integration process, so
that they are run in the cloud before we merge in new changes to the theme. We
use GitHub Actions to provision machines in the cloud. We use Tox to install the
needed dependencies on those machines. We use Pytest with the plug-in for
Playwright to run the tests. 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
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 an issue](https://github.com/pydata/pydata-sphinx-theme/issues/new) on
GitHub if you find something broken.
122 changes: 68 additions & 54 deletions docs/user_guide/accessibility.md
View file
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,72 @@ 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`:
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`:

```python
"logo": {
"text": "PyData Theme",
"image_dark": "_static/logo-dark.svg",
"alt_text": "PyData Theme home",
},
"logo": {
"image_dark": "_static/logo-dark.svg",
"alt_text": "<Your Project> home",
},
```

Note the use of "home" in the alt text to indicate that the logo is also a link to the home page.
Note the use of "home" in the alt text to indicate that the logo is also a link
to the home page.

### In the Browser
### Test and inspect your site

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

### Built-in tools
Non-interactive tools also exist for integration with continuous integration
(CI).

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.
#### Browser tools

#### tota11y
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](https://khan.github.io/tota11y/#Installation) is an open source
"bookmarklet" which modifies the currently-loaded page in place and highlights
several accessibility issues.
- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
- [Chrome DevTools Accessibility](https://developer.chrome.com/docs/devtools/accessibility/reference)

#### WAVE
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](https://wave.webaim.org/extension/) is a proprietary (but _gratis_)
browser extension which can highlight multiple issues.
- [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/)

:::{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.
:::
#### Continuous Integration tools

### In Continuous Integration
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).

Several automated tools are available for assessing _glaring_ accessibility
issues across some pages at once, usually with many configurable options.
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
If you are curious about how we do accessibility CI for this theme, refer to the
page [](../community/topics/accessibility.md).

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

:::{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.
:::
19 changes: 11 additions & 8 deletions docs/user_guide/web-components.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,17 @@ 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>`__.

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, the space bar can be used on a ``<button>``s but
not on ``<a>``-tag links.)

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

0 comments on commit 7faf842

Please sign in to comment.