From d016b80014ac71b5643a5b16872a36dc13f7fa75 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:59:43 +0700 Subject: [PATCH] fix(a11y): name dialogs by their heading, and four smaller things A PdDialog's name was an aria-label holding what it was about, so a screen reader announced "numpy, dialog" and then "Cancel": the question being asked was on screen and never spoken. It is named by its visible heading, followed by what it is about, and described by its body. The legal gate replaces the whole shell, declares itself modal, and had no focus inside it. Its heading takes focus on arrival, as a screen's does. A package row's focus ring was drawn 2px outside a row that is absolutely positioned in a scroller and stacked against its neighbours, so three sides of it were clipped or painted over. It sits inside the row, in every mode rather than only in forced-colors. The dock bay's remove button was a bare glyph about 8px wide. It is 24px each way. Co-Authored-By: Claude Fable 5.2 --- ui/src/components/PdDialog.tsx | 27 ++++++++++++++++---- ui/src/components/PdDockBay.tsx | 4 ++- ui/src/components/PdLegalGate.test.tsx | 8 ++++++ ui/src/components/PdLegalGate.tsx | 13 ++++++++-- ui/src/components/PdUninstallDialog.test.tsx | 11 ++++++++ ui/src/styles.css | 8 ++++++ 6 files changed, 63 insertions(+), 8 deletions(-) diff --git a/ui/src/components/PdDialog.tsx b/ui/src/components/PdDialog.tsx index 1684e98..5518926 100644 --- a/ui/src/components/PdDialog.tsx +++ b/ui/src/components/PdDialog.tsx @@ -26,10 +26,17 @@ * double-submitted and the user keeps reading what they were reading. */ -import { useEffect, useRef } from 'react' +import { useEffect, useId, useRef } from 'react' interface PdDialogProps { - /** Accessible name — the package or operation the dialog is about. */ + /** + * What the dialog is about — the package, the interpreter, the cache. + * + * Spoken after the heading, as part of the dialog's name. It used to *be* the name, as an + * `aria-label`, so a screen reader announced "numpy, dialog" and then "Cancel": the question + * being asked was on screen and never said. A caller whose heading already says it passes the + * same string for both, and it is said once. + */ label: string /** Heading text, already localized. */ title: string @@ -55,6 +62,8 @@ export function PdDialog({ }: PdDialogProps) { const ref = useRef(null) const cancelRef = useRef(null) + const titleId = useId() + const bodyId = useId() useEffect(() => { const el = ref.current @@ -72,7 +81,10 @@ export function PdDialog({ return ( { @@ -84,8 +96,13 @@ export function PdDialog({ // top-left corner. Seen in the installed build; jsdom computes no layout to show it. className="m-auto max-w-lg rounded-pd border border-border bg-surface p-6 text-text backdrop:bg-bg/80" > -

{title}

-
{children}
+

+ {title} + {label === title ? null : {`: ${label}`}} +

+
+ {children} +
{/* First, and focused: UI-SPEC §7. The safe answer must be the one a reflex reaches. */} diff --git a/ui/src/components/PdLegalGate.test.tsx b/ui/src/components/PdLegalGate.test.tsx index 51945eb..f2b7d93 100644 --- a/ui/src/components/PdLegalGate.test.tsx +++ b/ui/src/components/PdLegalGate.test.tsx @@ -33,6 +33,14 @@ describe('PdLegalGate', () => { vi.mocked(openUrl).mockResolvedValue(undefined) }) + it('puts focus on its heading when it takes the screen', () => { + // The gate replaces the whole shell and says it is modal, and nothing inside it had focus: + // the first thing a keyboard or screen-reader user met on first run was silence, then the + // first link. The shell focuses a screen's heading on arrival; this is the same move. + render() + expect(screen.getByRole('heading', { level: 1 })).toHaveFocus() + }) + describe('first run', () => { it('lists all five documents and opens each on GitHub', () => { render() diff --git a/ui/src/components/PdLegalGate.tsx b/ui/src/components/PdLegalGate.tsx index f8e4ba2..08c09a3 100644 --- a/ui/src/components/PdLegalGate.tsx +++ b/ui/src/components/PdLegalGate.tsx @@ -17,7 +17,7 @@ */ import { getCurrentWindow } from '@tauri-apps/api/window' -import { useState } from 'react' +import { useEffect, useRef, useState } from 'react' import { useTranslation } from 'react-i18next' import { LEGAL_DOCUMENTS } from '@/components/legal' @@ -39,6 +39,11 @@ export function PdLegalGate({ const error = useLegalStore((s) => s.error) const [checked, setChecked] = useState(false) const { open, failed: openFailed } = useOpenExternal() + const heading = useRef(null) + + useEffect(() => { + heading.current?.focus() + }, []) return (
-

+ {/* Focused on arrival. The gate replaces the whole shell and declares itself modal, and + nothing inside it had focus — on first run a keyboard or screen-reader user met + silence, then the first link. The shell focuses a screen's heading when it changes + (`App.tsx`); the gate is rendered instead of the shell, so it does the same itself. */} +

{t('legal.title')}

diff --git a/ui/src/components/PdUninstallDialog.test.tsx b/ui/src/components/PdUninstallDialog.test.tsx index bb945e0..248856b 100644 --- a/ui/src/components/PdUninstallDialog.test.tsx +++ b/ui/src/components/PdUninstallDialog.test.tsx @@ -44,6 +44,17 @@ describe('PdUninstallDialog', () => { expect(screen.getByText('scipy 1.11.4 requires numpy<1.28.0,>=1.21.6')).toBeInTheDocument() }) + it('is named by its heading and by what it is about, and described by its body', () => { + // The name was the package alone — a reader heard "numpy, dialog" and then "Cancel", with the + // question the dialog asks never spoken. A dialog is named by its visible heading; what it is + // about follows, and the body is its description. + setup(BREAKING) + + expect(dialog()).toHaveAccessibleName(/^This removal breaks other packages.*numpy/) + expect(dialog()).toHaveAccessibleDescription(/pandas 2\.1\.4 requires numpy/) + expect(dialog()).not.toHaveAttribute('aria-label') + }) + it('focuses Cancel, and renders it first', () => { // UI-SPEC §7: destructive confirms "require the dialog's default focus to be Cancel". setup(BREAKING) diff --git a/ui/src/styles.css b/ui/src/styles.css index b9c2dd1..fd39c2a 100644 --- a/ui/src/styles.css +++ b/ui/src/styles.css @@ -91,6 +91,14 @@ outline-offset: 2px; } + /* A package row's ring sits inside it. Rows are absolutely positioned inside a scroller and + * stacked edge to edge, so a ring drawn 2px outside one is clipped by the scroller at both + * ends and painted over by the row below — three sides of the ring a keyboard user steers by. + * This was in the forced-colors block alone, where the same clipping had been noticed. */ + [role='row']:focus-visible { + outline-offset: -2px; + } + /* UI-SPEC §2: prefers-reduced-motion is respected. */ @media (prefers-reduced-motion: reduce) { *,