[Working Document] Accessibility Roadmap

[Sidnioulz]

Note

This is a working document listing known accessibility issues, up for discussion before being turned into actionable issues. The main post will be updated often. Please create new top-level conversations for each topic.

Known issues

(x)s indicate the section is written in the roadmap

Broken things

• Sidebar is not accessible
• Toolbar is not accessible
• Addon panel is not accessible
• Control editors, especially objects, are not accessible
• ArgsTable headings pollution
• IconButton missing labels and misuse
• General use of disabled vs aria-disabled
• Windows High Contrast Mode issues
• Story autoplay and WCAG 2.2.2/2.3.3

Underlying building blocks we're missing

• Toggle, Select
• Menu
• Tooltip
• Accordion
• Modal
• Live region

Tools we need

• Manual a11y testing guidelines
• Accessibility document

Sidebar

Problems

• The sidebar is not keyboard navigable
• Its DOM structure does not reflect its tree nature very well
• Secondary actions on sidebar items would lengthen kb nav and complicate VoiceOver support if kb nav worked

Solutions being considered

Code a basic nested list, like most navs are implemented.

1. A nested list of navigation links

Pros

• Building a 'simple' nested list would provide a very robust DOM structure that all ATs should be compatible with
• Many ATs provide keyboard shortcuts for quick navigation in lists

Cons

• We don't know how integrating accordion patterns would affect AT support; it might not be possible to do so and would require user research
• Implementing the HTML tree role provides better keyboard navigation for all users, not just AT users, considering the nav is indeed a tree view

2. A tree view wrapped in a nav

Use https://primer.style/product/components/tree-view/.

Pros

• Closest match between our current UI/behaviour and ARIA roles
• Easier keyboard navigation for all users
• Working, user-research tested implementation provided by GitHub covering all our use cases including secondary actions

Cons

• We may need to fork GitHub's implementation depending on whether its APIs, dependency chain and styling primitives work for us or not

Toolbar

Problems

• The toolbar is lacking proper semantics
• not a region, no heading
• no announcement of tool count

Solution being considered

• Wrap in a landmark region and add a heading
• Make other minor DOM adjustments (e.g. list items for individual tools)
• Switch to toolbar role with relevant kb nav (can be done later if time is scarse)

Addon panel

Problems

The addon panel is mostly unaudited.

