From 8880495970cfa23d4985b9438c99c45750fdc44b Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Mon, 19 Oct 2026 16:33:59 +0100 Subject: [PATCH] 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. --- web/design/layout/capture.mjs | 48 ++ web/design/layout/prototype.css | 801 +++++++++++++++++++++++++++++++ web/design/layout/prototype.html | 470 ++++++++++++++++++ web/docs/a11y-audit.md | 206 ++++++++ web/docs/layout-spec.md | 574 ++++++++++++++++++++++ 5 files changed, 2099 insertions(+) create mode 100644 web/design/layout/capture.mjs create mode 100644 web/design/layout/prototype.css create mode 100644 web/design/layout/prototype.html create mode 100644 web/docs/a11y-audit.md create mode 100644 web/docs/layout-spec.md diff --git a/web/design/layout/capture.mjs b/web/design/layout/capture.mjs new file mode 100644 index 00000000..3dd5ef48 --- /dev/null +++ b/web/design/layout/capture.mjs @@ -0,0 +1,48 @@ +// Capture the L2–L4 layout prototype through the repository's zero-dependency +// Chrome DevTools driver. Read-only import: web/test/browser.mjs is not modified. +// +// node web/design/layout/capture.mjs +// +// Writes PNGs into web/design/layout/captures/ (gitignored by the root +// `captures/` rule). No server is started; the prototype is a local file. + +import { mkdir } from "node:fs/promises"; +import { dirname, join } from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { launchChrome } from "../../test/browser.mjs"; + +const here = dirname(fileURLToPath(import.meta.url)); +const outDir = join(here, "captures"); +const prototype = pathToFileURL(join(here, "prototype.html")); + +const shots = [ + { hash: "wide", width: 1440, height: 900, name: "wide-pipelines-1440x900.png" }, + { hash: "runs", width: 420, height: 900, name: "narrow-runs-420x900.png" }, + { hash: "detail", width: 420, height: 900, name: "narrow-run-detail-420x900.png" }, +]; + +await mkdir(outDir, { recursive: true }); + +const browser = await launchChrome({ width: 1440, height: 900 }); +try { + for (const shot of shots) { + const page = await browser.openPage(`${prototype.href}#${shot.hash}`, { + width: shot.width, + height: shot.height, + }); + await page.waitForSelector(`#${shot.hash}`); + await page.evaluate("document.fonts.ready.then(() => true)"); + await new Promise((resolve) => setTimeout(resolve, 150)); + const box = await page.evaluate(`(() => { + const node = document.querySelector("#${shot.hash} .app-shell"); + const rect = node.getBoundingClientRect(); + return { width: Math.round(rect.width), height: Math.round(rect.height) }; + })()`); + const path = join(outDir, shot.name); + await page.screenshot(path); + console.log(`${shot.name}: viewport ${shot.width}x${shot.height}, shell ${box.width}x${box.height}`); + await page.close(); + } +} finally { + await browser.close(); +} diff --git a/web/design/layout/prototype.css b/web/design/layout/prototype.css new file mode 100644 index 00000000..033c7db5 --- /dev/null +++ b/web/design/layout/prototype.css @@ -0,0 +1,801 @@ +/* ─────────────────────────────────────────────────────────────────────────── + Pipelines web — L2–L4 layout prototype + The app palette below is copied verbatim from web/styles.css :root. + The rules from "App shell" to "Reduced motion" are the reference layout; + everything under "Prototype chrome" is for this static mock only. + ─────────────────────────────────────────────────────────────────────────── */ + +/* App palette — verbatim from web/styles.css. */ +:root { + color-scheme: dark; + --bg: #0e1513; + --surface: #171f1d; + --surface-2: #1f2a27; + --border: #2c3a36; + --text: #e2e8e6; + --muted: #9db0ab; + --accent: #7fd1bb; + --ok: #6bd39a; + --warn: #e6c268; + --bad: #ef8a8a; +} + +/* Named layout tokens, mirroring android/app/src/main/java/net/awan/pipelines/ + ui/theme/Dimens.kt (WIDE_RAIL_WIDTH_DP = 200, SPACING_* = 4/8/12/16). */ +:root { + --rail-width: 200px; + --list-min-width: 200px; + --list-max-width: 360px; + --dock-height: 60px; + --hairline: 1px; + --dock-clearance: calc(var(--dock-height) + env(safe-area-inset-bottom, 0px)); + --radius-s: 8px; + --radius-m: 10px; + --radius-l: 12px; + --space-xs: 4px; + --space-s: 8px; + --space-m: 12px; + --space-l: 16px; + --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; +} + +* { box-sizing: border-box; } + +html, body { height: 100%; } + +body { + margin: 0; + background: var(--bg); + color: var(--text); + font: 14px/1.45 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; + -webkit-font-smoothing: antialiased; +} + +button, a { font: inherit; } +button { color: inherit; } +a { color: inherit; } + +.icon { + width: 20px; + height: 20px; + flex: 0 0 auto; +} + +.icon-sprite { + position: absolute; + width: 0; + height: 0; + overflow: hidden; +} + +:where(a, button, [tabindex]):focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} + +.skip-link { + position: absolute; + top: -80px; + left: var(--space-l); + z-index: 100; + padding: var(--space-s) var(--space-m); + border-radius: var(--radius-s); + background: var(--surface-2); + color: var(--text); + text-decoration: none; +} +.skip-link:focus { top: var(--space-l); } + +/* ── App shell ────────────────────────────────────────────────────────────── + Narrow is the default: one grid cell, one pane at a time, and clearance for + the fixed destination bar. The wide media query at exactly 600px turns the + same shell into the 200px rail + two panes. No other breakpoint is used. */ + +.screen { + display: none; + height: 100dvh; + min-height: 0; +} +.screen:target { display: block; } +body:not(:has(.screen:target)) #wide { display: block; } +body:has(.screen:target) .proto-nav { display: none; } + +.app-shell { + position: relative; + height: 100dvh; + min-height: 0; + overflow: hidden; + display: grid; + grid-template-columns: minmax(0, 1fr); + grid-template-rows: minmax(0, 1fr); + grid-template-areas: "workspace"; + padding-top: env(safe-area-inset-top, 0px); + padding-bottom: var(--dock-clearance); + background: var(--bg); +} + +.workspace { + grid-area: workspace; + min-width: 0; + min-height: 0; + display: grid; + grid-template-columns: minmax(0, 1fr); + grid-template-rows: minmax(0, 1fr); + grid-template-areas: "main"; +} + +/* The 200px rail is the wide-only destination and section index. */ +.app-rail { display: none; } + +.list-pane, +.detail-pane { + grid-area: main; + min-width: 0; + min-height: 0; + overflow: hidden; + display: none; + flex-direction: column; + background: var(--bg); +} + +.app-shell[data-active-pane="list"] .list-pane { display: flex; } +.app-shell[data-active-pane="detail"] .detail-pane { display: flex; } + +/* ── Wide: left rail + list/detail panes ──────────────────────────────────── + The single breakpoint. widthDp >= 600 is isWideLayout() in WindowSize.kt; + in the browser the same predicate is (min-width: 600px). */ + +@media (min-width: 600px) { + .app-shell:not(.app-shell--phone) { + grid-template-columns: var(--rail-width) minmax(0, 1fr); + grid-template-areas: "rail workspace"; + padding-bottom: 0; + } + + .app-shell:not(.app-shell--phone) .app-rail { display: flex; } + + .app-shell:not(.app-shell--phone) .workspace { + grid-template-columns: minmax(var(--list-min-width), var(--list-max-width)) minmax(0, 1fr); + grid-template-areas: "list detail"; + } + + .app-shell:not(.app-shell--phone) .list-pane { + grid-area: list; + display: flex; + border-right: var(--hairline) solid var(--border); + } + + .app-shell:not(.app-shell--phone) .detail-pane { + grid-area: detail; + display: flex; + } + + /* Wide windows use the rail for sections; the strip is a narrow affordance. */ + .app-shell:not(.app-shell--phone) .section-strip { display: none; } + + /* Wide windows use the rail for destinations; no bottom bar is in flow or + drawn. The bar never gets a grid row in either layout. */ + .app-shell:not(.app-shell--phone) .destination-dock { display: none; } +} + +/* ── Left rail ────────────────────────────────────────────────────────────── + Width is owned by the grid (200px), never by the rail's contents. */ + +.app-rail { + flex-direction: column; + min-width: 0; + min-height: 0; + padding: var(--space-m) var(--space-s); + background: var(--surface); + border-right: var(--hairline) solid var(--border); +} + +.rail-brand { + display: flex; + align-items: center; + gap: var(--space-s); + min-height: 44px; + padding: 0 var(--space-m); + margin-bottom: var(--space-m); + font-size: 15px; + font-weight: 650; + letter-spacing: -0.01em; +} + +.brand-mark { + width: 18px; + height: 18px; + border-radius: 6px; + background: linear-gradient(135deg, var(--accent), var(--ok)); + box-shadow: 0 0 0 4px rgba(127, 209, 187, 0.10); +} + +.rail-destinations { + display: flex; + flex-direction: column; + gap: 2px; +} + +.rail-item, +.rail-tab { + min-height: 44px; + display: flex; + align-items: center; + gap: var(--space-m); + padding: 0 var(--space-m); + border: 0; + border-radius: var(--radius-s); + background: transparent; + color: var(--muted); + text-align: left; + text-decoration: none; + cursor: pointer; +} + +.rail-item:hover, +.rail-tab:hover { + background: var(--surface-2); + color: var(--text); +} + +.rail-item[aria-current="page"], +.rail-tab[aria-selected="true"] { + color: var(--text); + background: rgba(127, 209, 187, 0.12); + box-shadow: inset 2px 0 0 var(--accent); + font-weight: 600; +} + +.rail-divider { + height: var(--hairline); + margin: var(--space-m) var(--space-s); + background: var(--border); +} + +.rail-heading { + margin: 0 0 var(--space-s); + padding: 0 var(--space-m); + color: var(--muted); + font-size: 11px; + font-weight: 600; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.rail-tablist { + display: flex; + flex-direction: column; + gap: 2px; +} + +.rail-footer { + margin-top: auto; + display: flex; + align-items: center; + gap: var(--space-s); + min-height: 44px; + padding: 0 var(--space-m); + color: var(--muted); + font-size: 12px; +} + +/* ── Panes ──────────────────────────────────────────────────────────────── */ + +.pane-header { + flex: 0 0 auto; + min-height: 64px; + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-m); + padding: var(--space-s) var(--space-l); + border-bottom: var(--hairline) solid var(--border); + background: var(--bg); +} + +.eyebrow { + margin: 0 0 2px; + color: var(--muted); + font-size: 11px; + font-weight: 600; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.pane-header h1 { + margin: 0; + font-size: 18px; + line-height: 1.2; + letter-spacing: -0.01em; +} + +.count-chip { + min-width: 30px; + padding: 2px 9px; + border: var(--hairline) solid var(--border); + border-radius: 999px; + color: var(--muted); + font-size: 12px; + text-align: center; +} + +.list-tools { + flex: 0 0 auto; + display: flex; + align-items: center; + gap: var(--space-xs); + padding: var(--space-s) var(--space-m); + border-bottom: var(--hairline) solid var(--border); +} + +.tool-button { + min-height: 32px; + padding: 0 10px; + border: var(--hairline) solid var(--border); + border-radius: var(--radius-s); + background: var(--surface-2); + color: var(--text); + font-size: 12px; + cursor: pointer; +} +.tool-button:hover { border-color: var(--accent); } + +.tool-spacer { flex: 1 1 auto; } + +.live-badge { + display: inline-flex; + align-items: center; + gap: 6px; + color: var(--ok); + font-size: 11px; + font-weight: 600; +} + +.status-dot { + width: 7px; + height: 7px; + flex: 0 0 auto; + border-radius: 50%; + background: var(--ok); + box-shadow: 0 0 0 3px rgba(107, 211, 154, 0.12); +} +.status-dot--ok { background: var(--ok); } + +.list-scroll, +.pane-scroll { + flex: 1 1 auto; + min-height: 0; + overflow: auto; + overscroll-behavior: contain; + scrollbar-gutter: stable; +} + +.list-scroll { padding: var(--space-s); } +.pane-scroll { padding: var(--space-l); } + +.day-heading { + margin: var(--space-s) var(--space-s) var(--space-xs); + color: var(--muted); + font-size: 11px; + font-weight: 600; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.row-list { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-direction: column; + gap: 2px; +} + +.row { + width: 100%; + display: grid; + grid-template-columns: minmax(0, 1fr) auto; + grid-template-areas: + "title chip" + "meta meta" + "last last"; + gap: 3px var(--space-s); + padding: 10px var(--space-m); + border: var(--hairline) solid transparent; + border-radius: var(--radius-m); + background: transparent; + color: var(--text); + text-align: left; + cursor: pointer; +} + +.row:hover { + background: var(--surface); + border-color: var(--border); +} + +.row.is-selected, +.row[aria-current="true"] { + background: var(--surface-2); + border-color: var(--border); + box-shadow: inset 2px 0 0 var(--accent); +} + +.row-title { + grid-area: title; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + font-weight: 600; +} + +.row .chip { grid-area: chip; align-self: start; } + +.row-meta, +.row-last { + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + color: var(--muted); + font-size: 12px; + font-variant-numeric: tabular-nums; +} +.row-meta { grid-area: meta; } +.row-last { grid-area: last; } + +.chip { + display: inline-flex; + align-items: center; + gap: 5px; + min-height: 22px; + padding: 1px 8px; + border: var(--hairline) solid var(--border); + border-radius: 999px; + background: var(--surface-2); + color: var(--muted); + font-size: 11px; + font-weight: 600; + line-height: 1.2; + white-space: nowrap; +} +.chip::before { + content: ""; + width: 6px; + height: 6px; + border-radius: 50%; + background: currentColor; +} +.chip--ok { color: var(--ok); border-color: rgba(107, 211, 154, 0.30); background: rgba(107, 211, 154, 0.10); } +.chip--bad { color: var(--bad); border-color: rgba(239, 138, 138, 0.32); background: rgba(239, 138, 138, 0.10); } +.chip--warn { color: var(--warn); border-color: rgba(230, 194, 104, 0.30); background: rgba(230, 194, 104, 0.10); } + +/* ── Detail ─────────────────────────────────────────────────────────────── */ + +.detail-header { + align-items: flex-start; + flex-wrap: wrap; + padding-top: var(--space-m); + padding-bottom: var(--space-m); +} + +.detail-heading { min-width: 0; } + +.detail-title-row { + display: flex; + align-items: center; + gap: var(--space-s); + flex-wrap: wrap; +} + +.detail-subtitle { + margin: 4px 0 0; + color: var(--muted); + font-size: 12px; + font-variant-numeric: tabular-nums; +} + +.detail-actions { + display: flex; + gap: var(--space-xs); + margin-left: auto; +} + +.card { + padding: var(--space-m) var(--space-l); + border: var(--hairline) solid var(--border); + border-radius: var(--radius-l); + background: var(--surface); +} +.card + .card { margin-top: var(--space-m); } + +.card h2 { + margin: 0 0 var(--space-m); + color: var(--muted); + font-size: 11px; + font-weight: 600; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.kv { + display: grid; + grid-template-columns: minmax(92px, 140px) minmax(0, 1fr); + gap: 8px var(--space-m); + margin: 0; +} +.kv div { display: contents; } +.kv dt { color: var(--muted); font-size: 12px; } +.kv dd { + margin: 0; + min-width: 0; + overflow-wrap: anywhere; + font-size: 13px; + font-variant-numeric: tabular-nums; +} + +code { + font-family: var(--font-mono); + font-size: 12px; + color: var(--text); +} + +.inline-status { + display: inline-flex; + align-items: center; + gap: 6px; +} + +.stage-list, +.version-list { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-direction: column; + gap: 2px; +} + +.stage-list li, +.version-list li { + display: flex; + align-items: center; + gap: var(--space-m); + min-height: 34px; + padding: 0 var(--space-s); + border-radius: var(--radius-s); +} +.stage-list li:hover, +.version-list li:hover { background: var(--surface-2); } + +.stage-index { + width: 22px; + height: 22px; + display: grid; + place-items: center; + border-radius: 50%; + background: var(--surface-2); + color: var(--muted); + font-size: 11px; + font-variant-numeric: tabular-nums; +} + +.stage-name { flex: 1 1 auto; font-weight: 550; } +.stage-type, +.muted { color: var(--muted); } +.stage-type { font-size: 12px; } + +.version-tag { + min-width: 38px; + color: var(--accent); + font-family: var(--font-mono); + font-size: 12px; +} +.version-list .muted { margin-left: auto; font-size: 12px; } +.small { font-size: 12px; } + +.mobile-header { + gap: var(--space-s); + justify-content: flex-start; +} + +.icon-button { + width: 44px; + height: 44px; + flex: 0 0 auto; + display: grid; + place-items: center; + border: var(--hairline) solid transparent; + border-radius: var(--radius-m); + background: transparent; + color: var(--muted); + cursor: pointer; +} +.icon-button:hover { + background: var(--surface-2); + border-color: var(--border); + color: var(--text); +} + +.disclosure { + width: 100%; + min-height: 44px; + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-m); + padding: 0 var(--space-s); + border: 0; + border-radius: var(--radius-s); + background: var(--surface-2); + color: var(--text); + text-align: left; + cursor: pointer; +} +.disclosure:hover { box-shadow: inset 0 0 0 1px var(--border); } +.disclosure-chevron { width: 16px; height: 16px; color: var(--muted); } + +/* ── Narrow section strip ───────────────────────────────────────────────── + Sits in normal flow at the foot of the detail pane, directly above the + fixed destination bar's reserved clearance. The entries are the same + DetailTab keys the wide rail renders, so section state is not duplicated. */ + +.section-strip { + flex: 0 0 auto; + display: flex; + align-items: center; + min-width: 0; + padding: 6px var(--space-s); + background: var(--surface); + border-top: var(--hairline) solid var(--border); + overflow-x: auto; + overflow-y: hidden; + overscroll-behavior-x: contain; + scrollbar-width: none; +} +.section-strip::-webkit-scrollbar { display: none; } + +.strip-tablist { + display: flex; + align-items: center; + gap: 2px; + min-width: 0; +} + +.strip-tab { + flex: 0 0 auto; + min-height: 44px; + display: inline-flex; + align-items: center; + gap: 4px; + padding: 0 var(--space-s); + border: var(--hairline) solid transparent; + border-radius: var(--radius-s); + background: transparent; + color: var(--muted); + font-size: 12px; + white-space: nowrap; + cursor: pointer; +} +.strip-tab .icon { width: 17px; height: 17px; } + +.strip-tab:hover { + background: var(--surface-2); + color: var(--text); +} + +.strip-tab[aria-selected="true"] { + background: var(--surface-2); + border-color: var(--border); + box-shadow: inset 0 -2px 0 var(--accent); + color: var(--text); + font-weight: 600; +} + +/* ── Bottom destination bar ─────────────────────────────────────────────── + A true overlay: position fixed, no grid row, no layout height. The shell + reserves --dock-clearance as padding so the strip and pane end above it. */ + +.destination-dock { + position: fixed; + inset: auto 0 0 0; + z-index: 30; + height: calc(var(--dock-height) + env(safe-area-inset-bottom, 0px)); + display: flex; + align-items: stretch; + gap: var(--space-xs); + padding: var(--space-xs) var(--space-s) + calc(var(--space-xs) + env(safe-area-inset-bottom, 0px)); + background: var(--surface); + border-top: var(--hairline) solid var(--border); +} + +.dock-item { + flex: 1 1 0; + min-width: 0; + min-height: 48px; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: 2px; + padding: 2px 0; + border-radius: var(--radius-s); + color: var(--muted); + font-size: 11px; + text-decoration: none; +} +.dock-item .icon { width: 21px; height: 21px; } +.dock-item:hover { background: var(--surface-2); color: var(--text); } +.dock-item[aria-current="page"] { + color: var(--accent); + background: rgba(127, 209, 187, 0.10); +} + +/* ── Reduced motion ─────────────────────────────────────────────────────── + The wide/narrow switch is instant. If a transition is added to the rail, + strip, dock or pane entry, it collapses here; no lateral slide, scale or + smooth scrolling is allowed. */ + +@media (prefers-reduced-motion: reduce) { + *, + *::before, + *::after { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + scroll-behavior: auto !important; + } +} + +/* ── Prototype chrome (not part of the implementation) ─────────────────── */ + +.proto-nav { + position: fixed; + top: 12px; + left: 50%; + transform: translateX(-50%); + z-index: 90; + display: flex; + align-items: center; + gap: 6px; + padding: 6px; + border: var(--hairline) solid var(--border); + border-radius: 999px; + background: rgba(23, 31, 29, 0.92); + box-shadow: 0 10px 30px rgba(0, 0, 0, 0.45); + backdrop-filter: blur(8px); + font-size: 12px; +} +.proto-nav a { + padding: 5px 10px; + border-radius: 999px; + color: var(--muted); + text-decoration: none; +} +.proto-nav a:hover { background: var(--surface-2); color: var(--text); } +.proto-title { + padding: 0 8px; + color: var(--text); + font-weight: 650; +} +.proto-hint { + padding: 0 8px 0 4px; + color: var(--muted); +} + +/* The two narrow states are phone-width states. This class keeps them at + 420px while the page is previewed on a desktop; it is not part of the + responsive rule (the real shell has no such class). */ +.app-shell--phone { + position: relative; + width: 100%; + max-width: 420px; + margin-inline: auto; + box-shadow: 0 0 0 1px var(--border), 0 30px 90px rgba(0, 0, 0, 0.55); +} + +@media (min-width: 600px) { + .app-shell--phone .destination-dock { position: absolute; } +} diff --git a/web/design/layout/prototype.html b/web/design/layout/prototype.html new file mode 100644 index 00000000..b12fa6d1 --- /dev/null +++ b/web/design/layout/prototype.html @@ -0,0 +1,470 @@ + + + + + + Pipelines web — L2–L4 layout prototype + + + + + + + + + +
+ +
+ + +
+
+
+
+

