[BLOG] PyData Sphinx Theme Accessibility Fixes #867
Conversation
gabalafou
requested review from
pavithraes,
trallard and
rgommers
as code owners
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| @@ -90,7 +90,6 @@ | |||
| "postcss": "^8.4.31", | |||
| "prettier": "^2.5.1", | |||
| "react-test-renderer": "17.0.2", | |||
| "sass": "1.49.9", | |||
There was a problem hiding this comment.
When I ran npm install it removed this.
| @@ -48,7 +48,7 @@ export const PostListItem: FC<TPostListItem> = ({ post, variant }) => ( | |||
| )} | |||
| > | |||
| <Link href={`/blog/${post.slug}`}> | |||
| <a>{post.meta.title}</a> | |||
| {post.meta.title} | |||
There was a problem hiding this comment.
I made these changes to make local dev work. Next.js deprecated the style on the left.
| authors: [gabriel-fouasnon] | ||
| published: June 26, 2024 | ||
| description: 'A small showcase of accessibility improvements made to the PyData Sphinx Theme, Fall 2023-Spring 2024' | ||
| category: [Access-centered] |
There was a problem hiding this comment.
Any other categories I should use?
There was a problem hiding this comment.
Think we have a documentation category no?
There was a problem hiding this comment.
No, I think these are the categories:
- "Access-centered",
- "Array API",
- "Beyond PyData",
- "Community",
- "Developer workflows",
- "Funding",
- "GPU",
- "IDEs",
- "Machine Learning",
- "OSS Experience",
- "Packaging",
- "PyData ecosystem"
There was a problem hiding this comment.
PyData ecosystem for sure, maybe OSS experience
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
What do we think? Should I add a Codepen?
There was a problem hiding this comment.
I think the one that is there works for my understanding.
There was a problem hiding this comment.
I generally like having small iterative or illustrative CodePen especially when following changes to interactive or nuanced states.
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
Codepen or no Codepen?
There was a problem hiding this comment.
Other than the existing one? Or are you asking if the existing one makes sense?
While I can't speak from a regular code-writer's perspective, I think having the information represented as code and rendered supports understanding the how behind the before and afters you are showing. This Codepen is also not very long so I don't think it becomes a big obstacle by accident.
There was a problem hiding this comment.
My same comment from above applies here, experiencing the interaction change as well as seeing the code changes is useful.
| look at all of the [PST issues and PRs tagged with | ||
| accessibility](https://github.com/pydata/pydata-sphinx-theme/issues?q=label%3A%22tag%3A+accessibility%22). | ||
| If you find anything you would like to see written about in a blog post like | ||
| this one, please let us know! |
There was a problem hiding this comment.
Should I be more specific about how the reader can get in touch?
There was a problem hiding this comment.
I would hesitate to simply because I don't know what channels of communication we'll maintain. For example, we don't have an email I'm aware of that we are always watching, and I don't know if authors get notified of blog post comments.
There was a problem hiding this comment.
For PST feedback, this should be the PST repo and issues.
We do not have comments in our blog but there is a [email protected]
email that folks generally use to contact us and we get questions redirected (Ralf and I). So we can do something like
"If you find anything you want to see written about in a blog post like
this one, please let us know! You can contact us at [email protected]."
There was a problem hiding this comment.
A solid blog post with lots of helpful experiential information. I like the way each section is written as a story where readers can witness the original issue, triaging and finding its source, and iterating on how to fix it. I like the honesty and I think it's memorable.
I wouldn't be surprised to see this posted as-is minus the to-do comments, so I wouldn't block merging on any of my review. Thank you for documenting this process and team wins as a blog post!
| look at all of the [PST issues and PRs tagged with | ||
| accessibility](https://github.com/pydata/pydata-sphinx-theme/issues?q=label%3A%22tag%3A+accessibility%22). | ||
| If you find anything you would like to see written about in a blog post like | ||
| this one, please let us know! |
There was a problem hiding this comment.
I would hesitate to simply because I don't know what channels of communication we'll maintain. For example, we don't have an email I'm aware of that we are always watching, and I don't know if authors get notified of blog post comments.
| If you find anything you would like to see written about in a blog post like | ||
| this one, please let us know! | ||
|
|
||
| ## Accessibility in this Blog Post |
There was a problem hiding this comment.
This is a cool section. Even though it felt separate from the rest of the blog post to me, I would keep it. For example, I totally went to check the description for the code and was pleasantly surprised to find Codepens instead of images.
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
Other than the existing one? Or are you asking if the existing one makes sense?
While I can't speak from a regular code-writer's perspective, I think having the information represented as code and rendered supports understanding the how behind the before and afters you are showing. This Codepen is also not very long so I don't think it becomes a big obstacle by accident.
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
I think the one that is there works for my understanding.
| for people without disabilities, too. | ||
|
|
||
| For those not familiar with Sphinx, it is a framework for writing documentation. | ||
| It is used, for example, to generate the official Python docs. As with many such |
There was a problem hiding this comment.
docs -> documentation ? in a few places maybe. I thing docs is colloquial.
There was a problem hiding this comment.
It was a deliberate choice. However, I suppose you won't be the only reader to have that reaction, so I'll change it
| such theme, created by and for the PyData community, is the PyData | ||
| Theme. | ||
|
|
||
| For those not familiar with accessibility, it is the practice of adapting built |
There was a problem hiding this comment.
2 paragraph starting with For those not familiar with.
There was a problem hiding this comment.
Perhaps best reworded to
| For those not familiar with accessibility, it is the practice of adapting built | |
| Accessibility is the practice of adapting built |
There was a problem hiding this comment.
Hmm, the repetition was intentional to help the reader skim. Perhaps what irks is that they are separate paragraphs? Maybe better to combine them into one?
| <!-- ... --> | ||
| </ul> | ||
| </li> | ||
| ``` |
There was a problem hiding this comment.
Not for here, but I'm not sre we should have dark code block for a light theme blog.
There was a problem hiding this comment.
I have no strong feelings here so will leave it to y'all to make a decision here
| The most important kind of before-and-after fix that we made was to add focus | ||
| rings to places where they were missing. Now, you might wonder why there were | ||
| missing focus rings to begin with, since the browser provides them by default. TODO: | ||
| Ask Chris Holdgraff if he knows about Sphinx-copybutton and Sphinx-togglebutton |
There was a problem hiding this comment.
I looked in git history and found no particular reasons.
There was a problem hiding this comment.
ping @choldgraf if he remembers why.
| Sphinx Theme. For this blog post, I chose three such improvements (out of many!) | ||
| to examine with a before-and-after lens to give a better idea of how these kinds | ||
| of changes can create an improved user experience for disabled people—and often | ||
| for people without disabilities, too. |
There was a problem hiding this comment.
This is a small nit-pick, so feel free to ignore if you don't feel the same. As a non-native english speaker, I found the sentence "For this blog post, I chose...without disabilities, too." a bit too long and hard to follow. I think breaking it into two sentences could help.
Something like this maybe:
For this blog post, I chose three such improvements (out of many!) to examine with a before-and-after lens. This will give a better idea of how these kinds of changes can improve user experience for disabled people—and often
for people without disabilities, too.
| authors: [gabriel-fouasnon] | ||
| published: June 26, 2024 | ||
| description: 'A small showcase of accessibility improvements made to the PyData Sphinx Theme, Fall 2023-Spring 2024' | ||
| category: [Access-centered] |
There was a problem hiding this comment.
Think we have a documentation category no?
| such theme, created by and for the PyData community, is the PyData | ||
| Theme. | ||
|
|
||
| For those not familiar with accessibility, it is the practice of adapting built |
There was a problem hiding this comment.
Perhaps best reworded to
| For those not familiar with accessibility, it is the practice of adapting built | |
| Accessibility is the practice of adapting built |
| A small, subtle point of clarification before we begin. Throughout this blog | ||
| post, I will use screenshots from the [PyData Sphinx Theme | ||
| docs](https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html), which |
There was a problem hiding this comment.
Since the latest version is bound to change, perhaps the version against which you are comparing should be spelled out
There was a problem hiding this comment.
Good point, will add in parentheses
| This section assumes that you know [what a screen reader | ||
| is](https://en.wikipedia.org/wiki/Screen_reader). | ||
|
|
||
| If you are sighted, then when you visit a website, you are used to seeing the |
There was a problem hiding this comment.
| If you are sighted, then when you visit a website, you are used to seeing the | |
| If you are a sighted person, then when you visit a website, you are used to seeing the |
| content arranged in a limited number of ways: typically, a header, a main area, | ||
| a footer, maybe a sidebar. Visual cues like alignment, horizontal lines, and | ||
| font sizes all work together to help your eyes and brain to scan the page to | ||
| know where to look. But if you are blind, you rely on landmarks to fulfill the |
There was a problem hiding this comment.
| content arranged in a limited number of ways: typically, a header, a main area, | |
| a footer, maybe a sidebar. Visual cues like alignment, horizontal lines, and | |
| font sizes all work together to help your eyes and brain to scan the page to | |
| know where to look. But if you are blind, you rely on landmarks to fulfill the | |
| content arranged in a limited number of ways: typically, a header, a main area, | |
| a footer, maybe a sidebar. Visual cues like alignment, horizontal lines, and | |
| font sizes all work together to help your eyes and brain scan the page to | |
| know where to look. But if you are a person who is blind, you rely on landmarks to fulfill the |
I generally prefer either a person or identity-first vs blind/sighted alone
| In order to be useful, the set of landmarks needs to be short and unambiguous. | ||
| There should be one and only one landmark for the main part of the page, just as | ||
| there should only be one header and one footer. It’s okay to have multiple | ||
| navigations, but they should be clear and distinct from each other. |
There was a problem hiding this comment.
| In order to be useful, the set of landmarks needs to be short and unambiguous. | |
| There should be one and only one landmark for the main part of the page, just as | |
| there should only be one header and one footer. It’s okay to have multiple | |
| navigations, but they should be clear and distinct from each other. | |
| To be useful, the set of landmarks needs to be short and unambiguous. | |
| There should be one and only one landmark for the main part of the page, just as | |
| there should only be one header and one footer. It’s okay to have multiple | |
| navigations, but they should be clear and distinct from each other. |
prefer simpler language...
| other words, with only a keyboard. Not only does this help low-vision users; | ||
| providing full keyboard access is like providing a kind of input API to your | ||
| site. Different kinds of assistive tech can hook into the same interface |
There was a problem hiding this comment.
| other words, with only a keyboard. Not only does this help low-vision users; | |
| providing full keyboard access is like providing a kind of input API to your | |
| site. Different kinds of assistive tech can hook into the same interface | |
| other words, with only a keyboard. Not only does this help low-vision users; | |
| providing full keyboard access is like providing an input API to your | |
| site. Different kinds of assistive tech can hook into the same interface |
There was a problem hiding this comment.
Nice one @gabalafou, I think we can leave the blog as is. After re-reading this does not feel too long and there are enough breaks with code samples and images.
| worth mentioning that screen readers, such as macOS VoiceOver and NVDA, will | ||
| generally provide keyboard interactivity for the label element in the absence of | ||
| the browser providing it, but it's also worth mentioning that to meet the [Web | ||
| Content Accessibility Guidelines success criterion | ||
| 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html), this sort of |
There was a problem hiding this comment.
| worth mentioning that screen readers, such as macOS VoiceOver and NVDA, will | |
| generally provide keyboard interactivity for the label element in the absence of | |
| the browser providing it, but it's also worth mentioning that to meet the [Web | |
| Content Accessibility Guidelines success criterion | |
| 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html), this sort of | |
| worth mentioning that screen readers, such as macOS VoiceOver and NVDA, will | |
| generally provide keyboard interactivity for the label element in the absence of | |
| the browser providing it. Note that to meet the [Web | |
| Content Accessibility Guidelines success criterion | |
| 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html), this sort of |
let's simplify this a bit
| role. The conclusion of that conversation for me was that an ARIA role is like a | ||
| user experience contract, and unless you plan to follow the contract exactly, |
There was a problem hiding this comment.
I like this framing 🔖 will keep this in mind
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
I generally like having small iterative or illustrative CodePen especially when following changes to interactive or nuanced states.
| </li> | ||
| ``` | ||
|
|
||
| [TODO: create a Codepen to illustrate this?] |
There was a problem hiding this comment.
My same comment from above applies here, experiencing the interaction change as well as seeing the code changes is useful.
| | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | ||
| |  |  | | ||
|
|
||
| The thing I don't love about this is that it is a somewhat unconventional |
There was a problem hiding this comment.
| The thing I don't love about this is that it is a somewhat unconventional | |
| The thing I don't love about this approach is that it is a somewhat unconventional |
| @@ -0,0 +1,479 @@ | |||
| --- | |||
| title: 'PyData Theme Accessibility Fixes' | |||
There was a problem hiding this comment.
| title: 'PyData Theme Accessibility Fixes' | |
| title: 'PyData Sphinx Theme Accessibility Fixes' |
There was a problem hiding this comment.
Maybe to make this a bit punchier and descriptiv, we can extend it to something like: "PyData Sphinx Theme Accessibility Fixes: a retrospective/lessons learned"
| page that the link goes to). Many of these states can overlap, hence | ||
| "frankenstates." For example, a link can be hovered and focussed at the same | ||
| time by using the mouse and keyboard together. It's a challenge to design for | ||
| all of these states in such a way that all the different frankenstates look |
There was a problem hiding this comment.
| page that the link goes to). Many of these states can overlap, hence | |
| "frankenstates." For example, a link can be hovered and focussed at the same | |
| time by using the mouse and keyboard together. It's a challenge to design for | |
| all of these states in such a way that all the different frankenstates look | |
| page that the link goes to). Many of these states can overlap. Hence, we coined the term "Franken states." For example, a link can be hovered and focussed simultaneously using the mouse and keyboard together. It's challenging to design for | |
| all of these states in such a way that all the different frankenstates look |
| active link green. But an access-centered designer is wary of relying on color | ||
| alone (because of various forms of color blindness and vision impairments). But | ||
| that removes an entire dimension from the design space, and you end up designing | ||
| for the frakenstates in much the same way that you would arrange a tiny | ||
| apartment: carefully, thoughtfully, creatively, skillfully, and with a | ||
| willingness to make needed compromises. |
There was a problem hiding this comment.
| active link green. But an access-centered designer is wary of relying on color | |
| alone (because of various forms of color blindness and vision impairments). But | |
| that removes an entire dimension from the design space, and you end up designing | |
| for the frakenstates in much the same way that you would arrange a tiny | |
| apartment: carefully, thoughtfully, creatively, skillfully, and with a | |
| willingness to make needed compromises. | |
| active link green. However, an access-centered designer is wary of relying on color | |
| alone (because of various forms of color blindness and vision impairments). But | |
| that removes an entire dimension from the design space, and you end up designing | |
| for the frakenstates in much the same way that you would arrange a tiny | |
| apartment: carefully, thoughtfully, creatively, skillfully, and with a | |
| willingness to make needed compromises. |
I find the but that removes... clause confusing, what removes an entire dimension? the use of colour only?
| look at all of the [PST issues and PRs tagged with | ||
| accessibility](https://github.com/pydata/pydata-sphinx-theme/issues?q=label%3A%22tag%3A+accessibility%22). | ||
| If you find anything you would like to see written about in a blog post like | ||
| this one, please let us know! |
There was a problem hiding this comment.
For PST feedback, this should be the PST repo and issues.
We do not have comments in our blog but there is a [email protected]
email that folks generally use to contact us and we get questions redirected (Ralf and I). So we can do something like
"If you find anything you want to see written about in a blog post like
this one, please let us know! You can contact us at [email protected]."
| present and structure your content. There are a number of things that I did in | ||
| writing this blog post to make it more accessible, for example: | ||
|
|
||
| - All of the images have alt text or are described by the surrounding text. Even |
There was a problem hiding this comment.
| - All of the images have alt text or are described by the surrounding text. Even | |
| - All images have alt text or are described by the surrounding text (in which case the alt text is an empty string). Even |
this is the recommended practice and some folks might not know
There was a problem hiding this comment.
Nice one @gabalafou , I think we can leave the blog as is. After re-reading this does not feel too long and there are enough breaks with code samples and images.
gabalafou
force-pushed
the
feature/pydata-theme-a11y-fixes
branch
from
27214fa to
4119a88
Compare
|
Update: I realized that our blog posts have headings out of order, and since I have a little section at the bottom that talks about that, I want to fix that before merging this PR. |
There was a problem hiding this comment.
This looks ready from my POV, but the PR is still in draft so will approve and leave it to @gabalafou to merge when ready
| authors: [gabriel-fouasnon] | ||
| published: June 26, 2024 | ||
| description: 'A small showcase of accessibility improvements made to the PyData Sphinx Theme, Fall 2023-Spring 2024' | ||
| category: [Access-centered] |
There was a problem hiding this comment.
PyData ecosystem for sure, maybe OSS experience
| <!-- ... --> | ||
| </ul> | ||
| </li> | ||
| ``` |
There was a problem hiding this comment.
I have no strong feelings here so will leave it to y'all to make a decision here
There was a problem hiding this comment.
This looks ready from my POV, but the PR is still in draft so will approve and leave it to @gabalafou to merge when ready
There was a problem hiding this comment.
This looks ready from my POV, but the PR is still in draft so will approve and leave it to @gabalafou to merge when ready
Co-authored-by: Isabela Presedo-Floyd <[email protected]>
Some tweaks to the text.
gabalafou
force-pushed
the
feature/pydata-theme-a11y-fixes
branch
from
86812b0 to
03a38d5
Compare
--------- Co-authored-by: Isabela Presedo-Floyd <[email protected]>
Preview URL
Preview: PyData Theme Accessibility Fixes
Text styling
Non-text contents