Files
pipelines/web/docs/a11y-audit.md
T
alan 8880495970 web: layout prototype/spec and an accessibility audit (design inputs)
The layout prototype shows the operator's target shell: a left destination rail
(Pipelines/Runs/Chat/Settings) with the detail sections grouped in the rail, list
and detail panes, a status dot in the rail footer and no top connection chrome.
The spec's DOM sketch still mentions the old connection banner; the implementation
brief supersedes that (connection lives in Settings only).

The audit records 9 must-fix, 12 should-fix and 15 notes from real DOM and
accessibility-tree inspection, with file:line for each finding.
2026-10-19 16:33:59 +01:00

27 KiB
Raw Blame History

Pipelines web client — accessibility audit

Date: 2026-10-19 Scope: the browser client in web/ (L7 in web/PARITY.md), against the live server on 127.0.0.1:8080. Status: audit only. This audit adds only this report; no product source, test, style or config file was changed.

What was driven

The page was served by web/serve.mjs on 127.0.0.1:8097 against the live Pipelines server on 127.0.0.1:8080, then driven in headless Chrome 1440×900 through the read-only web/test/browser.mjs driver plus the Chrome DevTools Protocol for real key events, the accessibility tree and reduced-motion emulation.

Screens exercised: Pipelines list + filter/sort; Runs list + filter/sort; all five run-detail tabs; the Timeline stage pane; the Changes diff viewer (run 438); the artifact gallery and full-screen image viewer (run 430); Chat list, transcript, composer, actions menu and Rename dialog; Search; the Needs you sheet (182 entries at capture time); Settings; and URL deep links (/runs/:id, /runs/:id/stage/:key, /pipelines/:id, /pipelines/:id/:version, /settings/templates, /templates, and a malformed run id).

Screen coverage

Screen What was driven Checks that were exercised Findings
Pipelines list + filters list load, Filter panel, Sort panel, trigger toggles names, tab order, Escape, outside click, headings, contrast M3, M4, M8, S1, S2
Runs list + filters 438 runs, Filter and Sort panels, row selection names, 458-control tab walk, Escape, outside click, headings M3, M4, M8, S1, S2
Run detail tabs Summary / Graph / Input / Output / Timeline tab role/selected, names, ArrowRight, headings M3, M8
Run decision sheet not reachable (no waiting run); source reviewed dialogue/radio/groups, keyboard, error announcement S9
Stage pane opened from a Timeline row, focus walk, Escape dialog name, initial focus, trap, background inertness, Escape return M1, M2
Changes viewer run 438 Summary → expand Changes → open diff dialog name, initial focus, trap, Escape return, contrast M1, M2, N1
Artifacts viewer run 430 gallery → image tile → full-screen viewer tile semantics, keyboard, viewer focus/trap/Escape, names M5, S10, N11
Chat list, menu, Rename dialog, transcript, composer, palette; approval card unavailable (no pending request) row/menu names, keyboard, Shift+Enter, empty Enter, live semantics M6, S5, S7, S8, N4, N7
Search query plan, kind/sort controls, results, Escape names, live region, focus return M2, S6, N13
Attention sheet bell → 182-entry sheet, focus walk, Escape names, duplicate Dismiss, trap, background, Escape return M1, M7
Settings Connection, Workspace, Notifications, Templates sections names, duplicate Disconnect, headings, status M8, S11, N13
Deep links 7 paths including a malformed id route resolution, stage-pane link, fallback N5

Read-only guarantees observed:

  • No run was started, cancelled, retried or decided. The Retry confirm was opened and dismissed with Escape; no retry_run/cancel_run/decide_run was sent.
  • No chat was created, closed or hidden. The existing operator session was opened read-only (subscription only); the Rename dialog was opened and dismissed without saving. The composer draft was exercised and restored.
  • No filter was applied, no attention entry was dismissed, no settings were saved.

Summary

9 must-fix, 12 should-fix, 15 notes. The status palette and the rest of the dark palette pass AA contrast; status is never colour-only. The largest problems are structural: modal dialogs do not trap focus or hide the background, tabs are anonymous buttons, and the detail pane sits after hundreds of list rows in the tab order. Artifact tiles cannot be opened by keyboard, and several lists expose identical accessible names for different actions.