Workspace

+

Pipelines

+
+ 12 +
+ +
+ + + + live +
+ +
+
    +
  • + +
  • +
  • + +
  • +
  • + +
  • +
  • + +
  • +
  • + +
  • +
+
+
+ +
+
+
+

Pipeline

+
+

Plan and land

+ succeeded +
+

id 24 · v5 · 6 stages · latest version v5

+
+
+ + +
+
+ +
+
+

Summary

+
+
Latest version
v5
+
Content hash
sha256:9f2c41e8a7
+
Created
12 Oct 2026 09:14
+
Updated
19 Oct 2026 14:32
+
Last run
succeeded · run 458 · 12m
+
+
+ +
+

Stages

+
    +
  1. 1planagent
  2. +
  3. 2implementagent
  4. +
  5. 3reviewagent
  6. +
  7. 4landshell
  8. +
+
+ +
+

Versions

+
    +
  • v519 Oct 14:31latest
  • +
  • v418 Oct 16:086 stages
  • +
  • v316 Oct 11:225 stages
  • +
+
+
+
+
+ + +
+
+ + +
+ +
+
+
+
+
+

Workspace

+

Runs

+
+ live +
+ +
+ + + + 12 runs +
+ +
+

Today

+
    +
  • + +
  • +
  • + +
  • +
  • + +
  • +
