docs: add page for notification debugging help #34818
Conversation
📊 Bundle size report✅ No changes found |
|
Pull request demo site: URL |
|
|
||
| # Debugging screen reader notifications and live regions | ||
|
|
||
| Live region notifications are one of the most temperamental accessibility features, compounded by how difficult they are to debug. A significant part of their functionality is handled within screen reader implementations, and is both undocumented and differs between screen readers. |
There was a problem hiding this comment.
I have it written down in my doc that behavior also differs between browsers, if you think that's worth mentioning here! Pasting the blurb from my doc in case it's helpful :)
The result of screenreader interactions can differ between browsers. By repeating the same actions that trigger the bug in each browser, you can sometimes narrow down the bug to specific browser and screenreader interactions.
|
|
||
| ## Step 1: check for conflicting user interactions or focus changes | ||
|
|
||
| If a live region change is not getting read by a screen reader, first check if the screen reader is instead reading other information at the same time (concurrent focus changes or typing are common causes of this). If this is happening, there is a good chance that the live region is functioning as expected but the output is being overridden. |
There was a problem hiding this comment.
I don't know if it's worth mentioning explicitly in case it's second nature for a more experienced dev, but I had this blurb about how to check if the notification is being overridden:
If you are working directly inside of the Fluent AI or Fluent UI repos, this part is slightly easier. Navigate directly to the file where useAnnounce is implemented and drop a console.log print statement directly into the announce function.
If you are working in the browser, for example in a site like Stackblitz, navigate to the browser’s developer tools, enter the Sources tab, and add breakpoints.
Adds a "debugging notifications" docs page to the accessibility section of our storybook docs, and links to it from the docs for relevant controls/utils.
This is a pretty common / thorny accessibility issue from partner teams that's pretty hard to debug without a11y help. I figured a docs page of what I most commonly tell folks to try when they encounter a live region bug would be useful.