docs: 1.5.0 — the changelog, the slice's record, and what running found

changelog/1.x.md gains 1.5.0, written by reader: keyboard, screen reader,
contrast theme, everyone. It says that Narrator was not run again on this
release and that zoom was built and held back.

ROADMAP records the slice: the decisions and why, and the defects that were in
code with green tests and were found by driving the installed build over
WebView2's debugging port — the high-contrast border that had never been
drawn, the buttons that dropped focus when they went busy, the legal gate, two
accessible names. U45, U47 and U48 close; A1-A7 open, each with what it is
waiting for, and A7 is the testing only a person can do.

ACCESSIBILITY.md, UI-SPEC and TESTING are corrected to what the build actually
does: no zoom, a double border, busy as aria-disabled. CLAUDE.md carries the
rules the slice left behind and the recipe that found the defects.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Fable 5.2 committed 2026-11-10 20:01:03 +07:00
1 parent 95e45d7acc
commit 2df161cb36
6 files changed
+237 -18

No files matched your search

+13 -7
View File
@@ -44,12 +44,11 @@ never removed.
| `←` `→` `Home` `End` | In Code Health: move between the tool tabs |
| `←` `→` `↑` `↓` | In a version conflict: move between *Keep compatible*, *Skip* and *Force latest*. Nothing is chosen until you press `Space` or `Enter` |
| `Esc` | Close a dialog, the palette or the console drawer; inside a package row, return to the row |
| `Ctrl` `+` / `Ctrl` `-` / `Ctrl+0` | Zoom in, zoom out, reset |
When the screen changes — a new tab, a plan's preview, its summary, the dependency view — focus
moves to the new screen's heading. When a dialog, the palette or the console drawer closes, focus
returns to what opened it. Every confirmation that removes, forces or rewrites something opens with
focus on **Cancel**.
returns to what opened it. A button that is busy after you press it stays where focus is. Every
confirmation that removes, forces or rewrites something opens with focus on **Cancel**.
The full map and the reasoning behind it are in [`docs/UI-SPEC.md`](docs/UI-SPEC.md) §8.
@@ -68,9 +67,12 @@ The full map and the reasoning behind it are in [`docs/UI-SPEC.md`](docs/UI-SPEC
Under a Windows contrast theme (forced colours), every colour in the interface is replaced by the
system's own. Because that removes every tint, the things a tint used to say are drawn another way:
destructive buttons get a heavier border, and the selected row, the selected search result and the
destructive buttons get a double border, and the selected row, the selected search result and the
current sidebar tab get an outline.
PipDock follows the Windows display scale (Settings → Display → Scale), which enlarges the whole
window. It has no zoom of its own yet — see the limitations below.
### Colour, contrast and motion
- Text and status chips are checked against their backgrounds for at least 4.5:1 by a test that
@@ -97,7 +99,7 @@ Honesty about this matters more than a long list.
| Structure: roles, names, required parts | [axe-core](https://github.com/dequelabs/axe-core) over every screen, on every change | Automated, from 1.5.0 |
| Keyboard behaviour and where focus goes | Unit tests, on every change | Automated |
| Text contrast | Computed from the design tokens, on every change | Automated |
| High contrast, zoom, the accessibility tree | In the running application, with forced colours emulated | During the 1.5.0 release |
| Where focus goes, what the accessibility tree exposes, forced colours | In the installed build, driven by real key presses over the webview's debugging port, with forced colours emulated | During the 1.5.0 release. It found defects no test had; all are fixed |
**Not tested, and said so rather than implied:**
@@ -135,8 +137,12 @@ where there is a workaround it is given.
picker fails, the screen does not change. Nothing is lost, but nothing tells you either.
- **Why a control is disabled is sometimes only in a tooltip**, which a keyboard cannot reach
because a disabled control cannot be focused.
- **Long paths and package names are cut off** rather than wrapped in a few places, which gets
worse with zoom.
- **No zoom inside the application.** It was built for 1.5.0 and held back: at 200 % in the
default window the package-name column collapsed to nothing and the last sidebar tabs were cut
off, which is worse than no zoom. *Workaround:* the Windows display scale enlarges everything
correctly.
- **Long paths and package names are cut off** rather than wrapped in a few places, most of all
in a narrow window.
- **Dates and sizes are not formatted for the interface language.**
- **`Ctrl+K` is matched by the letter the layout types**, unlike the digit shortcuts, so it moves
on a layout where K is elsewhere.
+36 -1
View File
@@ -1,7 +1,7 @@
# PipDock — working notes for Claude
Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19.
Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.4.0. M1, M2, Phase 3, Phase 4, the P1 wave, the Security tab and the dependency view are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette; 1.2.0 added the Security tab (PRD P1-1); 1.3.0 added the dependency view (P1-6), which is a *mode of the package screen* rather than a tab and adds no runtime dependency — read its ROADMAP record before touching `graph/`, because the shape of the screen is a consequence of measurements rather than of taste. 1.4.0 added no feature: it is the audit release — about 170 findings, every Critical and High fixed with a test that failed first, and the rest in ROADMAP's **Audit backlog**, with file:line and a reason each. Read that table before starting a slice; most of what is wrong with the codebase is already written down there. **What is left of Post-1.0 is one thing** — the scheduled check (P1-7) — and `docs/ROADMAP.md` now carries the survey of what blocks it, which for two versions it was cited for and did not contain: no toast component, no notification/autostart/tray plugin, nothing on a timer, and no surface that can report a background failure.
Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.5.0. M1, M2, Phase 3, Phase 4, the P1 wave, the Security tab and the dependency view are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette; 1.2.0 added the Security tab (PRD P1-1); 1.3.0 added the dependency view (P1-6), which is a *mode of the package screen* rather than a tab and adds no runtime dependency — read its ROADMAP record before touching `graph/`, because the shape of the screen is a consequence of measurements rather than of taste. 1.4.0 added no feature: it is the audit release — about 170 findings, every Critical and High fixed with a test that failed first, and the rest in ROADMAP's **Audit backlog**, with file:line and a reason each. Read that table before starting a slice; most of what is wrong with the codebase is already written down there. 1.5.0 added no feature either: it is the accessibility pass (backlog U45, U47, U48) — focus, names, keyboard patterns and high contrast, axe-core in the suite, and `ACCESSIBILITY.md`, which is a *record of what was tested* and has to be kept true like one. **What is left of Post-1.0 is one thing** — the scheduled check (P1-7) — and `docs/ROADMAP.md` now carries the survey of what blocks it, which for two versions it was cited for and did not contain: no toast component, no notification/autostart/tray plugin, nothing on a timer, and no surface that can report a background failure.
## Read the docs before changing anything
@@ -172,6 +172,41 @@ rule below backed by a test where a test can hold it:
could not fail. Write such files with the Write/Edit tools, then check the failing-first run
actually failed.
**1.5.0, the accessibility pass, left these behind** — the first found by reading, the rest by
driving the installed build:
- **jsdom is wrong about focus and blind to the cascade, and both cost a shipped defect.** A
browser takes focus from a control that becomes `disabled`; jsdom does not. So nine buttons that
disabled themselves when pressed dropped focus to `<body>` with every test green. **Busy is
`aria-disabled` plus a click guard; `disabled` is for unavailable.** And jsdom applies no
stylesheet: the forced-colors border on destructive buttons sat in `@layer base`, lost to
Tailwind's `border` utility in a later layer, and had never been drawn. **A rule that must beat
a utility goes outside every `@layer`**, and `destructive.test.ts` counts the braces.
- **The recipe that found them.** Install the bundle, launch with
`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<n>` and a scratch
`LOCALAPPDATA` (a release build honours it), and speak CDP to `http://127.0.0.1:<n>/json`:
`Input.dispatchKeyEvent` for real key presses (`Enter` needs a `char` event with `\r`),
`Runtime.evaluate` for `document.activeElement`, `Accessibility.getFullAXTree` for names, and
`Emulation.setEmulatedMedia` with `forced-colors: active`. No system setting changes. It cannot
hear a screen reader — say so wherever the result is written down. **A scratch profile still
discovers the owner's real interpreters**: select the scratch venv before starting any plan.
- **Anything that replaces what `<main>` shows without changing `nav` belongs in `App.tsx`'s
second focus effect.** There were four; the legal gate was a fifth, found after the first four
were fixed and tested. The effect acts only when focus was lost, so adding a dependency is safe.
- **A destructive button carries `data-destructive`**, whatever colour it is drawn in, and a test
reads the source for it. Do not add a `data-action` to a stylesheet list; there is no list.
- **An accessible name is assembled without spaces.** Inline spans join as `Updates(5)`; put a
literal `{' '}`. A browser *adds* one before visually-hidden text, so `: numpy` in an `sr-only`
span read "Remove packages : numpy" — use `aria-label` for a name with punctuation in it.
- **`ACCESSIBILITY.md` is hand-kept and says who tested what.** A change to keyboard, focus,
names or contrast is a change to it, the way a behaviour change is a change to `legal/`. It
currently says Narrator was not re-run on 1.5.0, and only a person can change that sentence.
- **`eslint-plugin-jsx-a11y` peers ESLint 9 at most**, like `react/jsx-no-literals`. axe-core is
called directly from `ui/src/test/axe.ts`; `color-contrast` is off there, and is
`tokens.test.ts`'s job.
- **Zoom is off on a measurement** (`zoomHotkeysEnabled`): at 200 % in the default window the
table's name column collapses to zero. Backlog A5 says what has to change first.
Three rules P1 left behind, all found by running rather than reading:
- **A venv is never externally managed**, and `sysconfig.get_path("stdlib")` inside one resolves to
+83
View File
@@ -3,6 +3,89 @@
Newest first. See [`README.md`](README.md) for the conventions, and `docs/ROADMAP.md` for what each
slice cost and what it taught — that is a different document for a different reader.
## 1.5.0 — 2026-11-10
**The accessibility release.** PipDock could already be driven from the keyboard and read by
Narrator from end to end — that was tested by hand on 1.4.0, and nothing blocked. This release fixes
the places where it worked but made you work for it, and writes down honestly what is and is not
supported. ([#107](https://github.com/poli0981/pipdock/pull/107))
### If you use the keyboard
- **Focus no longer disappears when the screen changes.** Starting an update, a run reaching its
summary, opening a package's dependencies or opening an environment each replaced the screen and
left focus on nothing, so the next `Tab` started again from the top of the window. Focus now
lands on the new screen's heading. Closing the console drawer returns it to the button that
opened the drawer.
- **Code Health's tabs are one tab stop**, moved through with `←` `→` `Home` `End`. They were three.
- **A version conflict's three choices are one tab stop**, moved through with the arrow keys.
Nothing is chosen until you press `Space` or `Enter` — an arrow key will never open *Force
latest*'s confirmation.
- **The command palette scrolls with its selection.** Past the ninth action the highlight used to
leave the visible list.
- **A button you have just pressed keeps focus while it works.** *Use*, *Rescan*, *Run*, *Run
audit*, *Add*, *Download the index* and *Stop* used to drop it the moment they went busy.
- **The focus ring on a package row is complete.** Three of its four sides were being cut off.
- The first-run screen puts focus on its heading rather than nowhere, and accepting it puts focus
on the first screen.
### If you use a screen reader
- **Dialogs say what they are asking.** A confirmation used to be announced by the package name
alone — "numpy, dialog", then "Cancel". It is now named by its heading and described by its text.
- **Search tells you what it is doing**: that it is searching, how many results came back, and when
nothing matched. Which result's details are showing is announced, not only coloured.
- **Code Health's tabs are named for what you see** — `deptry 3`, followed by what the tool checks —
so "click deptry" works with voice control too.
- **A pin's lock chip says what it means.** A held pin used to read as a bare version number; the
explanation was a mouse-only tooltip.
- **The package table is a well-formed grid**: every column has a header, the checkbox is in a cell,
and the table says more than one row can be selected.
- The console drawer's close button is called *Close console*. It was called *Cancel*, next to a
*Stop* button that cancels the run.
- Each sidebar tab exposes its `Ctrl+1`…`Ctrl+9` shortcut.
### If you use a Windows contrast theme
- **Every destructive button is marked, with a double border.** High contrast removes the red,
and a button that removes, forces or rewrites was then drawn exactly like the *Cancel* beside
it. A border was meant to mark them and, it turns out, had never actually been drawn.
- **The current sidebar tab is outlined.** It was indistinguishable from the rest.
### For everyone
- The sidebar's shortcut hints (`^1`…`^9`) are no longer drawn at half strength.
- The link to vulture's whitelist is underlined all the time, not only under the mouse.
- The remove button in Search's install list is large enough to hit.
### Added
- **[ACCESSIBILITY.md](../ACCESSIBILITY.md)** — what is supported, exactly what has been tested and
by whom, what has *not* been tested, the known limitations, and how to report a barrier. The
target is WCAG 2.2 AA; it is a target, not a claim of conformance.
- **An Accessibility section in About**, with a button that opens the statement and a new address,
`accessibility@poli0981.dev`, for anyone who would rather not use GitHub.
- **An accessibility issue form** that asks what got in your way, not what caused it.
- [CONTRIBUTING.md](../CONTRIBUTING.md) and a [Code of Conduct](../CODE_OF_CONDUCT.md), for anyone
who wants to help.
### Worth knowing
- **There is no zoom yet.** It was built for this release and held back, because at 200 % in the
default window the package names disappeared. The Windows display scale works as before.
- **Narrator has not been run again on this release.** The changes above were checked in the
running application against what it exposes to assistive technology, and by automated tests —
not by listening. If something sounds wrong, that is exactly the report the new address is for.
- The legal documents did not change, so the first-run screen does not reappear.
- Also in this build since 1.4.0: pip 26.3's new wording for an unloadable build backend is
recognised (it was reported under a neighbouring error code, with the same advice), and
dependencies are current.
### Verifying a download
As for 1.4.0: check the installer against `SHA256SUMS.txt`, or run
`gh attestation verify <file> --repo poli0981/pipdock`.
## 1.4.0 — 2026-10-17
**No new feature: everything PipDock already did, made to do what it said.** A review of the whole
+83 -3
View File
@@ -1402,9 +1402,14 @@ starting a slice**: several are cheaper inside a slice that touches the same fil
| U40 | `PdPins.tsx:138-139,202-209`; `stores/index.ts:466-472` | The empty state can show before the list has loaded; a reason edit commits on blur with no way to cancel; accepting a suggestion drops it even when the pin write failed | Small, and best done together |
| U41 | `stores/index.ts:526-538`; `PdPalette.tsx:96-103` | No in-flight guard: a double click takes two snapshots, and the palette can dispatch twice | Small |
| U44 | `PdEnvironments.tsx:186-196` | A `scan-progress` listener can outlive the screen | Small; with U19 |
| U45 | `styles.css:156-162` | `forced-colors` misses Remove, Force, rollback, Clear and the active tab | Needs a High Contrast pass, by hand |
| U47 | grids, tabs, radio groups, listbox; `PdHealthReport.tsx:220,321` | ARIA roles are partial | An accessibility pass of its own |
| U48 | `PdPalette.tsx:219` | The palette's selection is not scrolled into view | Small |
| ~~U45~~, ~~U47~~, ~~U48~~ | — | Closed by 1.5.0, the accessibility pass (below) | — |
| A1 | `PdPackageTable.tsx`, `PdPackageRow.tsx` | The package grid is one tab stop per row with no `↑`/`↓` between rows, so passing 200 rows is 200 Tabs | Changes the tab model the owner had just tested by hand on 1.4.0; wants a decision and a Narrator pass of its own, and a virtualizer that scrolls ahead of focus |
| A2 | `PdPackages.tsx:197`, `PdEnvironments.tsx:222`, `PdUninstallDialog.tsx:130`, `PdSummarySheet.tsx:83` | A live region that mounts together with its text may never be announced | Only a screen reader can answer it; Search's region was rebuilt in 1.5.0 because its fix did not depend on the answer |
| A3 | `PdErrorRow.tsx:68`; `PdStatusLine.tsx:41` with `PdEnvironments.tsx:223` | Every error row is `role="alert"`, so a failed batch may fire one assertive alert per package; "scanning" is announced by two regions | Same: needs Narrator, and a decision about which region owns it |
| A4 | `PdConflictRow.tsx`, `PdDockBay.tsx` | Why a control is disabled is only in a `title`, which a disabled control cannot be focused to show | Wants visible text beside the control, in both catalogues |
| A5 | `packageColumns.ts`, `PdSidebar.tsx`, `tauri.conf.json` | No in-app zoom: at 200 % in the default window the name column (`min-w-0 flex-1`) collapses to zero and the sidebar cuts off its last tabs | With U51 — a minimum for the name column, an overflow for the sidebar, then `zoomHotkeysEnabled` |
| A6 | `PdDialog.tsx`, `PdUninstallDialog.tsx`, `PdCacheUsage.tsx`, `PdHealth.tsx` | A dialog's buttons still go `disabled` while its work runs, so focus drops inside the modal until it closes | The shell's lost-focus rule recovers it when the dialog closes; inside one, `aria-disabled` needs the dialog's own busy handling rethought |
| A7 | — | Narrator on 1.5.0, NVDA and JAWS at all, each Windows contrast theme by hand, the installers | The owner's hands; `ACCESSIBILITY.md` says none of it has been done and must be updated by whoever does it |
| U49 | `App.tsx` Ctrl+K | Ctrl+K reads `e.key`, unlike Ctrl+1..9 | Letter shortcuts by physical key are wrong on Dvorak; needs a decision |
| U50 | `PdHealth.tsx:215`, `PdSecurity.tsx:160`, `PdCacheUsage.tsx:32` | Dates and sizes are not formatted per locale | An `Intl` pass |
| U51 | `PdEnvironments.tsx:55`, `PdEnvDetail.tsx:76`, `PdPackageRow.tsx` | Long paths and names overflow | With U22's container-query work |
@@ -1522,6 +1527,81 @@ for something the product never contained.
patched only in 11.x, which ESLint 10.14 and typescript-eslint 8.72 do not accept. Dev-only, the
gate is `high`, and ARCHITECTURE §10 says why it is tolerated rather than forced by `overrides`.
## 1.5.0 — the accessibility pass — **2026-11-10**
One slice: audit backlog U45, U47 and U48, taken as "an accessibility pass of its own", plus the
statement that says what the pass did and did not establish. It began from GitHub's community
profile — five things missing, `ACCESSIBILITY.md` among them — and from the owner's report that
1.4.0 had been driven end to end with the mouse unplugged and with Narrator, and nothing blocked.
Both were true. The code agreed with the owner: nothing was unreachable. What a survey of the code
found was eleven places where it worked and made a user work for it.
**What shipped** (the changelog has it by reader): focus on every screen replacement, not only on a
tab change; the tabs, radio group and listbox patterns finished; names that contain the visible
text; a well-formed grid; a status region for Search; `data-destructive` in place of a hand-kept
list; axe-core over every screen; `ACCESSIBILITY.md`, `CONTRIBUTING.md`, a code of conduct, a pull
request template and an accessibility issue form; and About's Accessibility section.
| Decision | Why |
|---|---|
| axe-core called directly, no `eslint-plugin-jsx-a11y` | The plugin peers ESLint 9 at most and this repository is on 10 — the same wall `react/jsx-no-literals` hit. The matcher packages wrap axe and pin a runner's major. axe-core has no dependencies |
| The radio group's arrows move focus and choose nothing | The pattern says arrows check what they land on; here that would open *Force latest*'s destructive confirm from an arrow key |
| `data-destructive`, and a test that reads the source | Forced-colors cannot be rendered under jsdom, and the stylesheet's list of five `data-action` names had been wrong for as long as it existed |
| WCAG 2.2 AA as a *target* | Nobody independent has audited it, Narrator was not re-run on 1.5.0, and a statement that claims more than its last test is the thing it exists to prevent |
| An answer in 7 days and no fix date | One maintainer. The toolkit's template promises 30/60/90 days; a date that slips is worse than none |
| Zoom built, measured, and taken out | Below |
| `legal/` untouched | The five hashed documents did not need to change, so the gate does not re-show. A dev-only dependency is not a third-party notice |
**What running found that reading did not** — the installed bundle, WebView2's remote-debugging
port (`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=…`, which a release build
honours), real key presses through `Input.dispatchKeyEvent`, and `document.activeElement` and the
accessibility tree read back after each one. Every item below was in code whose tests were green:
- **The high-contrast border on destructive buttons had never been drawn — not for the five the old
list named either.** The rule was in `@layer base`; every button carries Tailwind's `border`
utility; a later layer wins whatever the selectors say. UI-SPEC §7 described that border for two
milestones, and U45 was filed as "the list is incomplete" when the list did nothing at all. Seen
by emulating `forced-colors: active` and enlarging a screenshot of *Cancel* beside *Allow*: the
same border. The rule is unlayered now, a test counts the braces, and it is a double border
because 2 px beside 1 px is not a difference anyone sees.
- **A button that disables itself when pressed drops focus to `<body>`.** A browser takes focus
from a control that becomes `disabled`; jsdom does not, so no test could fail. Found by pressing
*Download the index*. Nine buttons were doing it — *Use*, *Rescan*, *Run*, *Run audit*, *Add*,
*Stop* among them — which is to say most of the app's primary actions lost a keyboard user's
place on the keypress that started the work. Busy is `aria-disabled` now; `disabled` is for
unavailable.
- **Accepting the legal gate left focus on nothing.** The fix for "focus is lost when the screen is
replaced" had been written and tested an hour earlier and did not cover it, because the gate is
rendered *instead of* the shell: a fifth way to replace the screen, and the first thing a new
user does.
- **A dialog's name read "Remove packages : certifi".** A browser puts a space before
visually-hidden text; jsdom's name computation does not.
- **The Updates tab's name read "Updates(5)"** — inline spans are joined without a space.
- **Zoom broke the table.** `zoomHotkeysEnabled` is one line and needs no permission on Windows.
At 200 % in the default 1180 px window — a 590 px viewport, emulated with a device-metrics
override — the name column collapsed to zero width and the sidebar cut off *Settings* and
*About*. It holds at a maximised 1920 px window, which is the layout's own 900 px floor. Taken
out; backlog A5.
And one thing running confirmed rather than found. The survey suspected a package row's focus ring
was clipped, and it was — on three sides, in normal mode, fixed here. The forced-colors block had
carried that exact fix since M2, with a comment saying why: the knowledge was in the stylesheet,
scoped to the one mode someone had looked at.
**What it did not establish.** The assistant cannot run a screen reader. Everything above about
what assistive technology receives is the accessibility tree, which is what is *exposed*, not what
is *said*. Narrator on 1.5.0, NVDA, JAWS and each contrast theme by hand are backlog A7 and are
listed as untested in `ACCESSIBILITY.md`. ROADMAP's own count of live regions — "eight now", Phase
3 · P6 — was ten when this slice counted them, plus two `role="status"`.
**Dependencies, the same day, no version of their own** (#106, superseding #103–#105): the npm,
actions and tools bumps that were past their cooldown, with `tools-constraints.txt` regenerated by
the header's command rather than edited (the result was byte-identical to Dependabot's edit, which
is the check the edit had lacked) and the drift job dispatched on the branch first. Held back and
said so in the PR: i18next 27 with react-i18next 18, and jsdom 31 — majors inside the 14-day
window, the first with new defaults and stricter `t()` types that want a session of their own —
and rfd 0.18, which tauri-plugin-dialog 2.8.4 still pins below.
## Standing risks
| Risk | Mitigation |
+1 -1
View File
@@ -88,4 +88,4 @@ This section once set targets — core ≥ 85 % line coverage, classifiers and p
A short exploratory pass on a real machine: dirty 150+ package env, corporate-proxy simulation (PD-NET-002 copy), non-ASCII Windows username paths, VI locale sweep of all mutation dialogs, cancel mid-Phase-B, and SmartScreen/first-run installer experience.
**And an accessibility pass, since 1.5.0** — ten minutes, on the installed build: the mouse unplugged from the legal gate through an update and its summary (after every screen change, is focus somewhere you can see?); the same with Narrator, listening for the screen's name on arrival and for the run's progress; one Windows contrast theme, looking at a destructive confirm beside its Cancel and at the current sidebar tab; and 200 % zoom. `ACCESSIBILITY.md`'s "what has been tested" table is a record of this pass and is updated by whoever does it — a statement that outlives its last test is the failure it exists to prevent. The parts a machine can do were done for 1.5.0 over WebView2's remote-debugging port (ROADMAP): the accessibility tree, emulated forced-colors and `document.activeElement` after each step.
**And an accessibility pass, since 1.5.0** — ten minutes, on the installed build: the mouse unplugged from the legal gate through an update and its summary (after every screen change, is focus somewhere you can see?); the same with Narrator, listening for the screen's name on arrival and for the run's progress; and one Windows contrast theme, looking at a destructive confirm beside its Cancel and at the current sidebar tab. `ACCESSIBILITY.md`'s "what has been tested" table is a record of this pass and is updated by whoever does it — a statement that outlives its last test is the failure it exists to prevent. The parts a machine can do were done for 1.5.0 over WebView2's remote-debugging port (ROADMAP): the accessibility tree, emulated forced-colors and `document.activeElement` after each real key press. That pass found defects in code whose tests were green — some because jsdom does not take focus from a control that becomes `disabled` and a browser does, one because jsdom applies no stylesheet and so could not show that the high-contrast border had never been drawn.
+21 -6
View File
@@ -408,11 +408,11 @@ either number. Screens (`ui/src/screens/`, `PdPlanPanel` among them) are not cou
- Empty states: one mono glyph + one sentence + one action (e.g. Updates empty: `▸ all packages up to date`).
- Offline: banner chip in top bar; search works (local index), metadata panel shows cached-at timestamp.
- Errors: inline with catalog code, human message (localized), and *Details* expanding stderr tail. Toasts only for background completions. *Report bug* opens a prefilled GitHub issue that nothing sends until the user submits it; since 1.4.0 the link is rebuilt at the click with the selected environment, so the issue carries its Python version and the configured engine's version — one subprocess per report, rather than one per error row mounted, which a summary of many failures would multiply.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override, and — since P5 — `Fix with ruff`, the only one that writes outside an environment) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**. The PEP 668 override was on this list while it was a bare checkbox with no confirm at all; it has been a `PdDialog` since 1.4.0. **A destructive control carries `data-destructive`**, and under forced-colors `styles.css` gives every button with it a 2 px border, because high contrast drops every tint and a destructive primary that looks like Cancel is worse than no colour at all. Until 1.5.0 the stylesheet kept its own list of five `data-action` values instead, and the list was never complete: the uninstall dialog's plain *Remove*, the *Force latest* inline confirm, the override's *Allow*, Disk usage's *Clear* confirm and the plan panel's danger-treated Confirm (a rollback, or a forced plan) were not on it, so in high contrast each was told from the control beside it by its label alone (audit backlog U45). A list of names beside a list of buttons is two lists; `ui/src/destructive.test.ts` reads the source instead and fails on a button drawn in the danger colour without the attribute. The same pass fixed the active sidebar tab, which carries `aria-current="page"` under an outline rule that matched `'true'` alone. *Stop* carries the attribute too: it interrupts a run part-way, and is drawn in the danger colour for that reason.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override, and — since P5 — `Fix with ruff`, the only one that writes outside an environment) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**. The PEP 668 override was on this list while it was a bare checkbox with no confirm at all; it has been a `PdDialog` since 1.4.0. **A destructive control carries `data-destructive`**, and under forced-colors `styles.css` gives every button with it a double border, because high contrast drops every tint and a destructive primary that looks like Cancel is worse than no colour at all. Until 1.5.0 the stylesheet kept its own list of five `data-action` values instead, and the list was never complete: the uninstall dialog's plain *Remove*, the *Force latest* inline confirm, the override's *Allow*, Disk usage's *Clear* confirm and the plan panel's danger-treated Confirm (a rollback, or a forced plan) were not on it, so in high contrast each was told from the control beside it by its label alone (audit backlog U45). A list of names beside a list of buttons is two lists; `ui/src/destructive.test.ts` reads the source instead and fails on a button drawn in the danger colour without the attribute. The same pass fixed the active sidebar tab, which carries `aria-current="page"` under an outline rule that matched `'true'` alone. *Stop* carries the attribute too: it interrupts a run part-way, and is drawn in the danger colour for that reason. **And the border was never drawn at all until 1.5.0**, for the old five as much as the missing five: the rule sat in `@layer base`, every button carries Tailwind's `border` utility, and a later layer wins whatever the selectors say, so `border: 2px` lost to `border-width: 1px`. It is outside every layer now — an unlayered rule beats every layered one, and `destructive.test.ts` counts the braces — and it is a 3 px *double* border, because 2 px beside 1 px is a difference nobody sees at a glance. Found by emulating forced-colors in the installed build and looking at the button; this paragraph described a border for two milestones on the strength of a rule nobody had seen take effect.
## 8. Keyboard & accessibility
Full keyboard traversal: `Ctrl+1..9` sidebar tabs (by physical key), **`Ctrl+K` opens the command palette**, `/` focuses the Search field, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers, and **`←`/`→` move within a focused row** (P6). Since 1.5.0: `←`/`→`/`Home`/`End` move between Code Health's tabs, the arrow keys move between a conflict's three choices, and `Ctrl` `+`/`-`/`0` zoom. [`ACCESSIBILITY.md`](../ACCESSIBILITY.md) is the user-facing statement of this section, with what has and has not been tested; About links to it.
Full keyboard traversal: `Ctrl+1..9` sidebar tabs (by physical key), **`Ctrl+K` opens the command palette**, `/` focuses the Search field, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers, and **`←`/`→` move within a focused row** (P6). Since 1.5.0: `←`/`→`/`Home`/`End` move between Code Health's tabs, and the arrow keys move between a conflict's three choices. [`ACCESSIBILITY.md`](../ACCESSIBILITY.md) is the user-facing statement of this section, with what has and has not been tested; About links to it.
**Four rules from 1.4.0:**
@@ -441,12 +441,14 @@ A dialog — `PdDialog`, and the palette — returns focus to whatever opened it
to fall to `<body>`, and a keyboard user lost their place in a 200-row table. The package grid itself
is focusable but not a tab stop: the row is.
**Five rules from 1.5.0**, the accessibility pass:
**Six rules from 1.5.0**, the accessibility pass:
- **Focus moves whenever the screen is replaced, not only when the tab changes.** The shell focused
the new screen's heading on a `nav` change and on nothing else — but the plan panel and each of
its phases, the dependency view and an opened environment all replace what `<main>` shows without
changing `nav`, and each unmounts the control that was just pressed. Focus fell to `<body>`. A
changing `nav`, and each unmounts the control that was just pressed. Focus fell to `<body>`. The
legal gate is a fifth: it is rendered *instead of* the shell, so accepting it replaces the screen
with `nav` unchanged, and the first screen of a first run had focus on nothing. A
second effect in `App.tsx` covers them, and **acts only when focus was actually lost**: a run
advancing from `resolving` to `preview` must not pull a keyboard user off *Back*, and an open
modal owns focus until it closes. The console drawer returns focus to its opener the same way,
@@ -468,8 +470,21 @@ is focusable but not a tab stop: the row is.
from. Several older regions still mount with their text; whether a reader says them is in the
Audit backlog, because only a reader can answer it.
**Zoom is on since 1.5.0** (`zoomHotkeysEnabled`, which on Windows is WebView2's own zoom control,
so it needs no permission and no code). The zoom level is the webview's and is not persisted.
- **Busy is `aria-disabled`; unavailable is `disabled`.** A browser takes focus away from a control
that becomes `disabled`, so a button that disables itself when pressed — *Use*, *Rescan*, *Run*,
*Run audit*, *Add*, *Download the index*, *Stop*, the two requirements buttons — dropped focus to
`<body>` on the keypress that started its work. Those carry `aria-disabled` while busy and
ignore a second press; `disabled` is kept for a control that cannot be used at all, which nobody
is focused on when it happens. jsdom does not move focus off a disabled control, so no test could
see this; it was found by pressing *Download the index* in the installed build.
**Zoom is not on.** `zoomHotkeysEnabled` (WebView2's own zoom control on Windows — no permission,
no code) was set for 1.5.0 and taken out again on a measurement: at 200 %, which in the default
1180 px window is a 590 px viewport, the package table's name column (`min-w-0 flex-1`) collapsed
to zero width and the sidebar, which does not scroll, cut off its last two tabs. At a maximised
1920 px window the same zoom is the layout's own 900 px floor and holds. Shipping it means giving
the name column a minimum and the sidebar an overflow — U51's container-query work — and until
then the Windows display scale, which enlarges the window with its content, is the supported way.
**The arrow keys are not decoration, and the gap they close was real.** Making the row the only tab stop is what keeps 200 rows from becoming 600 — but every control inside one is `tabIndex={-1}`, and that left *Pin* and *Remove* reachable by mouse only: a WCAG 2.1.1 failure, found by tabbing to a row in the running app and discovering there was nowhere further to go. `←`/`→` are the ARIA grid pattern's roving tabindex, `Esc` returns focus to the row, and no tab stops are added.