[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? |
augustelalande
force-pushed
the
accessibility
branch
from
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.
3 participants
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.