Accessibility Troubleshooting
- Microsoft Edge & Narrator
Issues that do not reproduce in Edge & Narrator should be filed with the respective screen reading software, not the Fluent UI repo.
-
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 contrast against disabled text, and disabled text does not have a contrast requirement. Consider checking accessibility tool repos for existing issues:
- Accessibility Insights
- Axe Core (used by Accessibility Insights)
-
Find a reference example implementing the same ARIA
role
and see if the reference exhibits the same behavior.- Examples are usually found with a simple search of terms of "aria role example", such as "aria grid example".
- Determine what
role
the component is using. This is most often accomplished by looking forrole
attribute value either in the source code or by inspecting the element'srole
attribute in a browser. - The easiest way to find a reference is to search for
aria role x
oraria attribute y
wherex
is the component role andy
is the attribute name. For example searchingaria grid role
brings up some reference implementations for various grid implementations.
-
Test the ARIA reference example with Microsoft Edge and Narrator.
- If the issue does happen with Microsoft Edge and Narrator with ARIA reference examples, this is a strong indicator of a Microsoft Edge or Narrator issue and should be resolved as external.
- If the issue does not happen with Microsoft Edge and Narrator:
- If the issue is reported against JAWS, NVDA, or another browser, the issue is with the screen reader or browser and should most likely be resolved as external.
- If the issue is reported against Microsoft Edge & Narrator, then continue trubleshooting below.
-
Verify ARIA is implemented by Fluent UI React correctly. Note applicable references:
-
ARIA Role Definitions for determining component attribute behavior by component's
role
attribute. - ARIA Attributes for determining required attributes and correct attribute behavior.
- ARIA Design Patterns for specifying component behavior, such as navigation behavior.
-
ARIA Role Definitions for determining component attribute behavior by component's
-
Use auditing tools such as Accessibility Insights to validate implementation.
Don't assume:
- That any missing ARIA attribute is required.
- That any ARIA is better than no ARIA.
- That the issue is with Fluent UI React as opposed to MS Edge/Narrator/consuming app/third-party software.
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 Toggle
is not dictating its description AND aria-label
must be added to Toggle
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.
Toggle
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 property - We shouldn’t be providing
aria-label
if the description is available onscreen. Rather, we should be usingaria-labelledby
attribute. -
aria-label
should only be used if no descriptive text is available elsewhere on the screen.
What can we conclude?
- Since
Toggle
provides an onscreen description already, it doesn't make sense to always providearia-label
. - If
Toggle
has a descriptive label on it, we should NOT be redundantly putting this information inaria-label
. Instead, we should be usingaria-labelledby
to point to the existing label text. - We should make sure
Toggle
has anaria-labelledby
attribute pointing to the existing onscreen description. Users should be able to optionally setaria-label
for instances where an onscreen description is not available. - If
Toggle
is doing what it should according to the ARIA reference, we can also consider that this may be a browser or screen reader bug.
-
ARIA Role Definitions for determining component attribute behavior by component's
role
definition. - ARIA Attributes for determining required attributes and correct attribute behavior.
- ARIA Design Patterns for specifying component behavior, such as navigation behavior.
- Sign into https://issues.microsoftedge.com with your account.
- Check for a pre-existing issue, hit
Me too
underReports
on the issue if it exists. Otherwise,Open new issue
. - Please provide the Windows build number (
Settings
>System
>About
), which screen readers replicate the issue, detailed steps to reproduce the issue, and a simplified test case, such as a JS Fiddle.
The best way to file feedback is via the feedback hub built into Windows. Put Accessibility
and Narrator
in the feedback item for increased visibility.
- FAQ - Fabric and Stardust to Fluent UI
-
@fluentui/react
Version 9 -
@fluentui/react
Version 8 - Contributing to the
7.0
branch - How to apply themes (version 7/8)
- Planning and development process (for work by the core team)
- Conducting meetings Style guide
- Keeping up with review requests
- RFC review process
- Setup (configuring your environment)
- Fluent UI React version 7/8
- CLA
- Overview
- Repo structure
- Development process
- Contributing to previous versions
- API Extractor
- Build command changes made in early 2020
- Component implementation guide
- Creating a component
- Implementation Best Practices
- Theming
- Documenting
- Styling (old approach)
- Overview
- Testing with Jest
- E2E testing (Cypress)
- Visual testing (Screener)
- Accessibility review checklist