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`

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.