USWDS - Table: Allow stacked table to be readable with VoiceOver + Safari combo

[mahoneycm]

Summary

Fixed a bug that prevented VoiceOver from reading stacked table content while using Safari.

Breaking change

This is not a breaking change

Related issue

Closes #5434

Related pull requests

Changelog →

Preview link

Stacked table →

Problem statement

Specifically when using VoiceOver on Safari, tables with display: block on the are skipped or read as empty.

This is caused by a well known bug¹ which causes tables with display properties to break accessibility with screen readers.

This bug used to affect most browsers, but in recent years has been resolved. Safari seems to be the only browser still affected by this. At the time of this PRs creation the referenced article was last updated: August 14th, 2023.

Additional mdn doc PR with a well organzied list of associated bugs: mdn/browser-compat-data#19994

Solution

I was able to improve the screen reader experience by removing display: block from stacked table tr tags.

Now, VoiceOver + Safari can properly navigate through the stacked table’s content and read it’s values

Differences

There is one slight difference between the way VO + Safari read the table data compared to other browsers.

Other browsers will read cells data labels with “column # of #” depending on how many data cells there are in each row. In our example, this would be “column 1 of 3” for example.

Safari now reads this as “Column 1 of 1”. While this differs from the other browsers, it is considered accurate because there is only one column.

The downside is that it doesn’t let the user know how many “columns” (if table wasn't stacked) are within the said “row”.

VoiceOver will correctly read out how many “rows” (sections) of the stacked table there are.

This is caused by a Safari bug

Tables with display: block on the and give the wrong column count.²

Testing and review

Confirm existence of bug

1. Visit develop branch stacked table variant on Safari →
2. Activate VoiceOver
3. Attempt to navigate table using keyboard inputs
   • Note that VO key + up/down arrows will jump between rows
4. Visit the stacked table variant on another browser
5. Confirm proper readouts

Confirm improvement

1. Visit preview on Safari →
2. Confirm no visual regression
3. Attempt to navigate the table with VoiceOver and keyboard inputs
4. Confirm you are able to access all cell information
5. Repeat for another browser
6. Confirm no unexpected changes

Testing checklist

• Stacked table is now accessible using VoiceOver + Safari
• Confirm we’re comfortable with the readout addressing each row as a single column
• No unexpected changes to other browsers
• No visual regressions

Footnotes

1. https://adrianroselli.com/2022/07/its-mid-2022-and-browsers-mostly-safari-still-break-accessibility-via-display-properties.html ↩

2. https://github.com/mdn/browser-compat-data/issues/19994 ↩

[amycole501]

Unable to test in Safari. Do you want me to test in JAWS and/or NVDA?

[mahoneycm]

@amycole501 Yeah if you don't mind comparing to the develop builds with other browsers/screen readers to confirm no accidental readout changes that would be great!

[amyleadem]

@mahoneycm, this is looking good! I like that there is a clean, one-line answer to an important bug fix.

I don’t see a big issue with Safari reading the content out as one column. It is not ideal but it is better than what we have now and does match the visual presentation.

I tested on Chrome, Safari, and Firefox with VoiceOver in MacOS. I also tested in iOS Safari with VoiceOver Gestures. I tested the following:

• Confirmed existence of the bug with VoiceOver in Safari on MacOS and VoiceOver Gestures Safari on iOS
• Confirm that the stacked table content is now accessible with VoiceOver in Safari VoiceOver Gestures in iOS Safari
• Confirm no visual regression in Safari and other browsers
• Confirm the readout makes sense
• Confirm no visual or screen reader regression in other browsers

[amycole501]

The table sounds great in JAWS in Chrome. No issues detected and all rows were read correctly. I'm currently having issues with NVDA reading the table. However, I asked @alex-hull if it sounded OK to her and she said it's good; it read the table data and rows. I just installed an update to NVDA so I think it's just a glitch for me and the table is fine as-is.

[mahoneycm]

@amycole501 Glad to hear it! Would you mind approving the PR if it looks good to you? Whenever you get the chance 😊

[mejiaj]

Good research on this.

Tested on Chromium, Firefox, Safari without visual regressions. As well as with VoiceOver. Removed the mobile width container to make sure desktop wasn't affected.

[thisisdano]

Clean fix, great documentation!