Files
HashTool/ACCESSIBILITY.md
poli0981andClaude Opus 5.5 6c4cd062cc fix(app): accessibility of hashes, paths, results and shortcuts
The fixable known limitations of ACCESSIBILITY.md:
- Hashes, file names and paths keep left-to-right order in right-to-left languages (FlowDirection on each control,
  not on the rows, so buttons keep their mirrored order).
- Verify shows the computed hash of a mismatched file under the expected one, in a read-only box that is focusable and
  named "Computed hash"; it used to be only in the status tooltip, which bypassed hash masking (now masked too). The
  expected-hash box is named "Expected hash" instead of its placeholder.
- A run of one file ends with its result in a live text at the top of the page ("photo.jpg: VALID"), which screen
  readers announce; several files still end with the summary dialog.
- Shortcut tooltips use the platform's notation (⌘O on macOS) and the buttons and search box expose them as
  AcceleratorKey.

ACCESSIBILITY.md is reviewed for 1.3.0: the maintainer's keyboard-only and Narrator test, the email address for people
who cannot use GitHub, the remaining limitations, and two new rules for contributors. New strings: Lbl_ExpectedHash,
Lbl_ComputedHash, Msg_RowResult.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:17:31 +07:00

189 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Accessibility
**Last reviewed: November 2026 (Hash Tool 1.3.0)**
Hash Tool should work for everyone who needs to check a file: with a keyboard alone, with a screen reader, with large
text or high contrast, and in their own language. This page describes what works today, what does not work yet, and how
to report a problem.
## Goals
The target is [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA, where it applies to a desktop app (see
[WCAG2ICT](https://www.w3.org/TR/wcag2ict-22/) for how the guidelines map to non-web software) and where Avalonia, the UI
framework, makes it possible. This is a goal, not a claim of conformance: no formal audit has been done.
Priorities, in this order:
1. Every feature works with the keyboard.
2. Screen readers announce a sensible name and role for every control.
3. Text is readable: contrast, text size and themes.
4. The app speaks the user's language, including right-to-left languages.
5. The `hashtool` command-line tool works in any terminal and with screen readers.
## What works today
### Desktop app
**Keyboard.** Tab and Shift+Tab move between controls, the arrow keys move between rows of a file list, and Enter or
Space activates the focused control. In a file row, Tab moves through that row's controls (algorithm, hash, copy, save,
run, clear, remove) and then leaves the list. When a run starts, focus moves from **COMPUTE ALL** / **VERIFY ALL** to
**Cancel**, and back when it ends. On **Hash Text**, Enter starts a new line in the text box and Tab moves on to the
options and to each algorithm's hash and copy button.
| Keys | Action |
|---|---|
| Ctrl+O (⌘+O on macOS) | Add files |
| Ctrl+Shift+O (⌘+Shift+O) | Add a folder |
| Ctrl+F (⌘+F) | Go to the search box |
| Ctrl+Enter (⌘+Enter) | Compute or verify all |
| Esc | Cancel the run; close a dialog |
| Delete | Remove the selected row |
| Enter, in a dialog | The highlighted button (OK, Yes) |
Tooltips show a button's shortcut in your platform's notation (⌘O on macOS), and screen readers announce it with the
button.
**Screen readers.** Every button, box, list and row has a translated name: icon buttons are named after their action
("Copy Hash", "Remove File") and rows after their file name. Page titles and section titles are headings, and the
navigation pane and the page are landmarks, so you can jump between them. The update and notice banners and the status
on the Update page are announced when they change. After a run of one file, its result (for example "photo.jpg: VALID")
is announced and shown at the top of the page; after a run with several files, a summary dialog opens and takes the
focus. When a file does not match, Verify shows the hash it really has under the expected one, in a box you can focus
and copy.
**Results in words, not only colour.** Every status is text: **VALID**, **MISMATCH!**, *Access denied*, *Timed out* and
so on. Search matches are shown in bold as well as in colour.
**Seeing.** You can choose light, dark or the system setting, and eight styles including **High Contrast** and
**Colour-blind** (Okabe–Ito colours). In every style, status text has a contrast of at least 4.5:1 and status icons at
least 3:1; automated tests check this. Settings has the font, a font size from 10 to 32, and a UI scale from 0.8× to
2.5× that also applies to dialogs.
**No mouse or drag and drop needed.** Everything you can drop has a button too: **Add Files…**, **Add Folder…**,
**Open Checksum File…**, and **Browse** for the expected hash of a row. You can also paste the expected hash.
**Language.** The app comes in 67 languages, with right-to-left layouts for Arabic, Persian, Hebrew, Dhivehi and Pashto,
in which hashes, file names and paths keep their left-to-right order. It picks your system language automatically.
**Motion and sound.** The only animation is a 0.3-second colour fade when the theme changes. The app makes no sounds,
and nothing flashes.
### Command-line tool
- Plain text: one line per file, with no colours, spinners or progress bars that redraw the line.
- Exit codes: `0` everything OK, `1` a file failed or did not match, `2` usage error.
- Output for other programs: `hashtool hash -f json` or `-f csv`.
- `hashtool verify -q` prints only the problems.
- Errors go to standard error, in the usual `hashtool: <file>: <reason>` form.
- `hashtool <command> --help` explains each command. [docs/USAGE.md](docs/USAGE.md) lists every option.
## Supported environments
| Platform | Assistive technology | Status |
|---|---|---|
| Windows 10 and 11 | Keyboard only (mouse turned off), Narrator | Tested by the maintainer on Windows 11 with Hash Tool 1.2.3 (November 2026); no problems found. The 1.3.0 changes were checked with automated tests and with the UI Automation tree that screen readers read. |
| Windows 10 and 11 | NVDA, JAWS | Expected to work, since they read the same UI Automation tree as Narrator. Not tested regularly; reports are welcome. |
| macOS (Apple silicon and Intel) | VoiceOver | Not tested yet. Avalonia exposes the app to macOS accessibility. |
| Linux (x64 AppImage) | Orca | Not tested yet. Avalonia's AT-SPI support is newer and may be incomplete. |
| Any | Terminal with a screen reader or braille display | The command-line tool prints plain text. |
## Known limitations
These are known problems, with a workaround where one exists. Please report anything else.
- **Progress is not read aloud during a run.** Each row shows its status as text, the result of a run of one file is
announced, and a run with several files ends with a summary dialog.
- **The app does not follow the system's contrast themes** (Windows contrast themes, macOS *Increase contrast*). Choose
*Settings → Theme style → High Contrast*. Standard controls such as buttons and the focus rectangle keep the colours
of the Fluent theme.
- **The app does not follow the system text size.** Use *Font size* and *UI scale* in Settings.
- **There is no "reduce motion" setting.** The only animation is the theme colour fade.
- **The Developer console uses fixed colours** (light text on a dark background) in every theme.
- **The Glassmorphism style and the translucent window background** (Windows and macOS) depend on what is behind the
window. Pick another style if text is hard to read.
- **Tooltips appear on mouse hover only.** What they show is also on screen or announced: a button's shortcut, a file's
folder, and on Verify the computed hash of a file that does not match.
- **Dialogs cannot be moved with the keyboard.** They open centred over the main window.
- **Most translations were made with AI assistance**, including the names screen readers announce. Corrections from
native speakers are welcome.
- **The command-line tool is in English only.**
- **VoiceOver and Orca have not been tested.**
## Reporting an accessibility problem
Open an issue with the
[Accessibility issue form](https://github.com/poli0981/HashTool/issues/new?template=accessibility.yml). If the form is
hard to use, a plain issue or a post in [Discussions](https://github.com/poli0981/HashTool/discussions) is fine too. If
you cannot use GitHub, email [accessibility@poli0981.dev](mailto:accessibility@poli0981.dev).
Helpful details:
- what you were trying to do, what you expected and what happened;
- the assistive technology and its version (for example NVDA 2026.3, or "keyboard only");
- your operating system and the Hash Tool version (shown on the About page);
- the steps to get there. A screenshot or recording helps but is optional.
You do not need to tell me about any disability. Security problems go through [SECURITY.md](SECURITY.md) instead.
### Severity
| Severity | Meaning | Example |
|---|---|---|
| Critical | You cannot generate or verify a hash at all. | A screen reader cannot reach **COMPUTE ALL**. |
| High | A task works only with a workaround or with great effort. | A setting can only be changed with the mouse. |
| Medium | Annoying or inconsistent, but you can get it done. | A button is announced with the wrong name. |
| Low | Minor or cosmetic. | A heading level is off. |
### What happens next
Hash Tool is maintained by one person, so there is no fixed response time. I read every report and reply as soon as I
can. Critical and High problems come before new features; if a fix takes a while, I will suggest a workaround. Fixes are
listed in [CHANGELOG.md](CHANGELOG.md) and the release notes, with credit if you would like it. If you are willing, I may
ask you to try a fix before it is released.
## For contributors
When you change the UI:
- Give every control that takes focus a translated name: `AutomationProperties.Name="{Binding Localization[Key]}"`.
This matters for icon buttons and for buttons whose content is a panel, which Avalonia otherwise announces by the
panel's type name ("Avalonia.Controls.StackPanel").
- Make new controls reachable with Tab and usable with Enter, Space and the arrow keys. A control that hides itself
while focused hands the focus on with `controls:FocusHandOff.Target`; lists with controls in their rows use
`controls:RowTabNavigation.IsEnabled`.
- Never use colour as the only signal. New colours in `ThemePalettes` keep 4.5:1 for text and 3:1 for icons.
- Hashes, file names and paths get `FlowDirection="LeftToRight"`, so right-to-left languages do not reorder them.
- Shortcut texts come from `controls:Shortcuts` (tooltip and `AutomationProperties.AcceleratorKey`), never a literal
"Ctrl+…".
- Page titles use `AutomationProperties.HeadingLevel="1"`; section titles use the `sectionTitle` class.
- Add new text to every language with `python -I eng/loc.py set` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
Testing:
- **Automated:** `tests/HashTool.App.Tests/AccessibilityTests.cs` checks names on every page in two languages, headings,
Tab inside file rows, focus when buttons swap, left-to-right hashes and paths in Arabic, the computed hash and the
announced result of a mismatch, shortcut notation, and the contrast of every theme. CI runs it on Windows, macOS and
Linux.
- **By hand, for UI changes:** one pass with the keyboard only, a quick check with a screen reader (Narrator:
Win+Ctrl+Enter; VoiceOver: ⌘+F5; Orca on Linux), UI scale 2.0, and the High Contrast style.
[Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/) shows what screen
readers see.
## Ownership and review
The maintainer, [poli0981](https://github.com/poli0981), is responsible for accessibility: triaging reports, keeping
this page up to date, and checking new releases. This statement is reviewed with every minor release and whenever a
report changes it.
## Feedback
Suggestions about this statement or these practices are welcome as an issue or a pull request. If something blocks you
right now, use [Reporting an accessibility problem](#reporting-an-accessibility-problem).
This statement follows the
[Open Source Accessibility Toolkit template](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md)
and the [accessibility best practices](https://opensource.guide/accessibility-best-practices-for-your-project/) of Open
Source Guides.
© 2026 poli0981. All rights reserved.