kayg/hermternal-apple
Watch
1
0
Fork
You've already forked hermternal-apple
 0
Code Issues 44 Pull requests Projects Releases 4 Packages Wiki Activity Actions

Complete a native accessibility audit and remediation pass #13

New issue
Open
opened 2026-08-21 08:36:17 +00:00 by kayg · 3 comments
kayg commented 2026-08-21 08:36:17 +00:00
Owner
Copy link

Goal

Complete a native accessibility audit and remediation pass across Hermternal before adding more visual complexity.

Coverage

  • VoiceOver: meaningful names/values/traits, logical reading order, streaming announcements that do not speak every token, and focus restoration across chat switches.
  • Full Keyboard Access: sidebar, transcript, composer, Settings, alerts, and future ⌘K palette; visible focus and predictable shortcuts.
  • Dynamic Type / larger accessibility sizes without clipped sidebar rows, bubbles, code blocks, or controls.
  • Increase Contrast, Differentiate Without Color, Reduce Transparency, and Reduce Motion.
  • Light/dark/theme contrast, including glass over changing desktop content.
  • Text selection, link/code actions, error/progress announcements, and minimum hit targets.

Performance guardrails

Accessibility must not add per-token announcements, eager accessibility trees for off-screen transcript rows, or repeated full-transcript Markdown parsing. Measure VoiceOver navigation on a 500+ row cached chat.

Acceptance

Audit with Accessibility Inspector and VoiceOver on the real macOS app; record and fix every blocker/serious finding, then verify keyboard-only completion of sign-in, chat selection, sending, interrupting, and Settings changes.

## Goal Complete a native accessibility audit and remediation pass across Hermternal before adding more visual complexity. ## Coverage - VoiceOver: meaningful names/values/traits, logical reading order, streaming announcements that do not speak every token, and focus restoration across chat switches. - Full Keyboard Access: sidebar, transcript, composer, Settings, alerts, and future ⌘K palette; visible focus and predictable shortcuts. - Dynamic Type / larger accessibility sizes without clipped sidebar rows, bubbles, code blocks, or controls. - Increase Contrast, Differentiate Without Color, Reduce Transparency, and Reduce Motion. - Light/dark/theme contrast, including glass over changing desktop content. - Text selection, link/code actions, error/progress announcements, and minimum hit targets. ## Performance guardrails Accessibility must not add per-token announcements, eager accessibility trees for off-screen transcript rows, or repeated full-transcript Markdown parsing. Measure VoiceOver navigation on a 500+ row cached chat. ## Acceptance Audit with Accessibility Inspector and VoiceOver on the real macOS app; record and fix every blocker/serious finding, then verify keyboard-only completion of sign-in, chat selection, sending, interrupting, and Settings changes.
kayg commented 2026-08-22 04:23:42 +00:00
Author
Owner
Copy link

Related follow-on: new issue #26 (Verify Reduce Transparency and add opaque fallback) covers a narrower, concrete verification and implementation slice within this audit's Reduce Transparency coverage. Keep #26 as a separate issue for the explicit opaque fallback across all glass/material surfaces and transition/relaunch verification; use this issue as the broader audit and remediation authority.

Related follow-on: new issue #26 (Verify Reduce Transparency and add opaque fallback) covers a narrower, concrete verification and implementation slice within this audit's Reduce Transparency coverage. Keep #26 as a separate issue for the explicit opaque fallback across all glass/material surfaces and transition/relaunch verification; use this issue as the broader audit and remediation authority.
kayg commented 2026-08-22 07:57:16 +00:00
Author
Owner
Copy link

Cross-reference from #26: the existing v0.0.1 glass/material surfaces were verified with Reduce Transparency enabled, and the system fallback is sufficient (screenshot: https://img.kayg.org/u/0cLKx5.png). When future glass surfaces are added—especially the search panel—verify the live Reduce Transparency toggle and relaunch behavior on the real app as part of this accessibility audit.

Cross-reference from #26: the existing v0.0.1 glass/material surfaces were verified with Reduce Transparency enabled, and the system fallback is sufficient (screenshot: https://img.kayg.org/u/0cLKx5.png). When future glass surfaces are added—especially the search panel—verify the live Reduce Transparency toggle and relaunch behavior on the real app as part of this accessibility audit.
kayg commented 2026-08-23 09:33:05 +00:00
Author
Owner
Copy link

Verified sidebar row accessibility finding: rows are now native Buttons carrying the accessible label and identifier. On macOS, an AXRow is an NSAccessibilityGroup and does not carry the title; the correct expectation is an unlabelled AXRow containing a labelled AXButton. Do not use accessibilityElement(children: .ignore), because it actively hides child elements.

Verified sidebar row accessibility finding: rows are now native `Button`s carrying the accessible label and identifier. On macOS, an `AXRow` is an `NSAccessibilityGroup` and does not carry the title; the correct expectation is an unlabelled `AXRow` containing a labelled `AXButton`. Do not use `accessibilityElement(children: .ignore)`, because it actively hides child elements.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
dev
feat/sidebar-selection-archive-purge
v0.0.4
v0.0.3
v0.0.2
v0.0.1
Labels
Clear labels   
delivered
Shipped and recorded in project history

  
outstanding
Not yet delivered or blocked

No labels
delivered
outstanding
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
kayg/hermternal-apple#13
No description provided.