+ +

Yesterday

+
    +
  • + +
  • +
  • + +
  • +
+
+
+
+ + +
+
+ + +
+ +
+
+ + +
+
+ +
+

Run

+
+

Plan and land

+ succeeded +
+

run 458 · v5 · 12m

+
+
+ +
+
+

Status

+
+
Status
succeeded
+
Started
19 Oct 2026 14:20
+
Finished
19 Oct 2026 14:32
+
Duration
12m
+
+
+ +
+

Run

+
+
Pipeline
24 · v5
+
Stage
land
+
Visits
6 recorded
+
Workspace
/Users/alan/repos/pipelines
+
Content hash
sha256:9f2c41e8a7
+
+
+ +
+

Changes

+ +
+
+ + +
+
+ + +
+
+ + diff --git a/web/docs/a11y-audit.md b/web/docs/a11y-audit.md new file mode 100644 index 00000000..4fdaef8d --- /dev/null +++ b/web/docs/a11y-audit.md @@ -0,0 +1,206 @@ +# 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 ` + + + + + + + + +
+ +
…
+ + +
+
…
+ +
…
+ + +
+
+ + + + + +``` + +Rules for the two section mounts: + +- Render only the mount appropriate to the current width, **or** render both and + give each unique ids. In the latter case the hidden mount must be + `display: none` (not merely transparent), so only one tablist is in the + accessibility tree. Never leave two visible tablists. +- `aria-controls` always names the one panel id (`detail-panel`). +- The panel's `aria-labelledby` names the tab id of the **visible** mount. +- A pipeline detail has `Summary`, `Graph`, `Source`; a run detail has + `Summary`, `Graph`, `Input`, `Output`, `Timeline`. Order is the Android + `runDetailTabs` / `pipelineDetailTabs` order; Summary is the default. +- The strip is rendered only when the detail has more than one section + (`selectorStripShown(entryCount) = entryCount > 1`). A list-only screen has + no strip. + +Pane selection: + +- `data-active-pane="list" | "detail"` is the narrow single-pane switch. +- On wide both panes are shown and the attribute is ignored. +- On narrow the inactive pane is `display: none`; if it is kept mounted for a + transition, also set `inert` and `aria-hidden="true"` while covered. +- Selecting a row sets `detail`; Back sets `list` and restores focus to the + originating row. `open`/`close` also updates the URL route, not a local-only + class. + +--- + +## 3. CSS the implementer should produce + +The rules below are the layout contract. Visual finish (tones, radii, chip +styles, icon sizing) can follow `prototype.css`; the grid/flex and overflow +rules should be kept as written. + +```css +.app-root { + display: flex; + flex-direction: column; + height: 100vh; + height: 100dvh; + min-height: 0; +} + +/* Narrow is the default layout. */ +.app-shell { + position: relative; + flex: 1 1 auto; + min-height: 0; + overflow: hidden; + display: grid; + grid-template-columns: minmax(0, 1fr); + grid-template-rows: minmax(0, 1fr); + grid-template-areas: "workspace"; + padding-top: env(safe-area-inset-top, 0px); + padding-bottom: var(--dock-clearance); + background: var(--bg); +} + +.workspace { + grid-area: workspace; + min-width: 0; + min-height: 0; + display: grid; + grid-template-columns: minmax(0, 1fr); + grid-template-rows: minmax(0, 1fr); + grid-template-areas: "main"; +} + +.list-pane, +.detail-pane { + grid-area: main; + min-width: 0; + min-height: 0; + overflow: hidden; + display: none; + flex-direction: column; + background: var(--bg); +} + +.app-shell[data-active-pane="list"] .list-pane, +.app-shell[data-active-pane="detail"] .detail-pane { + display: flex; +} + +/* The one breakpoint: 600px. WindowSize.kt's isWideLayout(600) is true. */ +@media (min-width: 600px) { + .app-shell { + grid-template-columns: var(--rail-width) minmax(0, 1fr); + grid-template-rows: minmax(0, 1fr); + grid-template-areas: "rail workspace"; + padding-bottom: 0; + } + + .app-shell .app-rail { display: flex; } + + .app-shell .workspace { + grid-template-columns: minmax(var(--list-min-width), var(--list-max-width)) minmax(0, 1fr); + grid-template-areas: "list detail"; + } + + .app-shell .list-pane { + grid-area: list; + display: flex; + border-right: var(--hairline) solid var(--border); + } + + .app-shell .detail-pane { + grid-area: detail; + display: flex; + } + + .app-shell .section-strip { display: none; } + .app-shell .destination-dock { display: none; } +} +``` + +```css +:root { + --rail-width: 200px; /* WIDE_RAIL_WIDTH_DP */ + --list-min-width: 200px; + --list-max-width: 360px; + --dock-height: 60px; + --hairline: 1px; + --dock-clearance: calc(var(--dock-height) + env(safe-area-inset-bottom, 0px)); +} +``` + +Rail: + +```css +.app-rail { + display: none; /* narrow: destinations live in the dock */ + flex-direction: column; + min-width: 0; + min-height: 0; + padding: 12px 8px; + background: var(--surface); + border-right: var(--hairline) solid var(--border); +} +.rail-destinations, +.rail-tablist { display: flex; flex-direction: column; gap: 2px; } +.rail-item, +.rail-tab { + min-height: 44px; + display: flex; + align-items: center; + gap: 12px; + padding: 0 12px; + border: 0; + border-radius: 8px; + background: transparent; + color: var(--muted); + text-align: left; + text-decoration: none; +} +.rail-item[aria-current="page"], +.rail-tab[aria-selected="true"] { + color: var(--text); + background: rgba(127, 209, 187, 0.12); + box-shadow: inset 2px 0 0 var(--accent); + font-weight: 600; +} +.rail-footer { margin-top: auto; } +``` + +The rail's **width comes from the grid track** (`grid-template-columns: +var(--rail-width) …`), never from its contents. No collapse control, no hover +peek, no master-pane width constant. + +Panes and scroll: + +```css +.pane-header, +.list-tools, +.section-strip { flex: 0 0 auto; } + +.list-scroll, +.pane-scroll { + flex: 1 1 auto; + min-height: 0; + overflow: auto; + overscroll-behavior: contain; + scrollbar-gutter: stable; +} +``` + +Every grid/flex ancestor of a scroll container needs `min-height: 0`; without it +the pane pushes the socket shell taller instead of scrolling internally. + +Exactly one layer owns the top safe area. The prototype has no topbar, so the +shell owns it with `padding-top`; if the existing `.topbar` already applies +`safe-area-inset-top`, omit that padding from `.app-shell` so the inset is not +counted twice — the same rule Android's shell follows. + +Narrow section strip: + +```css +.section-strip { + display: flex; + align-items: center; + min-width: 0; + padding: 6px 8px; + background: var(--surface); + border-top: var(--hairline) solid var(--border); + overflow-x: auto; + overflow-y: hidden; + overscroll-behavior-x: contain; + scrollbar-width: none; +} +.section-strip::-webkit-scrollbar { display: none; } + +.strip-tablist { display: flex; align-items: center; gap: 2px; min-width: 0; } + +.strip-tab { + flex: 0 0 auto; + min-height: 44px; + display: inline-flex; + align-items: center; + gap: 4px; + padding: 0 8px; + border: 1px solid transparent; + border-radius: 8px; + background: transparent; + color: var(--muted); + font-size: 12px; + white-space: nowrap; +} +.strip-tab[aria-selected="true"] { + color: var(--text); + background: var(--surface-2); + border-color: var(--border); + box-shadow: inset 0 -2px 0 var(--accent); + font-weight: 600; +} +``` + +The strip is in flow at the foot of the detail pane. It scrolls horizontally +when the labels do not fit, never wraps and never hides a label. Five labels +fit at 420px in the prototype at this padding; a longer localisation must scroll +rather than truncate. + +Bottom destination bar: + +```css +.destination-dock { + position: fixed; + inset: auto 0 0 0; + z-index: 30; + height: calc(var(--dock-height) + env(safe-area-inset-bottom, 0px)); + display: flex; + gap: 4px; + padding: 4px 8px calc(4px + env(safe-area-inset-bottom, 0px)); + background: var(--surface); + border-top: var(--hairline) solid var(--border); +} +.dock-item { + flex: 1 1 0; + min-width: 0; + min-height: 48px; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: 2px; + border-radius: 8px; + color: var(--muted); + text-decoration: none; +} +.dock-item[aria-current="page"] { + color: var(--accent); + background: rgba(127, 209, 187, 0.10); +} +``` + +The bar has **no grid area and no reserved row**. It is fixed to the viewport +bottom, painted above the pane with `z-index`. The shell reserves its height as +`padding-bottom: var(--dock-clearance)`, so the strip and the last scrollable +row end above it. That padding is the only space the bar influences. On wide the +bar is `display: none`. + +If a future change lets the bar hide (for example during an open chat +conversation), set `--dock-clearance: 0px` at the same time; do not leave a +reserved band behind a hidden bar. + +--- + +## 4. Focus and ARIA + +- **Skip link** first in the shell, pointing at `#pane-main`. It is the first + tab stop and becomes visible on focus. +- **Landmarks**: rail `aside aria-label="Pipelines navigation"`, workspace + `main id="pane-main" tabindex="-1"`, destinations + `nav aria-label="Destinations"`, strip `nav aria-label="Run sections"`. +- **Destinations** are links (``), not tabs. The current one carries + `aria-current="page"`. Set it in both the rail and the dock; the hidden mount + is not exposed. +- **Section tabs** are `role="tab"` inside `role="tablist"`; the rail tablist is + `aria-orientation="vertical"`, the strip is horizontal. Selected tab has + `aria-selected="true"` and `tabindex="0"`; the rest have `tabindex="-1"` + (roving tabindex). Implement Left/Right/Up/Down/Home/End in JS. Selection is + conveyed by `aria-selected` and the container colour/inset underline, never + by colour alone. +- **Panels** are `role="tabpanel"`, `tabindex="0"`, + `aria-labelledby=""`, and are the only scrolling body of a + detail. Changing a section keeps each section's saved scroll under its stable + key. +- **Pane focus**: after opening a detail, move focus to the detail's `

` + (`tabindex="-1"`) or to `#pane-main`; on Back, return it to the row that + opened it. When narrow, the covered pane is `display:none` and, while + animating, `inert` + `aria-hidden="true"`. +- **Rows**: the whole row is a `