docs/react-v9/contributing/accessibility-troubleshooting.md
We test with the following screen readers, using the latest version:
We do not support the following browsers, screen readers, or settings:
Note: while we test in the listed screen readers, there may still be issues that root cause in browsers, accessibility APIs, or the screen reading software. If there are no authoring errors or workarounds contributing to an issue, the bug will end up being external to the browser or screen reader.
For other ATs such as Dragon, ZoomText/Fusion, braille displays, etc. we will still implement fixes if the bug is root causing in Fluent.
For internal Microsoft employees, check our v9 known bugs wiki or v8 known bugs wiki before reporting an issue.
Check for duplicate issues! Many accessibility issues are reported multiple times. If they are caused by external factors such as screen reader issues they may take some time to resolve.
Verify that any reported accessibility tool errors are valid. For example, one oft-reported issue concerns buttons with a role=gridcell, which is now allowed. Consider checking accessibility tool repos for existing issues:
Find a reference example implementing the same general ARIA pattern and see if the reference example exhibits the same behavior in the same browser/assistive tech combination.
role the component is using. This is most often accomplished by looking for role attribute value either in the source code or by inspecting the element's role attribute in a browser.role.Verify ARIA is implemented by Fluent UI React correctly. Note applicable references:
role attribute.Use auditing tools such as Accessibility Insights to validate implementation.
Don't assume:
Before modifying ARIA roles, attributes or component navigation behavior, make sure you check the ARIA Role Definitions, ARIA Attributes, and ARIA Design Patterns to verify correct behavior.
Let's say we have an issue that says Switch is not dictating its description AND aria-label must be added to Switch for voice dictation.
The first observation is that this is actually two different bugs, both of which should be verified. They are not necessarily related.
Switch has the role of switch. We can review the switch role reference to find required attributes. It tells us that aria-label is not a required attribute.
We can review the aria-label attribute reference to find the following:
If the label text is visible on screen, authors SHOULD use aria-labelledby and SHOULD NOT use aria-label. There may be instances where the name of an element cannot be determined programmatically from the content of the element, and there are cases where providing a visible label is not the desired user experience. Most host languages provide an attribute that could be used to name the element (e.g., the title attribute in HTML), yet this could present a browser tooltip. In the cases where a visible label or visible tooltip is undesirable, authors MAY set the accessible name of the element using aria-label. As required by the text alternative computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.
What does this tell us?
aria-label is not a required propertyaria-label if the description is available onscreen. Rather, we should be using aria-labelledby attribute or a label + for/id association.aria-label should only be used if no descriptive text is available elsewhere on the screen.The Fluent Switch documentation additionally has documentation on how to provide a label with the label prop, as well as tips on how to write good label text. The built-in label prop handles id association under the hood, and no further ARIA or other work is required.
What can we conclude?
The true conclusion here is that Switch requires an accessible name, but not specifically aria-label. There are many instances of logged bugs asking for specific ARIA attributes, when in reality the best solution lies elsewhere. It is always worth taking specific ARIA recommendations in accessibility bugs with a healthy amount of skepticism.
Switch provides an onscreen description already, it doesn't make sense to always provide aria-label.Switch has a descriptive label on it, we should NOT be redundantly putting this information in aria-label. Instead, we should be using the built-in label prop to provide an accessible name.Switch has an accessible name and is behaving similarly to the ARIA reference, we can also consider that this may be a browser or screen reader bug.role definition.To log a bug on Fluent, follow the guidance in our Partner A11y Issue Filing Process wiki.
To log bugs on Edge, Narrator, or external browsers or external software, first create an isolated reproduction of the issue and then coordinate with the vendor testers to log the bug and track it.