From 024b08459c944f2f2b748b5a1a709cb8e0eecd20 Mon Sep 17 00:00:00 2001 From: phg Date: Tue, 8 Sep 2026 11:20:30 +0200 Subject: [PATCH] Document TUI accessibility audit --- README.md | 4 ++++ docs/accessibility.md | 52 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/accessibility.md diff --git a/README.md b/README.md index 31272ea..9bd183e 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ on macOS and Linux. The application starts in Read-only Mode. Default Entries cannot be edited, deleted, activated, deactivated, or moved. +See [Accessibility and terminal compatibility](docs/accessibility.md) for the +supported keyboard and terminal baseline, plus known assistive-technology +limitations. + ## Requirements - macOS or Linux with `/etc/hosts` and `sudo` diff --git a/docs/accessibility.md b/docs/accessibility.md new file mode 100644 index 0000000..05d60e6 --- /dev/null +++ b/docs/accessibility.md @@ -0,0 +1,52 @@ +# Accessibility and terminal compatibility + +`hosts` is a keyboard-first terminal application. This document states the +accessibility support available in the current application and records the +source-and-harness audit completed for issue #10. It describes the current +release, not planned behavior. + +## Supported baseline + +The supported baseline is a common 256-color terminal at 100 columns by 30 +rows or larger. The design target is 120 columns by 40 rows. At a smaller size, +the application replaces its workspace with an explicit minimum-size screen. +Host Entry mutations are unavailable until the terminal is resized. + +Every workflow is intended to be operable by keyboard. The table uses standard +table navigation keys; forms use Tab and Shift+Tab; radio groups use arrow +keys; and Escape cancels a modal or backs out of the Entry Editor without +immediately mutating the Hosts File. Mouse input may work where the terminal +framework supplies it, but no task requires it. + +Color, italic text, and symbols reinforce state rather than define it. For +example, the table spells out `Active`, `Inactive`, `Default`, `Resolved`, and +`Failed`; the footer spells out `READ-ONLY` or `PRIVILEGED`; and status messages +state their result in words. The application supports degraded-color and +monochrome use to that extent, although appearance and focus contrast depend on +the terminal emulator. + +The application does not currently claim screen-reader support or reliable +announcement of changing status text. Screen-reader behavior is determined by +the terminal emulator, operating system, and Textual runtime, and no +screen-reader compatibility matrix or automated announcement test exists. + +## Focus and keyboard audit + +This audit covers the table, the Entry Editor within the main screen, and every +`ModalScreen` in `src/hosts/tui/`. + +| Surface | Initial focus and keyboard path | Audit result | +| --- | --- | --- | +| Main table | The table receives focus when entries load or selection is restored. Up/Down, Home/End, and Page Up/Page Down move its cursor; the details pane updates with the selected Host Entry. | Keyboard path and state wording are present. Initial focus is contingent on at least one visible entry. | +| Search and Entry Editor | The Search field accepts immediate filtering. The Entry Editor uses Tab/Shift+Tab and Escape; its visible field order follows its layout. | Labels are visually persistent through section titles; validation and focus order need broader harness coverage. | +| Add Host Entry | New entries start at Entry Type; entries based on a selection start at Hostnames. Tab follows the composed form, and changing entry type moves focus to Hostnames. Escape cancels and Ctrl+S saves. | Keyboard path is present; opener-focus restoration and full order coverage are not yet guaranteed. | +| Advanced Filtering | Starts at Presets. A custom Tab/Shift+Tab order follows visible sections and excludes hidden custom controls. Escape cancels. | Strongest modal coverage exists, but restoration to the opener is not tested. | +| Configuration | Checkbox, Cancel, then Save appear in visual order. Escape cancels and Enter saves. | No explicit initial focus target is set; focus therefore relies on framework defaults. | +| Delete Host Entry | Cancel is explicitly focused first; Escape cancels. The destructive action names the Host Entry. | Safe initial focus is present; restoration to the opener is not tested. | +| Save Changes | Cancel is explicitly focused first; Escape cancels. Save and Discard are distinct labeled actions. | Safe initial focus is present; restoration to the opener is not tested. | +| Restore Pre-edit Backup | Cancel is explicitly focused first. Escape cancels; r, f, [, ], arrows, paging, Home, and End navigate the review. | Safe initial focus and textual review status are present; restoration to the opener is not tested. | +| Keyboard help | Close is focused first; ? and Escape close the overlay. The application has a harness test that focus returns to the opener. | Focus restoration is covered; the overlay is not yet a complete reference for all bindings. | + +The sudo authentication notice is a separate foreground terminal handoff, not a +Textual modal. It gives a text-only fallback and explicitly describes Ctrl+C as +the cancellation path. -- 2.51.2