[docs] Improve rules table accessibility#24711
Conversation
|
Thank you? How did you test that these changes improve accessibility? Did you use the browser's aria inspector? How does before/after compare? |
0212031 to
33b3ef6
Compare
|
Apologies my initial commit was sloppy. I downloaded a screen reader and things did not work as intended. I re-implemented things based on the initial suggestion to use hidden spans. I added a class sr-only based on the tailwind implementation which creates text visible to screen readers only (https://tailwindcss.com/docs/display#screen-reader-only) Here is now a comparison between the current docs and the PR (volume up). before.webmafter.webm |
|
|
||
| fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>, linter: &Linter) { | ||
| table_out.push_str("| Code | Name | Message | |"); | ||
| table_out.push_str("| Code { scope='col' } | Name { scope='col' } | Message { scope='col' } | Fix/Status { scope='col' .sr-only } |"); |
There was a problem hiding this comment.
Do we need to set scope="col". I'd expect browsers to pick this up by default?
What's the reason for setting sr-only for Fix/Status. Are the screen readers otherwise repeating the column header?
There was a problem hiding this comment.
So for scope="col" I think the answer is probably not. I was following the recommendation from #13376 but the screen reader I tested seemed to handle things fine without it. I'm not sure if other screen readers would have trouble assigning the headers to the cells without it? I left it in because it seemed like a safe hedge, with no downside, but up to you.
For Fix/Status, I added the class, because the heading didn't exist before this PR, so I didn't want to introduce any new text. This way the heading helps people using a screen reader know the significance of the cells, but doesn't introduce any visual change. Not sure if that answered your question.
| RuleGroup::Removed { since } => { | ||
| format!( | ||
| "<span {SYMBOL_STYLE} title='Rule was removed in {since}'>{REMOVED_SYMBOL}</span>" | ||
| "<span aria-hidden='true' {SYMBOL_STYLE} title='Rule was removed in {since}'>{REMOVED_SYMBOL}</span><span class='sr-only'>Rule was removed in {since}</span>" |
There was a problem hiding this comment.
These changes make sense to me.
##### [\`v0.15.12\`](https://github.com/astral-sh/ruff/blob/HEAD/CHANGELOG.md#01512) Released on 2026-04-24. ##### Preview features - Implement `#ruff:file-ignore` file-level suppressions ([#23599](astral-sh/ruff#23599)) - Implement `#ruff:ignore` logical-line suppressions ([#23404](astral-sh/ruff#23404)) - Revert preview changes to displayed diagnostic severity in LSP ([#24789](astral-sh/ruff#24789)) - \[`airflow`] Implement `task-branch-as-short-circuit` (`AIR004`) ([#23579](astral-sh/ruff#23579)) - \[`flake8-bugbear`] Fix `break`/`continue` handling in `loop-iterator-mutation` (`B909`) ([#24440](astral-sh/ruff#24440)) - \[`pylint`] Fix `PLC2701` for type parameter scopes ([#24576](astral-sh/ruff#24576)) ##### Rule changes - \[`pandas-vet`] Suggest `.array` as well in `PD011` ([#24805](astral-sh/ruff#24805)) ##### CLI - Respect default Unix permissions for cache files ([#24794](astral-sh/ruff#24794)) ##### Documentation - \[`pylint`] Fix `PLR0124` description not to claim self-comparison always returns the same value ([#24749](astral-sh/ruff#24749)) - \[`pyupgrade`] Expand docs on reusable `TypeVar`s and scoping (`UP046`) ([#24153](astral-sh/ruff#24153)) - Improve rules table accessibility ([#24711](astral-sh/ruff#24711)) ##### Contributors - [@dylwil3](https://github.com/dylwil3) - [@AlexWaygood](https://github.com/AlexWaygood) - [@woodruffw](https://github.com/woodruffw) - [@avasis-ai](https://github.com/avasis-ai) - [@Dev-iL](https://github.com/Dev-iL) - [@denyszhak](https://github.com/denyszhak) - [@ShipItAndPray](https://github.com/ShipItAndPray) - [@anishgirianish](https://github.com/anishgirianish) - [@augustelalande](https://github.com/augustelalande) - [@amyreese](https://github.com/amyreese) - [@majiayu000](https://github.com/majiayu000) ##### [\`v0.15.11\`](https://github.com/astral-sh/ruff/blob/HEAD/CHANGELOG.md#01511) Released on 2026-04-16. ##### Preview features - \[`ruff`] Ignore `RUF029` when function is decorated with `asynccontextmanager` ([#24642](astral-sh/ruff#24642)) - \[`airflow`] Implement `airflow-xcom-pull-in-template-string` (`AIR201`) ([#23583](astral-sh/ruff#23583)) - \[`flake8-bandit`] Fix `S103` false positives and negatives in mask analysis ([#24424](astral-sh/ruff#24424)) ##### Bug fixes - \[`flake8-async`] Omit overridden methods for `ASYNC109` ([#24648](astral-sh/ruff#24648)) ##### Documentation - \[`flake8-async`] Add override mention to `ASYNC109` docs ([#24666](astral-sh/ruff#24666)) - Update Neovim config examples to use `vim.lsp.config` ([#24577](astral-sh/ruff#24577)) ##### Contributors - [@augustelalande](https://github.com/augustelalande) - [@anishgirianish](https://github.com/anishgirianish) - [@benberryallwood](https://github.com/benberryallwood) - [@charliermarsh](https://github.com/charliermarsh) - [@Dev-iL](https://github.com/Dev-iL) Renovate-Branch: renovate/2024.6-ruff-0.15.x Change-Id: I2c5de44f14ce3133db71161eae18c7b43f7ba09b Priv-Id: 9c1a7f10043a2db2338a90de9a62a4d7989df14d
Summary
Improve docs rules table accessibility, by adding scope='col' to the table headers, and aria-labels to the status and fix icons.
Resolves #13376 although I chose to go with aria-label instead of hidden spans. Willing to change if asked.
Test Plan
I compiled the docs and verified everything displayed correctly.