Fix nbsphinx color outputs, suppress other notebook output Axe errors #1905

gabalafou · 2024-06-27T16:32:33Z

Once this PR is merged, running the accessibility checks should execute successfully, with all known failures marked as expected. This should allow us to close #1428 and add the accessibility checks to CI.

gabalafou · 2024-06-27T16:37:49Z

Submitting this as a draft until I can hunt down what seems to be some kind of race condition (I'm guessing race condition because sometimes the tests pass locally, sometimes not). Sometimes when running the tests locally, the "scollable-region-focusable" Axe check fails, which shouldn't happen because I am asking Playwright to wait for a sign from the script that adds tabindex=0.

gabalafou · 2024-06-28T08:08:13Z

Getting same confusing Axe failure in CI

gabalafou · 2024-06-28T12:24:44Z

I think I found the cause of the race condition:

page loads
addTabStopsToScrollableElements() function runs
ipywidgets load, triggering a debounced rerun of the addTabStopsToScrollableElements() function.

Note: at this point, the element containing the wide Pandas table in the ipywidget does NOT have tabindex="0"

Playwright runs Axe
The debounced call to addTabStopsToScrollableElements() finally runs and applies tabindex="0" after Axe has already run

With that order of operations, we get a failure for the scrollable-region-focusable Axe check. But if step 5 comes after 6, the check passes.

I rewrote the Playwright script to wait both for the ipywidget table's container to load and for tabindex="0" to be applied.

github-actions · 2024-06-28T12:27:46Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
src/pydata_sphinx_theme
__init__.py
logo.py
short_link.py
toctree.py
translator.py
Project Total

_{This report was generated by python-coverage-comment-action}

gabalafou

self review

gabalafou · 2024-06-28T12:27:51Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

@@ -52,6 +52,28 @@ div.nblast.container {
  margin-bottom: 1rem;
 }

+// Notebook cell input line number


Suggested change

// Notebook cell input line number

// Notebook cell input prompt (execution count)

// Ref: https://nbformat.readthedocs.io/en/latest/format_description.html#code-cells

gabalafou · 2024-06-28T12:29:07Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

+  }
+}
+
+// Notebook cell output line number


Suggested change

// Notebook cell output line number

// Notebook cell output prompt (execution count)

// Ref: https://nbformat.readthedocs.io/en/latest/format_description.html#code-cells

gabalafou · 2024-06-28T12:30:10Z

tests/test_a11y.py

+        # TODO: for color contrast issues with common notebook outputs
+        # (ipywidget tabbed panels, Xarray, etc.), should we override
+        # third-party CSS with our own CSS or/and work with NbSphinx, MyST-NB,
+        # ipywidgets, and other third parties to use higher contrast colors in
+        # their CSS?


cc @trallard

Larger conversation but longer term it would be best to have these fixed upstream vs in here.
Not sure how much of an effort this would be so will have to pin this for now.

gabalafou · 2024-06-28T12:30:50Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

+  html[data-theme="dark"] & {
+    color: #ffa07a;
+  }
+}


TODO: check MyST-NB notebook prompts for color contrast

Actually MyST-NB does not render notebook cell prompts:

gabalafou · 2024-06-28T12:31:43Z

tests/test_a11y.py

@@ -38,8 +38,9 @@ def filter_ignored_violations(violations, url_pathname):
    ]:
        filtered = []
        for violation in violations:
-            # TODO: eventually fix this rule violation. See
-            # https://github.com/pydata/pydata-sphinx-theme/issues/1479.
+            # TODO: remove this exclusion once the following update to Axe is


This change is unrelated to the rest of the PR, but I thought I would go ahead make this comment more up to date

gabalafou · 2024-06-28T12:32:54Z

src/pydata_sphinx_theme/assets/styles/extensions/_notebooks.scss

The CSS additions to this file override nbsphinx styles for the notebook cell prompts, which don't have sufficient color contrast against our light and dark backgrounds.

Nbsphinx uses a shade of blue for the input cell prompt and a shade of red for the output cell prompt. So I chose blueish and reddish colors from the following two accessible-pygments themes:

a11y-high-contrast-light

a11y-high-contrast-dark

TODO: add this as a code comment

Done, added comments to the code

