Accessibility pass with a screen reader #14

New issue

Open

opened 2026-08-19 23:56:56 +00:00 by dusan · 0 comments

dusan commented

2026-08-19 23:56:56 +00:00

Owner

Context

Nothing in this project has been checked with a screen reader, and the test
harness actively disables accessibility: build-aux/smoke.sh exports
GTK_A11Y=none, because a private D-Bus session has no accessibility bus and GTK
warns about it, which G_DEBUG=fatal-warnings turns into an abort.

So the current state is unknown rather than known-bad. What exists:

the sidebar is adw::Sidebar with adw::SidebarItems carrying a title,
subtitle, icon name and a suffix widget (rebuild_sidebar in
crates/terminalko/src/window.rs);
the state dot and bell marker are GtkBox and GtkImage built in
crates/terminalko/src/accent.rs, and the bell has a tooltip but nothing else;
dialogs are AdwPreferencesDialog and AdwAlertDialog, which are labelled by
their own rows and headings;
the terminal itself is VTE, whose accessibility is VTE's business.

What to do

Read what is there with a screen reader (Orca) and write down what it says for:
the sidebar rows, the state dot, the bell marker, the tab overview, the session
editor and the preferences dialog.
Fix what is wordless. The likely findings, from reading the code:
- the state dot conveys running/stopped by colour alone — it needs an
  accessible label, and arguably the row's subtitle should say it too;
- the bell marker likewise — a tooltip is not an accessible name;
- the accent colour conveys grouping by colour alone, which is a
  colour-only signal by design; the folder name carries the same information,
  so this may be acceptable — record the reasoning either way;
- suffix widgets built in code have no accessible-role or label set anywhere;
  gtk::Accessible properties (update_property, update_relation) are how
  to set them.
Decide what the smoke test should do about GTK_A11Y=none. Turning it on
requires an accessibility bus in the test session; if that is impractical, say
so in the script's comment rather than leaving it looking incidental.

Acceptance criteria

A written pass in docs/spec/accessibility.md: what was tested, with what, what
it said, and what changed.
No information conveyed by colour or shape alone without a text equivalent,
except where the reasoning for an exception is written down.
Keyboard reachability confirmed for everything in the sidebar and both dialogs —
every action already has an accelerator or a menu item, so this is a check
rather than a redesign.
./build-aux/ci.sh and ./build-aux/smoke.sh still pass.

Notes

https://docs.gtk.org/gtk4/iface.Accessible.html
https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/
This is the kind of work that is easy to postpone indefinitely and cheap to do
early, while there are four dialogs rather than twenty.

## Context Nothing in this project has been checked with a screen reader, and the test harness actively disables accessibility: `build-aux/smoke.sh` exports `GTK_A11Y=none`, because a private D-Bus session has no accessibility bus and GTK warns about it, which `G_DEBUG=fatal-warnings` turns into an abort. So the current state is unknown rather than known-bad. What exists: * the sidebar is `adw::Sidebar` with `adw::SidebarItem`s carrying a title, subtitle, icon name and a suffix widget (`rebuild_sidebar` in `crates/terminalko/src/window.rs`); * the state dot and bell marker are `GtkBox` and `GtkImage` built in `crates/terminalko/src/accent.rs`, and the bell has a tooltip but nothing else; * dialogs are `AdwPreferencesDialog` and `AdwAlertDialog`, which are labelled by their own rows and headings; * the terminal itself is VTE, whose accessibility is VTE's business. ## What to do 1. Read what is there with a screen reader (Orca) and write down what it says for: the sidebar rows, the state dot, the bell marker, the tab overview, the session editor and the preferences dialog. 2. Fix what is wordless. The likely findings, from reading the code: * **the state dot conveys running/stopped by colour alone** — it needs an accessible label, and arguably the row's subtitle should say it too; * **the bell marker likewise** — a tooltip is not an accessible name; * **the accent colour conveys grouping by colour alone**, which is a colour-only signal by design; the folder name carries the same information, so this may be acceptable — record the reasoning either way; * suffix widgets built in code have no `accessible-role` or label set anywhere; `gtk::Accessible` properties (`update_property`, `update_relation`) are how to set them. 3. Decide what the smoke test should do about `GTK_A11Y=none`. Turning it on requires an accessibility bus in the test session; if that is impractical, say so in the script's comment rather than leaving it looking incidental. ## Acceptance criteria - A written pass in `docs/spec/accessibility.md`: what was tested, with what, what it said, and what changed. - No information conveyed by colour or shape alone without a text equivalent, except where the reasoning for an exception is written down. - Keyboard reachability confirmed for everything in the sidebar and both dialogs — every action already has an accelerator or a menu item, so this is a check rather than a redesign. - `./build-aux/ci.sh` and `./build-aux/smoke.sh` still pass. ## Notes - <https://docs.gtk.org/gtk4/iface.Accessible.html> - <https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/> - This is the kind of work that is easy to postpone indefinitely and cheap to do early, while there are four dialogs rather than twenty.

No labels

No milestone

No project

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

dusan/terminalko#14

No description provided.

Rows
Columns