LotusGuild/cinny
3
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

[QA] §P Accessibility runtime pass: keyboard golden path, ? dialog, screen-reader reading + live announcements, focus return, axe/Lighthouse #185

New Issue
Open
opened 2026-09-17 23:24:09 -04:00 by jared · 3 comments
jared commented 2026-09-17 23:24:09 -04:00
Owner
Copy Link
Copy Source

Migrated from LOTUS_TESTING.md §P on 2026-09-17 — the file is now reference-only.

How to report: tick each item as it passes; on FAIL comment with what you saw vs expected, browser/OS, web (chat.lotusguild.org) vs desktop (Tauri), theme, and any browser-console errors. Screenshots for anything visual.

Checklist

  • P1. Keyboard-only golden path (no mouse)
  • P2. ? shortcuts dialog
  • P3. Screen-reader: reading messages
  • P4. Screen-reader: live announcements
  • P5. Focus return from dialogs
  • P6. axe / Lighthouse scan

The compliance fixes are gate-verified in code; these confirm the runtime a11y behavior only a human + AT can check. Tools: browser DevTools "axe" extension / Lighthouse a11y, plus VoiceOver (macOS ⌘F5) or NVDA (Windows).

P1. Keyboard-only golden path (no mouse)

Tab from page load: skip-to-content link appears first (Enter jumps to the timeline). Tab reaches the room list (rooms are focusable, active room announced), open a room (Enter), type a character → focus lands in the composer, send with Enter (or Shift+Enter per your enterForNewline setting). No keyboard trap; visible focus ring throughout.

P2. ? shortcuts dialog

Press ? (Shift+/) with focus NOT in a text field → the keyboard-shortcuts dialog opens, is focus-trapped, Escape closes it and focus returns to where you were. Pressing ? while typing in the composer/search inserts a literal ? (does NOT open the dialog).

P3. Screen-reader: reading messages

With VoiceOver/NVDA on, arrow through the timeline: each message is announced as an article with sender name + time — critically, this includes collapsed messages (consecutive messages from the same person), which previously announced only the body with no sender. Reactions, "edited", replies, and delivery status are announced with labels.

P4. Screen-reader: live announcements

  • New message arrives while you're reading → announced (polite).
  • Someone starts typing → "X is typing" announced once (not spammed per keystroke).
  • Editing a message → the edit box announces "Editing message from X".

P5. Focus return from dialogs

Open then close (Escape or ×): the room topic viewer, a reaction viewer (click a reaction count), and Search → focus returns to the button/element you opened them from (not lost to <body>). Inline popouts (emoji picker, autocomplete, hover menus) intentionally keep focus in context — that's expected, not a bug.

P6. axe / Lighthouse scan

Run the axe DevTools extension (or Lighthouse → Accessibility) on a room view, Settings, and the login screen. Expect no critical/serious "missing accessible name" or "ARIA" violations on the golden path. Report any that appear (note: far-scrolled timeline history being virtualized out is a known, accepted limitation — not a finding).

_Migrated from `LOTUS_TESTING.md` §P on 2026-09-17 — the file is now reference-only._ **How to report:** tick each item as it passes; on FAIL comment with what you saw vs expected, browser/OS, web (chat.lotusguild.org) vs desktop (Tauri), theme, and any browser-console errors. Screenshots for anything visual. **Checklist** - [x] P1. Keyboard-only golden path (no mouse) - [x] P2. `?` shortcuts dialog - [ ] P3. Screen-reader: reading messages - [ ] P4. Screen-reader: live announcements - [x] P5. Focus return from dialogs - [ ] P6. axe / Lighthouse scan --- The compliance fixes are gate-verified in code; these confirm the runtime a11y behavior only a human + AT can check. Tools: browser DevTools "axe" extension / Lighthouse a11y, plus **VoiceOver** (macOS ⌘F5) or **NVDA** (Windows). ### P1. Keyboard-only golden path (no mouse) Tab from page load: **skip-to-content** link appears first (Enter jumps to the timeline). Tab reaches the room list (rooms are focusable, active room announced), open a room (Enter), type a character → focus lands in the composer, send with Enter (or Shift+Enter per your `enterForNewline` setting). No keyboard trap; visible focus ring throughout. ### P2. `?` shortcuts dialog Press **?** (Shift+/) with focus NOT in a text field → the keyboard-shortcuts dialog opens, is focus-trapped, Escape closes it and focus returns to where you were. Pressing `?` while typing in the composer/search inserts a literal `?` (does NOT open the dialog). ### P3. Screen-reader: reading messages With VoiceOver/NVDA on, arrow through the timeline: each message is announced as an article with **sender name + time** — critically, this includes **collapsed messages** (consecutive messages from the same person), which previously announced only the body with no sender. Reactions, "edited", replies, and delivery status are announced with labels. ### P4. Screen-reader: live announcements - **New message** arrives while you're reading → announced (polite). - **Someone starts typing** → "X is typing" announced once (not spammed per keystroke). - **Editing a message** → the edit box announces "Editing message from X". ### P5. Focus return from dialogs Open then close (Escape or ×): the **room topic viewer**, a **reaction viewer** (click a reaction count), and **Search** → focus returns to the button/element you opened them from (not lost to `<body>`). Inline popouts (emoji picker, autocomplete, hover menus) intentionally keep focus in context — that's expected, not a bug. ### P6. axe / Lighthouse scan Run the axe DevTools extension (or Lighthouse → Accessibility) on a room view, Settings, and the login screen. Expect **no critical/serious** "missing accessible name" or "ARIA" violations on the golden path. Report any that appear (note: far-scrolled timeline history being virtualized out is a known, accepted limitation — not a finding). ---
jared added this to the Manual QA backlog milestone 2026-09-17 23:24:09 -04:00
jared added the a11yqa labels 2026-09-17 23:24:09 -04:00
jared commented 2026-09-18 19:22:09 -04:00
Author
Owner
Copy Link
Copy Source

