Skip to content

a11y: Settings UI - #59429

Merged
cameron1024 merged 13 commits into
mainfrom
settings-ui-a11y
Jun 17, 2026
Merged

a11y: Settings UI#59429
cameron1024 merged 13 commits into
mainfrom
settings-ui-a11y

Conversation

@cameron1024

Copy link
Copy Markdown
Contributor

Adds:

  • aria attributes to most UI elements in settings UI
  • a new a11y API to GPUI
  • a fix for a GPUI keyboard focus bug

Accesible settings UI

Settings UI should now be fully accessible to users of assistive technology.

However, there are some caveats:

  • accessibility features require zed to be launched with the ZED_EXPERIMENTAL_A11Y=1 env var to be set
  • I have not exhaustively checked every control
  • There are some quite surprising keyboard focus behaviours which predate this code
  • The main Zed UI is still largely inaccessible, though a handful of shared components will now report themselves, but the experience is suboptimal.

For anyone wishing to try out the settings UI:

  • make sure ZED_EXPERIMENTAL_A11Y=1 is set
  • open zed
  • press ctrl-, (or cmd+, on a mac) to open settings UI in a separate window

aria_active_descendant

This is equivalent to the aria-activedescendant API on the web.

It allows a container to maintain focus, while indicating that one of its children should be active. Zed uses this for menus and combo boxes, for example.

GPUI will report a div with .aria_active_descendant() as long as:

  • an ancestor is focused
  • only one descendant of the focused ancestor has .aria_active_descendant()

Two descendants with this property where the focused node is a common ancestor is an error.

GPUI keyboard fix

GPUI will map a space or enter keypress to a div's on_click handler, if it exists. However, the keyboard-driven path was missing some checks that the mouseclick path has.

With this PR, for an enter/space keypress to be considered a click, between the "key down" and "key up" events:

  • there must be no other key events
  • focus must not move to a different node

This fixes an existing bug with combo boxes in zed where:

  • enter maps to menu::Confirm *on key down
  • the menu item is selected
  • focus moves to the combo box
  • enter then triggers the combo box's on_click on key up, re-opening the menu

Release Notes:

  • N/A or Added/Fixed/Improved ...

@cla-bot cla-bot Bot added the cla-signed The user has signed the Contributor License Agreement label Jun 16, 2026
@zed-community-bot zed-community-bot Bot added the staff Pull requests authored by a current member of Zed staff label Jun 16, 2026
@cameron1024
cameron1024 added this pull request to the merge queue Jun 17, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jun 17, 2026
@cameron1024
cameron1024 added this pull request to the merge queue Jun 17, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jun 17, 2026
@cameron1024
cameron1024 added this pull request to the merge queue Jun 17, 2026
Merged via the queue into main with commit 83d4847 Jun 17, 2026
34 checks passed
@cameron1024
cameron1024 deleted the settings-ui-a11y branch June 17, 2026 17:46
This was referenced Jun 18, 2026
jolutz pushed a commit to jolutz/zed that referenced this pull request Aug 8, 2026
Adds:
- aria attributes to most UI elements in settings UI
- a new a11y API to GPUI
- a fix for a GPUI keyboard focus bug

## Accesible settings UI

Settings UI should now be fully accessible to users of assistive
technology.

**However**, there are some caveats:
- accessibility features require zed to be launched with the
`ZED_EXPERIMENTAL_A11Y=1` env var to be set
- I have not exhaustively checked every control
- There are some quite surprising keyboard focus behaviours which
predate this code
- The main Zed UI is still largely inaccessible, though a handful of
shared components will now report themselves, but the experience is
suboptimal.

For anyone wishing to try out the settings UI:
- make sure `ZED_EXPERIMENTAL_A11Y=1` is set
- open zed
- press `ctrl-,` (or `cmd+,` on a mac) to open settings UI in a separate
window

## `aria_active_descendant`

This is equivalent to the
[`aria-activedescendant`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant)
API on the web.

It allows a container to maintain focus, while indicating that one of
its children should be active. Zed uses this for menus and combo boxes,
for example.

GPUI will report a div with `.aria_active_descendant()` as long as:
- an ancestor is focused
- only one descendant of the focused ancestor has
`.aria_active_descendant()`

Two descendants with this property where the focused node is a common
ancestor is an error.

## GPUI keyboard fix

GPUI will map a space or enter keypress to a div's `on_click` handler,
if it exists. However, the keyboard-driven path was missing some checks
that the mouseclick path has.

With this PR, for an enter/space keypress to be considered a click,
between the "key down" and "key up" events:
- there must be no other key events
- focus must not move to a different node

This fixes an existing bug with combo boxes in zed where:
- enter maps to `menu::Confirm` **on key down*
- the menu item is selected
- focus moves to the combo box
- enter then triggers the combo box's `on_click` **on key up**,
re-opening the menu

---

Release Notes:

- N/A or Added/Fixed/Improved ...

---------

Co-authored-by: zed-zippy[bot] <234243425+zed-zippy[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed The user has signed the Contributor License Agreement staff Pull requests authored by a current member of Zed staff

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants