zai-org / zai-org/feedback

Accessibility: Slash-command suggestion menu options are hidden from screen readers

Open
#108 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

Title: Accessibility: Slash-command suggestion menu options are hidden from Windows UIA and screen readers (missing ARIA listbox/option roles)

Summary

In the ZCode desktop application, typing / in the chat input opens a slash-command and skills suggestions menu. While this menu is visually visible and navigable using the Arrow keys, it is completely hidden from Windows UI Automation (UIA) and assistive technologies like screen readers (NVDA/JAWS). Users relying on screen readers receive no spoken feedback when the menu opens and cannot hear which options are highlighted as they navigate.

Diagnostic Details

We performed a direct UI Automation (UIA) tree probe on the ZCode application window. During the probe:

  1. No Accessibility Tree Changes:
    Opening the slash-command menu by typing / did not trigger any structural changes in the UIA accessibility tree. The tree difference remained 0 added, 0 removed, 0 changed.
  2. Focus Trapped in Text Input:
    When pressing the Up/Down arrow keys to change the highlighted command option, keyboard focus stayed entirely on the main text input element. Assistive technologies are unaware of any selection changes because:
    • The dropdown container does not announce itself as a role="listbox".
    • The suggestion options are not exposed with role="option".
    • The main text input element does not establish a relationship link with the suggestion list (lacks aria-controls and does not dynamically update aria-activedescendant during arrow-key navigation).
Expected Behavior

To comply with standard accessibility patterns (WAI-ARIA Combobox design pattern):

  1. The popup suggestions container should be exposed to the accessibility engine with role="listbox".
  2. Each item in the suggestions list (such as /goal, /compact, or $caveman) should have role="option" and update its aria-selected state dynamically when highlighted.
  3. The main chat input element should declare the connection using:
    • aria-haspopup="listbox"
    • aria-controls="[id-of-listbox]"
    • aria-activedescendant="[id-of-currently-highlighted-option]" (updated dynamically as the user navigates using the Arrow keys).

This ensures screen readers can capture the event changes and announce the active menu option as the user cycles through them.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No implementation files, tests, or entry points are identified in the issue. Locate the desktop chat input and slash-command suggestion menu, then inspect their accessibility tree while typing / and navigating with the Arrow keys. Done means the popup and options are exposed to UIA and screen readers, with highlighted options announced as described; verify with NVDA, JAWS, or a UIA probe.

Written by the indexing model from the issue text.

Assessment

Domain
accessibility, desktop
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.