Must-fix (do these in one later item, in this order)

# Finding Screen(s) Severity Evidence Exact element + file:line Suggested fix
M1 No modal focus trap; the background stays tabbable. Tab from the last control goes to body or a background row; Shift+Tab from the first goes back into the page. document.querySelectorAll("[inert]").length === 0 while each measured dialog was open. Attention sheet, stage pane, Changes viewer, artifact viewer, confirm dialogs, decision sheet, chat Rename/Close, template create must-fix DOM + AX (attention, stage, changes, artifact, confirm measured; others structurally identical) div.attention-sheet src/app.js:1010-1049; div.stage-pane 3244-3282; div.change-viewer 2983-3107; div.artifact-viewer 4047-4160; div.confirm-dialog 3662-3703; div.decision-sheet 3515-3594; div.confirm-chat-rename 5894-5900; div.confirm-chat-close 6946-7005; div.template-create-dialog 2153-2210 Add one shared dialog controller: record the trigger, move focus to the first control (or the panel), trap Tab/Shift+Tab inside the panel, set inert (or aria-hidden) on #content, .topbar and the banner, close on Escape/backdrop, then restore the trigger. Apply it to every role="dialog".
M2 Some dialogs open with no focus at all, and several never return focus. Changes viewer and artifact viewer opened with focus still outside the dialog (document.activeElement === body in the automated capture, dialog.contains(activeElement) === false); confirm also opened on body after its trigger was replaced. After Escape, the artifact viewer, confirm, chat actions menu, chat Rename and Search leave focus on body. Changes viewer, artifact viewer, confirm, Action failed, chat menu, chat Rename/Close, template create, Search must-fix DOM for changes/artifact/confirm/menu/rename/search; code for Action failed/chat Close/template create openChangeViewer src/app.js:2978-3107; openArtifactViewer 4043-4160; renderConfirmDialog 3639-3704; dismissConfirm 3628-3631; dismissActionError 3750-3753; dismissChatRename 4890-4893; dismissChatClose 4766-4769; closeTemplateCreateDialog 2137-2144; chat menu close 8634-8639; closeSearch 7124-7138 Give each opener an explicit return target and call .focus() after render. The same shared controller as M1 should cover this; for the menu, return to its button.chat-menu-button; for Search, return to #searchToggle.
M3 The "tabs" are plain buttons: no tablist/tab/tabpanel, no selected state, no arrow-key operation. Chrome's AX tree reports role=button for every top-level and detail tab; aria-selected/aria-current are absent; the active state exists only as .active CSS. ArrowRight on the active detail tab does nothing. Top nav, pipeline detail tabs, run detail tabs must-fix DOM + AX tabButton src/app.js:1301-1313; pipeline tab strip 1938-1950; run tab strip 2686-2701; nav.tabs 1244-1257 Use role="tablist" on the strip, role="tab" + aria-selected + aria-controls on each tab, role="tabpanel" + aria-labelledby on the body; roving tabindex and ArrowLeft/ArrowRight/Home/End. If the top nav stays navigation, at minimum add aria-current="page" and aria-label="Primary".
M4 The detail pane comes after the entire list in tab order; there is no skip link. From the selected run row to the first detail tab is 351 tab stops (458 focusables on screen). Pipelines: 29 stops; Chat: 43 stops. No skip link exists on any route. Runs, Pipelines, Chat must-fix DOM (real Tab order / focusable indices) renderContent split order src/app.js:1265-1277 (list appended before detail); renderPipelineList 1695-1701; renderRunList 2362-2406; index.html:9-15 (no skip link) Add a "Skip to detail" link as the first focusable, and after a row is activated move focus to the detail's h1/h2 (and announce it). Alternatively make each list a roving-tabindex listbox so it contributes one stop.
M5 Artifact tiles are click-only generic divs. Chrome reports role=generic, name "" for div.artifact-tile.clickable; it has no tabindex, no key handler and no control role. An image/video tile opens the viewer; a file tile opens a new tab — both only by mouse. Artifacts gallery and visit artifacts must-fix DOM + AX renderArtifactTile src/app.js:3904-3936; click handlers 3921, 3925, 3932 Make the tile itself a <button> (or role="button" tabindex="0" with Enter/Space) named Open {artifact name}; move the viewer/tab action there. Keep Copy link/Share as sibling buttons and stop propagation. Mark the video poster glyph decorative.
M6 A chat row is a role=button containing another real button, and its name absorbs "Chat actions". AX name of the row is e.g. New chat Operator Open Idle · … Chat actions; the inner action button is also a tab stop. 19–21 rows expose the identical Chat actions name, and many rows share identical New chat … names. Chat list must-fix DOM + AX renderChatRow src/app.js:5514-5552 (row role=button at 5516, menu appended at 5550); renderChatActionsMenu 5672-5736 Make the title/meta area the session button and render the actions button as its sibling, not a child. Name the actions control Chat actions for {title} (include session id or directory when titles repeat). Drop role=button from the row container.
M7 Every attention-row dismiss control is named exactly "Dismiss". The captured sheet had 181–182 identical names; a screen-reader user cannot tell which run each one dismisses. Needs you sheet must-fix DOM + AX renderAttentionRow src/app.js:1053-1089 (aria-label: "Dismiss" at 1079) Use aria-label="Dismiss {run label}" (optionally — {pipeline}/kind); keep the visible ✕ and title.
M8 No h1 on any route, and the list routes have no headings at all. document.querySelectorAll("h1").length === 0 on /pipelines, /runs, /chat, /settings, /templates. Pipeline/Runs list views have zero headings; details begin at h2; Settings has four h2s; Chat has an h2 and markdown h4/h5. All screens must-fix DOM renderContent src/app.js:1244-1257; pipeline list 1695-1701; run list 2362-2406; renderSettingsView 1326-1335; chat title 5759; index.html (no server-rendered heading) Render one h1 per route ("Pipelines", the run/pipeline title, "Chat", "Settings", "Templates") and an h2 for each list. Keep Settings sections at h2; ensure markdown headings start below the transcript heading.
M9 Timeline rows have no visible focus ring. .timeline-row:focus-visible removes the outline and changes only the background from --surface to --surface-2 (≈1.2:1). The row's other focus styling is absent. Run detail → Timeline must-fix DOM/CSS (outline: none, :focus-visible true) styles.css:790 (.timeline-row:hover, .timeline-row:focus-visible { background: var(--surface-2); outline: none; }) Add outline: 2px solid var(--accent); outline-offset: -2px; (matching .chat-row/.change-row) or another ≥3:1 ring.

