Screen reader accessibility friction: heading structure, ARIA landmarks, and focus management

Summary

Claude Code's conversation interface lacks the structural markup needed for screen reader users to navigate efficiently. This issue documents specific friction points experienced with NVDA on Windows and proposes concrete improvements. Individual issues are filed separately and linked below.

Environment

• Claude Code desktop app, Windows 11
• NVDA screen reader (latest stable)
• Electron-rendered conversation interface

---

Issue 1: No heading structure in conversation

The conversation view does not use heading elements to mark the boundaries between user prompts and assistant responses. Screen reader users rely on heading navigation (H key in NVDA) to move quickly through long documents. Without headings, the only way to jump to the most recent prompt or response is to use text search — for example, searching backward for the string "branch from here," which happens to appear reliably after each user prompt.

Recommendation 1: Implement a defined heading hierarchy

Each assistant response should follow this heading structure:

• H1 — The first sentence of the response. This does not need to be a title or summary; it is simply the opening sentence of the reply, marked as H1. This gives screen reader users a reliable top-of-response landmark they can jump to with a single keypress.
• H2 and below — Used as appropriate within the response to mark major sections, subsections, and other structural divisions.
• H5 — The final line of every response should be the string "End of response" wrapped in H5. This gives users a reliable bottom-of-response landmark, confirming that generation is complete and nothing has been missed.

User prompts should similarly be preceded by a heading element (H2 recommended) so users can jump backward through the conversation history to review their own input.

---

Issue 2: Permission dialogs do not receive focus

When Claude Code displays a permission request — for example, asking whether to allow a file write or a shell command — focus is not moved to the dialog or button. NVDA users receive no automatic announcement that input is required. The only way to discover the dialog is to navigate manually through the interface.

Recommendation 2: Auto-focus and announce permission and input requests

When Claude Code displays any request for user input — including permission dialogs, confirmation prompts, and tool approval requests — the following behavior is recommended:

1. Announce the topic — The nature of the request should be announced automatically via an ARIA live region or role="alert" element. The announcement should describe what action is being requested and why (e.g., "Permission requested: write to file config.json").
2. Move focus to the response buttons — Focus should be placed on the primary action button (typically "Allow" or "Yes") when the dialog appears.
3. Tab order among buttons — All response buttons in the dialog should be in the natural tab order, allowing the user to move between options (e.g., Allow, Deny, Allow Always) with the Tab key before making a selection.

---

Issue 3: Repository and branch link lists create navigation friction

In sessions that involve GitHub repositories, the interface accumulates large numbers of repo and branch links between the input field and the response area. These links have no enclosing landmark or skip mechanism. Navigating past them by tab or virtual cursor is time-consuming and worsens as sessions grow longer.

Recommendation 3: Provide a way to compact or bypass the repository control area

The repository and branch link region should offer one or more of the following:

• A "Simplify UI" setting that collapses or hides the repository control area, surfacing only the most essential controls and reducing clutter for users who do not need persistent access to branch and repo links.
• A skip link at the top of the region (similar to "skip to main content" patterns) that allows keyboard and screen reader users to jump past the entire block in a single keypress.
• Wrapping the region in a <nav> landmark with an aria-label such as "Repository controls," enabling users to bypass it using NVDA's landmark navigation (D key).

---

Issue 4: No announcement when response is generating or complete

There is no signal accessible to a screen reader that Claude is still generating a response or has finished. Users must navigate manually to the bottom of the response area to check status, and there is no passive indication that work is ongoing.

Recommendation 4: Announce response progress and completion

• While generating: The elapsed time display should be wrapped in an ARIA live region set to aria-live="polite", allowing NVDA to periodically announce elapsed time without interrupting speech. The elapsed time element should also carry a heading (H3 or H4 recommended) so users can navigate directly to it.
• On completion: When generation finishes, an ARIA live region should be updated with a brief notice such as "Response complete." Using aria-live="polite" ensures the announcement queues after any current speech rather than interrupting it.

---

Impact

These gaps make Claude Code significantly more difficult to use for blind and low-vision users who rely on screen readers. The workarounds are fragile, depend on incidental text strings in the interface, and worsen as sessions grow longer. The fixes are well-established ARIA patterns and should not require significant architectural changes.

Individual issues

• [ ] #69997 — Heading structure in conversation view
• [ ] #69998 — Permission dialog focus and announcements
• [ ] #69999 — Repository link navigation friction
• [ ] #70000 — Response progress and completion announcements

References

• ARIA Authoring Practices Guide: https://www.w3.org/WAI/ARIA/apg/
• NVDA screen reader: https://www.nvaccess.org/