trallard

Thanks @gabalafou this looks good, I checked through the axe/playwright tests and they look good so I will go ahead and merge

trallard · 2024-07-01T17:41:59Z

tests/test_a11y.py

@@ -167,6 +168,13 @@ def test_axe_core(
    # Wait for CSS transitions (Bootstrap's transitions are 300 ms)
    page.wait_for_timeout(301)

+    # On the PyData Library Styles page, wait for ipywidget to load and for our
+    # JavaScript to apply tabindex="0" before running Axe checker (to avoid
+    # false positives for scrollable-region-focusable).


Interesting, I did not notice before that this was the case, i.e. the tabindex being applied later. I suppose it make sense since we are delegating this to JS.

Yeah, you might have seen my first tab stop implementation, which adds tabindex="0" at build time (via HTML created by Python), and might not have noticed my second tab stop implementation, which adds a zero tab index at run time (via DOM manipulation by JavaScript).

Fun fact. This change was driven by an article you shared (or maybe it was Smera) 🌻 Inclusive Components - Data Tables - Only Focusable Where Scrollable

trallard · 2024-07-01T17:43:58Z

tests/test_a11y.py

+        # TODO: for color contrast issues with common notebook outputs
+        # (ipywidget tabbed panels, Xarray, etc.), should we override
+        # third-party CSS with our own CSS or/and work with NbSphinx, MyST-NB,
+        # ipywidgets, and other third parties to use higher contrast colors in
+        # their CSS?


Larger conversation but longer term it would be best to have these fixed upstream vs in here.
Not sure how much of an effort this would be so will have to pin this for now.

gabalafou mentioned this pull request Jun 27, 2024

Team sync - June 27, 2024 Quansight-Labs/czi-scientific-python-mgmt#104

Open

Fix nbsphinx color outputs, suppress other notebook output Axe errors

7354230

gabalafou force-pushed the deal-with-notebook-outputs-axe branch from a66f1e3 to 7354230 Compare June 28, 2024 12:19

gabalafou marked this pull request as ready for review June 28, 2024 12:24

gabalafou commented Jun 28, 2024

View reviewed changes

gabalafou requested a review from trallard June 28, 2024 12:37

comment nbsphinx notebook cell prompt color overrides

3eda814

trallard added the tag: accessibility Issues related to accessibility issues or efforts label Jul 1, 2024

trallard approved these changes Jul 1, 2024

View reviewed changes

trallard merged commit 0acb754 into pydata:main Jul 1, 2024
29 checks passed

gabalafou deleted the deal-with-notebook-outputs-axe branch July 3, 2024 13:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix nbsphinx color outputs, suppress other notebook output Axe errors #1905

Fix nbsphinx color outputs, suppress other notebook output Axe errors #1905

gabalafou commented Jun 27, 2024 •

edited

Loading

gabalafou commented Jun 27, 2024 •

edited

Loading

gabalafou commented Jun 28, 2024

gabalafou commented Jun 28, 2024

github-actions bot commented Jun 28, 2024

gabalafou left a comment

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

trallard Jul 1, 2024

gabalafou Jul 3, 2024

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

gabalafou Jun 28, 2024

trallard left a comment

trallard Jul 1, 2024

gabalafou Jul 3, 2024

trallard Jul 1, 2024

	// Notebook cell input line number
	// Notebook cell input prompt (execution count)
	// Ref: https://nbformat.readthedocs.io/en/latest/format_description.html#code-cells

	// Notebook cell output line number
	// Notebook cell output prompt (execution count)
	// Ref: https://nbformat.readthedocs.io/en/latest/format_description.html#code-cells

Fix nbsphinx color outputs, suppress other notebook output Axe errors #1905

Fix nbsphinx color outputs, suppress other notebook output Axe errors #1905

Conversation

gabalafou commented Jun 27, 2024 • edited Loading

gabalafou commented Jun 27, 2024 • edited Loading

gabalafou commented Jun 28, 2024

gabalafou commented Jun 28, 2024

github-actions bot commented Jun 28, 2024

Coverage report

gabalafou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trallard left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gabalafou commented Jun 27, 2024 •

edited

Loading

gabalafou commented Jun 27, 2024 •

edited

Loading