fix(a11y): four defects from an independent review of the diff

- Visually-hidden text is position: absolute, and with no positioned ancestor
  it is laid out against the viewport, outside every scroller above it. A pin
  chip's hidden sentence did that on Pins: a long list made the whole window
  scroll and took the header with it. Every parent of hidden text is relative.
- A run that failed before producing a summary rendered no <h1>, so the focus
  rule had nothing to land on. The branch has a heading.
- The console drawer stays open across runs, so the next run mounts it with no
  opener to return focus to. It falls back to the Console button.
- Under forced-colors the selection outline followed the focus ring at equal
  specificity and replaced it on a focused current tab.

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 f9c5001dc4
commit 7ee00893a7
12 files changed
+104 -12

No files matched your search

+3
View File
@@ -198,6 +198,9 @@ driving the installed build:
- **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.
- **`sr-only` text needs a positioned parent.** It is `position: absolute`, so with no positioned
ancestor it is laid out against the viewport, outside every scroller: a list of pin chips on
Pins made the whole window scroll. Put `relative` on whatever holds the hidden text.
- **`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.
+16
View File
@@ -1588,6 +1588,22 @@ was clipped, and it was — on three sides, in normal mode, fixed here. The forc
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.
**And what a second reader found**, in the diff, after the smoke had passed — an independent review
run while CI was going:
- **`sr-only` text needs a positioned parent.** It is `position: absolute`; with no positioned
ancestor it is laid out against the viewport and escapes every scroller above it. A pin chip's
new hidden sentence did exactly that on Pins, where nothing between the chip and `<html>` is
positioned: a long list made the whole window scroll and took the header with it. Package rows
hid it, because a row is `absolute`. Every parent of hidden text is `relative` now.
- **An error-only summary had no `<h1>`**, so the new focus rule had nothing to land on — on the
one screen where a run had just failed.
- **A drawer that mounts already open has no opener.** `consoleOpen` outlives a run; closing the
drawer in the next one dropped focus as it had before the fix. It falls back to the *Console*
button.
- Under forced-colors, the selection outline followed the focus ring at equal specificity, so a
focused current tab got a 1 px line in place of its 2 px ring.
**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
+4 -1
View File
@@ -39,7 +39,10 @@ export function PdBadge({ tone, label, glyph, title }: PdBadgeProps) {
const explained = title !== undefined && title !== label
return (
<span
className={`inline-flex shrink-0 items-center gap-1 rounded-pd px-1.5 py-0.5 text-data ${TONES[tone]}`}
// `relative`: the hidden sentence below is `position: absolute`, and with no positioned
// ancestor it is laid out against the viewport — outside every scroller above it. On Pins a
// long list of chips made the whole window scroll. The chip is its containing block.
className={`relative inline-flex shrink-0 items-center gap-1 rounded-pd px-1.5 py-0.5 text-data ${TONES[tone]}`}
title={title ?? label}
>
{glyph === undefined ? null : <span aria-hidden="true">{glyph}</span>}
@@ -69,6 +69,35 @@ describe('PdConsoleDrawer', () => {
expect(toggle).toHaveFocus()
})
it('finds the console button when nothing opened it', () => {
function AlreadyOpen() {
const [open, setOpen] = useState(true)
return (
<>
<PdConsoleDrawer
lines={[]}
open={open}
done={0}
total={0}
onClose={() => {
setOpen(false)
}}
/>
<button type="button" data-console-toggle>
Console
</button>
</>
)
}
render(<AlreadyOpen />)
const close = screen.getByRole('button', { name: 'Close console' })
close.focus()
fireEvent.keyDown(close, { key: 'Escape' })
expect(screen.getByRole('button', { name: 'Console' })).toHaveFocus()
})
it('leaves focus alone when it was never inside', () => {
// Toggled shut from the button that opened it: focus is already where it should be.
const toggle = openDrawer()
+8 -1
View File
@@ -63,7 +63,14 @@ export function PdConsoleDrawer({ lines, open, onClose, done, total }: PdConsole
return () => {
const active = document.activeElement
if (active !== null && active !== document.body && active.isConnected) return
if (opener !== null && opener !== document.body && opener.isConnected) opener.focus()
if (opener !== null && opener !== document.body && opener.isConnected) {
opener.focus()
return
}
// **Nothing opened it.** `consoleOpen` outlives a run, so the next run mounts the drawer
// already open, with focus on nothing to remember. The button that toggles it is the
// nearest thing to an opener there is.
document.querySelector<HTMLElement>('[data-console-toggle]')?.focus()
}
}, [open])
+1 -1
View File
@@ -260,7 +260,7 @@ export function PdHealthReport({
// be selected is already in the document to take focus.
document.getElementById(`health-tab-${next}`)?.focus()
}}
className={`rounded-t-pd px-3 py-1.5 font-mono text-data ${
className={`relative rounded-t-pd px-3 py-1.5 font-mono text-data ${
tab === key
? 'border-b-2 border-accent text-text'
: 'text-text-dim hover:bg-surface-2'
+7 -3
View File
@@ -223,8 +223,12 @@ describe('grid structure', () => {
.getAllByRole('row')
.find((row) => row.getAttribute('data-pinned') === 'true')
if (pinned === undefined) throw new Error('the fixture has no pinned row')
expect(within(pinned).getByText(/kept at this version|left out of every update/)).toHaveClass(
'sr-only',
)
const explained = within(pinned).getByText(/kept at this version|left out of every update/)
expect(explained).toHaveClass('sr-only')
// `sr-only` is `position: absolute`. Without a positioned ancestor it is laid out against the
// viewport and escapes every scroller above it — on Pins, where nothing between the chip and
// <html> is positioned, a long list of these made the whole window scroll and took the header
// with it. The chip is the containing block.
expect(explained.parentElement).toHaveClass('relative')
})
})
+2 -2
View File
@@ -108,7 +108,7 @@ export function PdPackageTable({
{/* The checkbox and action columns have no visible heading, and are still columns: the
header had five headings over six cells, so moving by column read "Status" above the
action buttons. Named for whoever cannot see which column they are in. */}
<span role="columnheader" className={COLUMNS.checkbox}>
<span role="columnheader" className={`relative ${COLUMNS.checkbox}`}>
<span className="sr-only">{t('packages.column.select')}</span>
</span>
<span role="columnheader" className={COLUMNS.name}>
@@ -126,7 +126,7 @@ export function PdPackageTable({
<span role="columnheader" className={COLUMNS.status}>
{t('packages.column.status')}
</span>
<span role="columnheader" className={COLUMNS.actions}>
<span role="columnheader" className={`relative ${COLUMNS.actions}`}>
<span className="sr-only">{t('packages.column.actions')}</span>
</span>
</div>
+21
View File
@@ -61,6 +61,27 @@ describe('the summary phase', () => {
expect(screen.getAllByText('Back to packages')).toHaveLength(1)
})
it('has a heading even when there is no summary to show', () => {
// The shell puts focus on a screen's <h1> when the screen is replaced. This branch had none —
// the sheet owns the heading and there is no sheet — so a run that failed before producing a
// summary left focus on <body>, on exactly the screen where something had gone wrong.
usePlanStore.setState({
phase: 'summary',
outcome: null,
error: { code: 'PD-SNP-001', message: 'snapshot failed' },
})
render(<PdPlanPanel onFinished={vi.fn()} />)
expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('Something went wrong')
})
it('has exactly one heading when the sheet is showing', () => {
usePlanStore.setState({ phase: 'summary', outcome: OUTCOME, kind: 'update' })
render(<PdPlanPanel onFinished={vi.fn()} />)
expect(screen.getAllByRole('heading', { level: 1 })).toHaveLength(1)
})
})
const FORCED_STEP = flowStepForced as FlowStep
+6
View File
@@ -83,6 +83,10 @@ export function PdPlanPanel({ onFinished }: PdPlanPanelProps) {
if (phase === 'summary') {
return (
<section className="h-full overflow-auto p-6">
{/* The sheet owns this screen's heading, and a run that failed before producing a summary
has no sheet — so this branch had no <h1>, the shell had nothing to focus, and focus
stayed on <body> on the one screen where something had gone wrong. */}
{outcome === null ? <h1 className="mb-4 text-accent">{t('errors.title')}</h1> : null}
{error === null ? null : (
<div className="mb-4">
<PdErrorRow error={error} />
@@ -245,6 +249,8 @@ export function PdPlanPanel({ onFinished }: PdPlanPanelProps) {
onClick={() => {
setConsoleOpen(!consoleOpen)
}}
// Where the drawer sends focus when it closes and nothing opened it.
data-console-toggle
className="rounded-pd border border-border px-3 py-1 text-data"
>
{t('plan.console')}
+1 -1
View File
@@ -108,7 +108,7 @@ export function PdSearch() {
earlier state to differ from. */}
<div
role="status"
className="mt-1 flex min-h-5 shrink-0 items-center gap-2 text-data text-text-dim"
className="relative mt-1 flex min-h-5 shrink-0 items-center gap-2 text-data text-text-dim"
>
{/* Warming is a state, not a failure: the index is 864k names and takes ~140 ms to
load, and saying so beats a field that silently returns nothing. */}
+6 -3
View File
@@ -161,9 +161,12 @@
/* `page` is the sidebar's active tab. The rule matched `'true'` alone, so the one thing that
* said which screen is showing was drawn like every other tab. */
[aria-selected='true'],
[aria-current='true'],
[aria-current='page'] {
/* `:not(:focus-visible)`: this rule follows the focus ring's at equal specificity, so a
* focused selection — the current tab, the selected hit — got this 1px line in place of its
* 2px ring. */
[aria-selected='true']:not(:focus-visible),
[aria-current='true']:not(:focus-visible),
[aria-current='page']:not(:focus-visible) {
outline: 1px solid Highlight;
}