Should-fix

# Finding Screen(s) Severity Evidence Exact element + file:line Suggested fix
S1 Selection is not exposed. Selected pipeline, run and chat rows are marked only by .selected (background + inset bar); no aria-current/aria-selected reaches the AX tree. Pipelines, Runs, Chat should-fix DOM + AX renderPipelineRow src/app.js:1920-1924; renderRunRow 2450-2453; renderChatRow 5514-5529 Add aria-current="true" to the selected row, or implement the lists as listboxes with option + aria-selected.
S2 Pipeline/run Filter and Sort popovers ignore Escape and outside clicks, and their triggers do not expose expanded state. Escape left #runFilterMenu/#sortPanel open; clicking the detail pane did not close it. Triggers have no aria-expanded; the menus have no role. Pipelines list, Runs list should-fix DOM Triggers src/app.js:1721-1741 and 2506-2525; panels 1756-1823, 2544-2601; global Escape 8591-8643 (no filter/sort branch) Add aria-expanded/aria-controls on both triggers, close on Escape and outside pointerdown, and give the panels role="group"/role="menu" with a label. Return focus to the trigger.
S3 The header server-URL field is named by its placeholder. AX name is ws://HOST:PORT/connect, not "Server URL"; it is the only form field in the header with no label. (Settings' field is correctly named "Server URL".) Global header should-fix AX #url src/app.js:815-824 Add a visually hidden or visible <label for="url">Server URL</label> (or aria-label="Server URL"), and keep the placeholder as an example.
S4 The document title never changes per route. Every route reports Pipelines — web spike; deep links and SPA navigation do not update it. All screens / deep links should-fix DOM index.html:6; no document.title assignment in src/app.js (verified by grep) Set document.title from the current route/detail ("Pipelines", "Runs — {run}", "Chat — {title}", "Settings", "Templates — {template}").
S5 The chat actions menu advertises role="menu" but does not support menu keys, and Escape loses focus. ArrowDown leaves focus on Rename…; Escape closes the menu but focus lands on body. Chat list → Chat actions should-fix DOM Menu src/app.js:5691-5734; open/focus 4861-4878; Escape 8634-8639 Implement roving focus with ArrowUp/ArrowDown/Home/End (and optional typeahead), and return focus to the Chat actions for … trigger on Escape/selection.
S6 The Search panel is an unlabelled generic div. #searchPanel has no role or accessible name; it is a disclosure rather than a landmark. Its Escape focus loss is covered by M2. Search should-fix DOM Panel src/app.js:7311; open/close 7108-7138 Give the panel role="search"/role="dialog" + aria-label="Search", and keep the field labelled.
S7 The slash-command highlight is visual only. The textarea has no aria-controls/aria-activedescendant; ArrowDown changes aria-selected on the option but the AX tree gets no active-descendant change, so screen readers do not hear the highlighted command. Chat composer should-fix DOM Textarea src/app.js:6780-6790; palette 6741-6747, 6815-6839; key handler 5085-5100 Give options ids and set aria-controls="chatPalette" + aria-activedescendant on #chatInput as the highlight moves (and aria-expanded).
S8 Live updates are not announced. #chatTranscript has no role="log"/aria-live/label, so streamed answer text and the approval card are silent; the approval card has no role="alert"; run status updates have no live region either. Chat transcript/approval, Runs list/detail should-fix DOM for transcript (no attributes); code for approval/run updates Transcript src/app.js:6072-6123; approval card 6152-6188; approval jump 6126-6142 Make the transcript a labelled role="log" with aria-live="polite" (avoid announcing every delta: announce turn boundaries); give a newly actionable approval role="alert"/aria-live="assertive"; add a polite live region for run status changes.
S9 The decision sheet's radiogroup does not behave like one (code-read; no waiting run was live). All options are tab stops with role="radio", arrow keys are not handled, and selecting an option calls renderContent(), which replaces the button and drops focus. The error line is not role="alert". Run decision sheet should-fix Code Options src/app.js:3532-3553; select handler 3541-3544; error 3570 Roving tabindex (selected option = 0, others -1), ArrowUp/ArrowDown/ArrowLeft/ArrowRight selection, restore focus to the chosen option after render, and role="alert" on the error.
S10 Artifact action names are duplicated without context. In run 430's gallery: Copy link ×8 and Share ×18, with no artifact name in the accessible name. Artifacts gallery / visit artifacts should-fix DOM + AX renderTileActions src/app.js:3938-3966 Use aria-label="Copy link to {name}" / "Share {name}".
S11 Two different "Disconnect" buttons on Settings. The header #connectBtn and the Settings primary #settingsPrimary are both named Disconnect, with no distinguishing context. Settings should-fix AX Header src/app.js:833-838; Settings primary 1381-1395 Name them by scope ("Disconnect server" / "Disconnect (header)") or hide the header connection controls while Settings is open.
S12 prefers-reduced-motion does not stop the spinner. Under emulated prefers-reduced-motion: reduce, .spinner still reports animation-name: spin; animation-duration: 0.8s. The graph halo and search progress do stop. All screens with loading/spinners should-fix DOM (CDP media emulation) styles.css:390-400; existing media blocks 662-664 and 1296-1298 Add .spinner { animation: none; } (or a non-rotating loading treatment) to the reduced-motion block.