Ran axe-core 4.10 (wcag2a/aa, wcag21a/aa, best-practice) over the main surfaces on the local dev homeserver, then fixed what was cheap and systemic:

surface before (critical / serious) after
Login page 0 / 1 0 / 1
Room timeline + composer + members 21 / 5 3 / 5
User Settings (General) 54 / 3 3 / 3
Room Settings 25 / 5 4 / 5
Thread panel open 26 / 15 3 / 15

Fixed (e9d419f8, 2e8244dc) — button-name criticals: every icon-only sidebar avatar button (space tabs, Home, Direct, Inbox, Search, Saved Messages, Explore, Add Space, User Settings, Unverified) and each message's sender avatar button had no accessible name; and every settings switch was an unlabeled role=switch. Sidebar buttons now carry their tooltip text as aria-label, message avatars read ", open profile", and SettingTile points its switch/select at the tile title via aria-labelledby.

Left as documented findings:

  • aria-allowed-attr ×3: NavItem (a div) carries aria-selected — upstream Cinny pattern used in ~20 places (room list, inbox tabs, explore, permissions); proper fix is role="option"/tab on the container or a data-selected attribute for the CSS hook. Screen readers ignore the attribute, so low impact.
  • color-contrast: composer placeholder "Send a message…" 2.3:1 (#a1a1a1 on #f2f2f2, light theme); space-tab initials 3.6:1 on the teal avatar; sender name colour 4.46:1. The #797979 description-text hits are axe misreading a layered background.
  • label ×1: the voice-limit number input in Room Settings (name="limitInput") has no label.
  • region/landmark moderates: the app has no <main> landmark; content outside landmarks (121 nodes in settings). Cosmetic for AT users, one <main> wrapper in the client layout would clear most of it.

P1 keyboard golden path, P3/P4 screen-reader reading and live announcements, P5 focus return: still need a real screen reader (VoiceOver/NVDA) — leaving those to you. P2: ? opens the shortcuts dialog ✓.

Ran **axe-core 4.10** (wcag2a/aa, wcag21a/aa, best-practice) over the main surfaces on the local dev homeserver, then fixed what was cheap and systemic: | surface | before (critical / serious) | after | |---|---|---| | Login page | 0 / 1 | 0 / 1 | | Room timeline + composer + members | **21** / 5 | 3 / 5 | | User Settings (General) | **54** / 3 | 3 / 3 | | Room Settings | **25** / 5 | 4 / 5 | | Thread panel open | **26** / 15 | 3 / 15 | **Fixed (`e9d419f8`, `2e8244dc`)** — `button-name` criticals: every icon-only sidebar avatar button (space tabs, Home, Direct, Inbox, Search, Saved Messages, Explore, Add Space, User Settings, Unverified) and each message's sender avatar button had no accessible name; and **every settings switch** was an unlabeled `role=switch`. Sidebar buttons now carry their tooltip text as `aria-label`, message avatars read "<name>, open profile", and `SettingTile` points its switch/select at the tile title via `aria-labelledby`. **Left as documented findings:** - `aria-allowed-attr` ×3: `NavItem` (a `div`) carries `aria-selected` — upstream Cinny pattern used in ~20 places (room list, inbox tabs, explore, permissions); proper fix is `role="option"`/`tab` on the container or a `data-selected` attribute for the CSS hook. Screen readers ignore the attribute, so low impact. - `color-contrast`: composer placeholder "Send a message…" 2.3:1 (#a1a1a1 on #f2f2f2, light theme); space-tab initials 3.6:1 on the teal avatar; sender name colour 4.46:1. The `#797979` description-text hits are axe misreading a layered background. - `label` ×1: the voice-limit number input in Room Settings (`name="limitInput"`) has no label. - `region`/`landmark` moderates: the app has no `<main>` landmark; content outside landmarks (121 nodes in settings). Cosmetic for AT users, one `<main>` wrapper in the client layout would clear most of it. P1 keyboard golden path, P3/P4 screen-reader reading and live announcements, P5 focus return: still need a real screen reader (VoiceOver/NVDA) — leaving those to you. P2: `?` opens the shortcuts dialog ✓.
jared commented 2026-09-24 12:15:06 -04:00
Author
Owner
Copy Link
Copy Source

Keyboard-only pass (2026-09-24, Playwright; screen-reader speech still needs NVDA/VoiceOver):

P1: ✅ after a fix. The first Tab reaches "Skip to main content", but Enter left focus on <body>, because the <main> target wasn't focusable (and the URL got a stray #main-content). Fixed: <main tabIndex=-1>, and the link focuses it. After that the path works: Tab reaches the room list (15 Tabs to the first room on Home), Enter opens it, typing lands in the composer, Enter sends (confirmed on the server), and the focus ring is visible (3px outline).

P2: ✅ after a fix. ? opened "Keyboard Shortcuts", but the dialog had no role and focus stayed in the timeline, so it wasn't announced. Now role="dialog" aria-modal, with focus moved inside. Escape closes it and returns focus to the same element. ? typed in the composer stays text.

P5: ✅ after a fix.

  • Room topic viewer: focus returns to the topic button.
  • Search dialog (sidebar): focus goes into it, and Escape returns focus to the Search button.
  • Reaction viewer: opened (Menu key / right-click on a reaction) without a role and with focus left behind. Fixed in both entry points (role="dialog", label "Reactions", focus moves in). Escape returns focus to the reaction.
  • Note: Enter/click on a reaction toggles your reaction by design. The viewer is on the context menu, or "View Reactions" in the message menu.

Broader note: 128 focus traps in the app use initialFocus: false (an upstream Cinny pattern), so other modals may open without moving focus in. I've fixed the three this checklist names; the pattern is worth an audit.

P3/P4 need a real screen reader. P6: the axe gate from #222 runs in CI.

Keyboard-only pass (2026-09-24, Playwright; screen-reader *speech* still needs NVDA/VoiceOver): **P1: ✅ after a fix.** The first Tab reaches "Skip to main content", but **Enter left focus on `<body>`**, because the `<main>` target wasn't focusable (and the URL got a stray `#main-content`). Fixed: `<main tabIndex=-1>`, and the link focuses it. After that the path works: Tab reaches the room list (15 Tabs to the first room on Home), Enter opens it, typing lands in the composer, Enter sends (confirmed on the server), and the focus ring is visible (3px outline). **P2: ✅ after a fix.** `?` opened "Keyboard Shortcuts", but the dialog had **no role and focus stayed in the timeline**, so it wasn't announced. Now `role="dialog" aria-modal`, with focus moved inside. Escape closes it and returns focus to the same element. `?` typed in the composer stays text. **P5: ✅ after a fix.** - Room topic viewer: focus returns to the topic button. - Search dialog (sidebar): focus goes into it, and Escape returns focus to the Search button. - Reaction viewer: opened (Menu key / right-click on a reaction) **without a role and with focus left behind**. Fixed in both entry points (`role="dialog"`, label "Reactions", focus moves in). Escape returns focus to the reaction. - Note: Enter/click on a reaction *toggles* your reaction by design. The viewer is on the context menu, or "View Reactions" in the message menu. **Broader note:** 128 focus traps in the app use `initialFocus: false` (an upstream Cinny pattern), so other modals may open without moving focus in. I've fixed the three this checklist names; the pattern is worth an audit. P3/P4 need a real screen reader. P6: the axe gate from #222 runs in CI.
jared commented 2026-09-24 13:12:18 -04:00
Author
Owner
Copy Link
Copy Source

Modal audit done (ce8ed89f, and a follow-up commit for the headless ones). Most modals rendered a folds Dialog/Modal with no role and no name, and their focus traps used initialFocus: false. So focus stayed behind the modal, and a screen reader never announced it.

  • 36 dialogs with a visible heading now have role="dialog", aria-modal, aria-labelledby pointing at the heading, and tabIndex=-1. Examples: Leave Room/Space, Join with Address, Delete/Report Message, Logout, device verification, create space, room upgrade/encryption, jump to time, forward, remove avatar, the UIA stages.
  • 8 modals without a heading get an aria-label: the three "Seen by" lists, View source, the text/PDF file viewers, the room-card join error, and the user profile.
  • Focus traps now use focus-trap's default: it keeps an already-focused autoFocus field, otherwise it focuses the first tabbable element. The dialog is the fallbackFocus, so a dialog with nothing tabbable can't crash the trap.

Verified at runtime: Join with Address, Delete Message, Report Message, Leave Room, Logout and Seen by open as named dialogs with focus inside, and close on Escape. When a text field has focus, Tab comes first: the shared stopPropagation helper keeps Escape from discarding typed text, which is by design. The axe e2e spec passes (6/6), unit tests pass, and eslint is unchanged at 46.

Deliberately untouched: the file drag-and-drop overlay (not a dialog), startup/loading/error screens, and wrappers around the image viewer (which has its own role="dialog").

**Modal audit done (`ce8ed89f`, and a follow-up commit for the headless ones).** Most modals rendered a folds `Dialog`/`Modal` with no role and no name, and their focus traps used `initialFocus: false`. So focus stayed *behind* the modal, and a screen reader never announced it. - **36 dialogs** with a visible heading now have `role="dialog"`, `aria-modal`, `aria-labelledby` pointing at the heading, and `tabIndex=-1`. Examples: Leave Room/Space, Join with Address, Delete/Report Message, Logout, device verification, create space, room upgrade/encryption, jump to time, forward, remove avatar, the UIA stages. - **8 modals without a heading** get an `aria-label`: the three "Seen by" lists, View source, the text/PDF file viewers, the room-card join error, and the user profile. - **Focus traps** now use focus-trap's default: it keeps an already-focused autoFocus field, otherwise it focuses the first tabbable element. The dialog is the `fallbackFocus`, so a dialog with nothing tabbable can't crash the trap. Verified at runtime: Join with Address, Delete Message, Report Message, Leave Room, Logout and Seen by open as named dialogs with focus inside, and close on Escape. When a text field has focus, Tab comes first: the shared `stopPropagation` helper keeps Escape from discarding typed text, which is by design. The axe e2e spec passes (6/6), unit tests pass, and eslint is unchanged at 46. Deliberately untouched: the file drag-and-drop overlay (not a dialog), startup/loading/error screens, and wrappers around the image viewer (which has its own `role="dialog"`).
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
a11y
Accessibility: keyboard, screen reader, contrast, motion
 area: appearance
Client area: appearance
 area: auth-session
Client area: auth-session
 area: build-ci
Client area: build-ci
 area: calls
Client area: calls
 area: desktop
Client area: desktop
 area: media
Client area: media
 area: messaging
Client area: messaging
 area: mobile
Client area: mobile
 area: moderation
Client area: moderation
 area: navigation
Client area: navigation
 area: notifications
Client area: notifications
 area: settings
Client area: settings
 area: threads
Client area: threads
 bug
Something is not working
 dependencies
Third-party package versions and advisories
 docs
README / LOTUS_* docs wrong or missing
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 needs-human-review
performance
Re-render storms, leaks, heavy work on hot paths
 planning
priority: critical
Data loss, security hole, or crash on a main path
 priority: high
Broken feature or serious usability problem
 priority: low
Minor issue or polish
 priority: medium
Wrong behaviour in an edge case or notable degradation
 qa
Manual QA: shipped, needs a human in a real environment
 question
More information is needed
 research
security
XSS, unsafe URLs, data leaks, auth/session
 tech-debt
Code health, dead code, fragile patterns
 ux
Usability or visual inconsistency
 wontfix
This won't be fixed
No labels a11y qa
Milestone
No items
No Milestone Manual QA backlog
Projects
Clear projects
No projects
Assignees
Clear assignees
cole (Cole Keller) jared (Jared Vititoe) nathan (Nathan Vititoe)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: LotusGuild/cinny#185