• Addons like interactions and a11y are known to have problems around live notifications and expand/collapse patterns
• Focus states in the tabbar need to be reviewed (invisible on current tab)
• Current tab is not well advertised
• The tabbar uses the right ARIA roles but does not implement the expected kb nav pattern to go with it (https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ & https://web.archive.org/web/20130208024627/http://www.marcozehe.de/2013/02/02/advanced-aria-tip-1-tabs-in-web-apps/)
• Double announcements with Narrator? [Bug]: While navigating to “Controls, Actions, Interactions, Accessibility, Performance” tab items narrator announce twice announcement for tab items. #24123

Solution being considered

• Build a TabBar with the proper keyboard navigation and visual focus states
• Apply tabbar to addon panel
• Apply tabbar to a11y addon tabs ([A11y] Screen reader is not announcing the selection state of the "Violations"/"Passes"/"Incomplete" tab items in Accessibility Tab. #26674)
• Test and see if [Bug]: While navigating to “Controls, Actions, Interactions, Accessibility, Performance” tab items narrator announce twice announcement for tab items. #24123 is fixed?
• Address other addon-specific problems separately

Control editors

Problems

Controls are generally speaking not accessible because they are missing labels, and there are a few other quirks (e.g. misuse of aria-readonly). The object control in particular is not accessible because it's a hellish UX pattern with mixed tree navigation and editing, that likely cannot be made to comply with all screenreaders.

Solutions

We will first fix general control issues, not specific to object, in #32250.

We will then continue to gradually improve object control in #24150 without attempting to make it fully WCAG compliant just yet. We should focus on making sure the JSON editor button is reachable and easy to use, so that kb users have an alternative. We likely won't manage to make this accessible to blind users.

Windows High Contrast Mode

etc

Problems

There generally speaking are problems with Windows High Contrast mode because we don't test for that. These cause some parts of the UI to be translated into something unreadable or invisible.

Solutions being considered

The only way we know how to fix this is to manually apply the relevant proprietary CSS selectors and properties when issues are reported. We lack a testing mechanism.

---

Story autoplay and WCAG 2.2.2/2.3.3

Problems

The fact that interactive stories automatically play violates two WCAG success criteria:

• 2.2.2: Pause, Stop, Hide (Level A)
• 2.3.3: Animation from Interactions (Level AAA)

Automatically playing content causes distraction and mental strain for users with specific conditions and cognitive impairments, and causes motion sickness for users with vestibular disorders.

The prefers-reduced-motion CSS media feature exists precisely for us to disable animations for users who request it. We should disable autoplay when this feature is on. We should also provide global UI controls for users to play or pause autoplay prior to loading stories.

There is an internal pre-RFC on this topic. There are many implications to discuss and so work cannot start yet. #32247 was created to track the issue in GitHub.

IconButton labels and misuse

Problems

• IconButtons are not labelled throughout most of the application, they use title and/or tooltips instead resulting in inaccessible buttons for SR users
• Many cases of IconButton are not actual buttons (handled later) or mix icon and text content
• Generally speaking, our IconButton API doesn't support writing accessible code

Solution being considered

• IconButton should have a mandatory ariaLabel prop OR Button should mandate either an ariaLabel prop or an hasAccessibleContent declarative flag
• Tooltips that repeat the label and/or print out keyboard shortcuts should be handled at the API level

Disabled vs aria-disabled

Problem

Our interactive components use the disabled attribute, which breaks accessible for non-sighted users and generally speaking for keyboard users. Disabled content is not reachable by keyboard, so it is not discoverable and SR users end up not knowing that certain features exist and not being able to infer what to do to discover and use those features.

'## Solution being considered

The aria-disabled attribute should be used instead, to communicate disabled status and as a selector that styles the disabled state. Interactive components should themselves ensure that all interactions are disabled based on their disabled prop, rather than let user agents block interactions.

Toggle and Select

Problems

We have many specialised buttons that either apply a state or open a popup for a selection, that are treated as simple buttons with an inaccessible tooltip. When possible, we should replace those with specialised components that convey the correct role, keyboard navigation pattern, and cause screenreaders to correctly announce content and available actions.

Solutions being considered

Toggle and Select are being handled through the IconButton rework: #31702.

We'll soon have

• A Toggle button with a pressed state reported to ATs, for on/off features like measure or grid
• A Select component for most toolbar addons
• A Select with multiSelect for the vision simulator

Menu

Problems

We have many specialised buttons that either apply a state or open a popup for a selection, that are treated as simple buttons with an inaccessible tooltip. When possible, we should replace those with specialised components that convey the correct role, keyboard navigation pattern, and cause screenreaders to correctly announce content and available actions.

Solutions being considered

Toggle and Select are being handled through the IconButton rework.

Menu remains a problem. See #32236. We have a single menu that contains mixed navigation and options, making it optimal neither for a navigation disclosure pattern nor for a traditional menu pattern. Considering the low impact of the menu on day to day operations, we should find a basic kb nav solution now that costs as little as possible and revisit the issue later.

Tooltips

Problems

All components that use WithTooltip to produce a menu/listbox/popup with interactive components are inaccessible, because WithTooltip closes when attempting to focus into the menu. This is an implementation side effect of the "close on click outside" feature of the underlying library.

Solutions

We need to switch to something else (react-aria could be a good fit? they have a hook specifically for this) so we can have close on click outside without this buggy behaviour.

Then, we also want to show tooltips on focus rather than just on hover (in most cases). This is necessary to provide the same level of information to users with motor disabilities.

Accordion

Problems

We don't announce, on our expand/collapse patterns, that a button controls an expand/collapse state. This means some users can miss out on entire UI sections. Just triggering the button opens a UI section somewhere else, and it's not always clear what has happened or how to reach said UI section.

Recommended solutions

If instead we used the recommended pattern with a button that declares aria-expanded and the follow-up UI immediately after in tabbing order (or the now baseline details element), it would be easier to discover and use these UI sections.

Two ways forward:

1. we build a dedicated component
2. we locally apply details to the 3-4 offending use cases

I'm leaning towards local application because we have few use cases and they look radically different; building a headless component to accomodate these UI needs might be overkill.

Tooltip

Problems

• WithTooltipPure does not detect clicks outside its region
• WithTooltip treats focus on child element as a click outside its region and closes the child element, making it impossible to use keyboard navigation
• MobileAboutMenu drawer should be a nested modal so that keyboard focus trapping works
• zIndex conflicts between modals and tooltips

Modals

Problems

We currently use a mixture of HTML dialog and Radix Modal. Both are accessible. We need to pick a single solution going forward, and there might be a few UI areas where the dialog role should be used.

Live regions

We need to start using aria-live regions for features that run in the background, like tests and play functions.

ArgsTable headings pollution

Problems

Table headings should not directly contain buttons or other secondary elements, because that causes the content of these buttons to be announced on every row visit in the entire table, ruining screenreader experience. See https://adrianroselli.com/2025/07/check-uncheck-all-in-a-table.html for examples.

I've found one use case so far with "Reset args" in the ArgsTable; it can easily be tested with AssistivLabs and announces "reset controls" in every single control editing cell.

Solutions being considered

Put button outside table

This is pretty much standard practice for such a use case. The button should be placed outside the table. It doesn't matter as much whether it is placed before or after the table; in both cases it can be argued some users will miss the button initially as they navigate landmark to landmark and land on the table.

Pros

• It fixes a bug

Cons

• We need to write ~10-20 lines of CSS :-)