Notes, passes and limits

# Observation Screen(s) Severity Evidence Element + file:line
N1 Status palette contrast passes. On --surface (#171f1d): running 7.62, waiting 11.22, succeeded 9.13, failed 6.94, canceled 5.30, interrupted 9.82, queued 6.68, blocked 8.08, skipped 8.28, unknown 9.88. On --surface-2: all ≥4.67 (worst: canceled #889391). Flow-outcome colours are 7.25–12.5. --muted is 7.38/6.51. No low-contrast text was found on any audited screen (lowContrastCount: 0). All note (pass) DOM (computed colours + WCAG formula) styles.css:2-14, 211-219, 809-827
N2 Status is not colour-only. Every chip carries its status word; the live badge carries its word; decorative dots are aria-hidden="true". The only state that is still visual-only is the active/selected row/tab, covered by M3/S1. All note (pass) DOM styles.css:208-231; src/app.js:2535-2542
N3 No unnamed controls. Across the audited screens every focusable control had a non-empty accessible name (447–484 controls on Runs across states, 50–88 in Chat). Icon-only controls (Send, Stop, Attach file, Chat actions, notification bell, remove attachment, Close) all carry aria-label. The one unnamed interactive element is the non-focusable artifact tile (M5). All note (pass) DOM + AX src/app.js:6867-6881 (Send/Stop), 6765-6777 (Attach), 1076-1088 (Dismiss)
N4 Composer keyboard works. Shift+Enter inserted a newline ("line one\n"); Enter on an empty draft sent nothing and did not change the transcript. Code confirms Enter submits only through composerSubmit. Enter-with-text was not sent live (to avoid writing to the operator's chat). Chat composer note (pass) DOM for Shift+Enter/empty Enter; code for Enter-with-text onComposerKeydown src/app.js:5085-5100
N5 URL deep links route correctly. /runs/438 and /runs/438/stage/implementer opened the run and stage pane; /pipelines/20 and /pipelines/20/10 opened the detail; /settings/templates and /templates are aliases; /runs/not-a-number fell back to /pipelines. The stage pane opened with its dialog label and Escape returned to /runs/438. Deep links note (pass) DOM src/routes.js; src/app.js:7539-7551
N6 Reduced motion is partial. The graph halo and search progress both become animation: none under emulation; only the spinner is missed (S12). Graph, Search, spinners note DOM (emulation) styles.css:662-664, 1296-1298
N7 The approval card was not reachable live. No permission was pending on the live server, so its findings (S8) are code-read; its controls are labelled text buttons and the risk panel is not colour-only. Chat approval note (limit) Code src/app.js:6152-6220
N8 The decision sheet was not reachable live. No waiting run existed, so S9 is code-read. Run decision sheet note (limit) Code src/app.js:3487-3620
N9 Focus rings are otherwise visible. Every other tabbed control showed Chrome's outline: auto 1px rgb(153, 200, 255); chat/change rows show a 2px accent ring. Timeline is the sole missing ring (M9). The inputs that set outline: none (decision feedback, template name, rename) still change their border to --accent. All note DOM (real Tab walk) styles.css:790, 1334, 1408, 1430, 1526, 2046
N10 Markdown headings inside Chat start at h4/h5 under the h2 chat title, so the in-transcript outline skips levels. This is content-generated, but the page outline fix (M8) should account for it. Chat transcript note DOM renderMarkdownBlock src/app.js:6590-6595
N11 The video artifact poster's ▶ is plain text, not aria-hidden. The tile has no accessible name anyway (M5); after M5 the glyph should be decorative. Artifacts note DOM src/app.js:3922-3925
N12 html lang="en" is present, and there is one main landmark. The single nav has no aria-label (minor; M3 adds one). All note DOM index.html:2; src/app.js:1244-1257
N13 Search results use aria-live="polite" and the Settings notification state uses role="status"; both are present and correctly scoped. The Settings URL error sets aria-invalid + role="alert"; the workspace field sets aria-invalid and a described helper, but that helper is not a live region (minor). Search, Settings note (pass) DOM src/app.js:7309, 1544, 1564-1565, 1573-1582
N14 Dialogs do expose a name: every role="dialog" had an aria-label (or a titled heading). The gap is focus management, not naming. The stage pane's name is only the stage key (implementer), so "Stage: implementer, run 438" would be clearer. All dialogs note AX src/app.js:1014, 3248, 3520, 3666
N15 The Dismiss, Chat actions, Copy link and Share name collisions are real AX-tree duplicates, not just visual repeats. They are listed as M6/M7/S10; Disconnect is S11. Runs/Chat/Artifacts/Settings note AX see M6/M7/S10/S11

Escape and focus-return matrix

Overlay Escape closes it? Where focus goes afterwards Evidence
Needs you sheet yes #attentionBell (correct) DOM
Stage pane yes the originating timeline row (correct) DOM
Changes viewer yes the originating change row (correct) DOM
Artifact viewer yes body — no restore DOM
Confirm (Retry/Cancel/Restart) yes body — no restore DOM
Chat actions menu yes body — no restore DOM
Chat Rename dialog yes body — no restore DOM
Search panel yes body — no restore DOM
Pipelines Filter / Sort no — stays open focus remains wherever it was (body in the test) DOM
Runs Filter / Sort no — stays open focus remains wherever it was (body in the test) DOM
Decision sheet yes (code) Decide card button (code) code
Chat Close confirm yes (code) no explicit restore (code) code
Action failed yes (code) no explicit restore (code) code
Template create yes (code) no explicit restore (code) code

Evidence and method

Real DOM / accessibility-tree checks

  • Accessible names: 7 controls queried with Accessibility.getPartialAXTree on /runs/438; chat row, menu button, composer, Send, attention row/dismiss, settings fields, search row and input queried in follow-up runs. This is how the header URL placeholder name, the nested "Chat actions" name, the empty artifact-tile name and the duplicate Dismiss names were confirmed.
  • Tab order and focus rings: real CDP Input.dispatchKeyEvent Tab presses with computed outline/background comparison against each element's unfocused style. The focus-distance numbers (351/29/43) come from the actual focusable order.
  • Dialogs: opened the attention sheet, stage pane, Changes viewer, artifact viewer, confirm, chat menu and Rename dialog; focused their first/last controls and pressed Tab/Shift+Tab; measured [inert], aria-hidden, active element and post-Escape active element.
  • Composer: Shift+Enter and empty-Enter were sent through CDP with real key events; the draft was restored.
  • Reduced motion: Emulation.setEmulatedMedia with prefers-reduced-motion: reduce; matchMedia confirmed true and computed animation names were read.
  • Contrast: computed colours from the live page and the WCAG relative luminance formula; --surface, --surface-2 and --bg were all checked.

Code-read only (unreachable or deliberately not exercised)

  • Decision sheet (S9): no waiting run on the live server.
  • Approval card (N7/S8): no pending chat_permission.
  • Chat Close confirm / Action failed / template create: read from source and not opened/confirmed, to avoid a state change and because the dialogs are not on the required screen list. Their focus behaviour follows the same pattern as the measured dialogs.
  • Enter-with-text in the composer (N4): intentionally not sent; the handler is read from source.
  • Artifact tile keyboard failure (M5): confirmed by DOM/AX (role=generic, no tabindex, no key handler), not by attempting a keyboard activation.

Commands run

cd /Users/alan/repos/pipelines/web
node serve.mjs --host 127.0.0.1 --port 8097 --pipelines 127.0.0.1:8080
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8097/

# Read-only audit scripts (outside the repo) importing web/test/browser.mjs
node /tmp/a11y/explore.mjs
node /tmp/a11y/audit.mjs
node /tmp/a11y/targeted.mjs
node /tmp/a11y/targeted2.mjs
node /tmp/a11y/targeted3.mjs

The audit scripts imported web/test/browser.mjs without modifying it. They launched the installed Chrome headless at 1440×900 and used a fresh profile. Raw capture files: /tmp/a11y/audit.json, /tmp/a11y/targeted.json, /tmp/a11y/targeted2.json.

One-item must-fix checklist

  1. Add the shared dialog controller (M1/M2) and convert every role="dialog" to use it: focus entry, Tab trap, inert background, Escape/backdrop, focus return.
  2. Convert top-level and detail tabs to tablist/tab/tabpanel with aria-selected, roving tabindex and arrow keys (M3).
  3. Add the skip link and move focus to the detail heading after a list row is activated (M4).
  4. Turn artifact tiles into real buttons with Open {name} names (M5).
  5. Restructure the chat row so the session and its actions are siblings; give every actions and Dismiss control a unique name (M6/M7).
  6. Add one h1 per route and an h2 for each list view (M8).
  7. Restore a visible focus ring on .timeline-row (M9).
  8. Re-run node --test test/, node test/ui-smoke.mjs and a short AX/Tab spot-check on the changed screens; add regression assertions for the dialog trap, tab roles and artifact-tile keyboard activation.