Files
pipelines/web/docs/layout-spec.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

575 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Pipelines web client — L2–L4 layout specification
Design-only deliverable for **L2 (wide: left rail + list/detail panes)**, **L3
(narrow: bottom section strip above the bottom destination bar)** and **L4
(responsive switch by viewport width)**. It does not change `web/src/app.js`,
`web/styles.css`, `web/index.html`, `web/test/**` or the Android app.
Read with:
- `web/design/layout/prototype.html` and `prototype.css` — the rendered mock and
the reference CSS.
- `web/design/layout/capture.mjs` — headless-Chrome capture of the mock.
- Android sources that define the same structure:
`ui/WindowSize.kt` (600dp predicate), `ui/components/DetailTabs.kt`
(200dp section rail, narrow strip), `ui/components/SelectorStrip.kt`
(bottom strip), `ui/DestinationBar.kt` (destinations) and
`ui/PipelinesApp.kt` (`pillVisible`, overlay, strip clearance).
Palette: copied verbatim from `web/styles.css` `:root` (`--bg`, `--surface`,
`--surface-2`, `--border`, `--text`, `--muted`, `--accent`, `--ok`, `--warn`,
`--bad`).
---
## 1. Layout contract
| | Narrow (viewport < 600 CSS px) | Wide (viewport ≥ 600 CSS px) |
| --- | --- | --- |
| Shell | one pane at a time | 200px left rail + list pane + detail pane |
| Section index | bottom strip inside the detail pane | vertical group in the left rail |
| Destinations | fixed bottom destination bar | left rail destination group |
| Detail strip | visible only on a detail pane, above the bar | hidden (the rail is the selector) |
| Bottom bar | `position: fixed`, out of flow | hidden |
| Pane scroll | `overflow: auto` inside the pane | same, per pane |
One breakpoint only: **600 CSS px**, expressed as
`@media (min-width: 600px)`. It is the web analogue of
`isWideLayout(widthDp) = widthDp >= WIDE_LAYOUT_MIN_WIDTH_DP` with
`WIDE_LAYOUT_MIN_WIDTH_DP = 600`. Do not add a second breakpoint, device
sniffing, `screen.width`, user-agent checks or a fixed device width.
At exactly 600px the columns are `200px | minmax(200px, 360px) | 1fr`; the
detail gets the remaining 200px. The rail never shrinks and never scrolls
horizontally; the list may use its 200–360px range.
`widthDp` and CSS px are both logical units. Browser zoom changes the CSS-px
viewport and therefore switches the layout, which is the intended analogue of a
window-size change.
---
## 2. DOM structure
Render one shell per app; the router fills the panes. The wide rail mount and
the narrow strip mount are alternate presentations of the **same** section tab
model (`DetailTab.key`), so the selected key must not change when the viewport
crosses 600px.
```html
<a class="skip-link" href="#pane-main">Skip to content</a>
<div class="app-root"> <!-- existing topbar + banner stay here -->
<header class="topbar">…</header> <!-- unchanged -->
<div class="connbar">…</div> <!-- existing connection banner, unchanged -->
<div class="app-shell" data-active-pane="detail">
<!-- Wide-only. Hidden by the base rules; display:flex from the 600px query. -->
<aside class="app-rail" aria-label="Pipelines navigation">
<div class="rail-brand">Pipelines</div>
<nav class="rail-destinations" aria-label="Destinations">
<a class="rail-item" href="/pipelines" aria-current="page">Pipelines</a>
<a class="rail-item" href="/runs">Runs</a>
<a class="rail-item" href="/chat">Chat</a>
<a class="rail-item" href="/settings">Settings</a>
</nav>
<div class="rail-divider" role="presentation"></div>
<div class="rail-sections">
<p class="rail-heading" id="rail-sections-label">Sections</p>
<div class="rail-tablist" role="tablist"
aria-labelledby="rail-sections-label" aria-orientation="vertical">
<button class="rail-tab" id="rail-tab-summary" type="button" role="tab"
aria-selected="true" aria-controls="detail-panel" tabindex="0">Summary</button>
<button class="rail-tab" id="rail-tab-graph" type="button" role="tab"
aria-selected="false" aria-controls="detail-panel" tabindex="-1">Graph</button>
<!-- Input, Output, Timeline for a run; Source for a pipeline. -->
</div>
</div>
<div class="rail-footer"><span class="status-dot"></span> Connected</div>
</aside>
<main class="workspace" id="pane-main" tabindex="-1">
<!-- List pane. Both panes exist; narrow shows exactly one. -->
<section class="list-pane" aria-label="Runs list">…</section>
<!-- Detail pane. Its section strip is narrow-only. -->
<section class="detail-pane" aria-label="Run detail">
<header class="pane-header detail-header">…</header>
<div class="pane-scroll" id="detail-panel" role="tabpanel"
aria-labelledby="rail-tab-summary" tabindex="0">…</div>
<nav class="section-strip" aria-label="Run sections">
<div class="strip-tablist" role="tablist" aria-label="Run sections">
<button class="strip-tab" id="strip-tab-summary" type="button" role="tab"
aria-selected="true" aria-controls="detail-panel" tabindex="0">Summary</button>
<button class="strip-tab" id="strip-tab-graph" type="button" role="tab"
aria-selected="false" aria-controls="detail-panel" tabindex="-1">Graph</button>
<button class="strip-tab" id="strip-tab-input" type="button" role="tab"
aria-selected="false" aria-controls="detail-panel" tabindex="-1">Input</button>
<button class="strip-tab" id="strip-tab-output" type="button" role="tab"
aria-selected="false" aria-controls="detail-panel" tabindex="-1">Output</button>
<button class="strip-tab" id="strip-tab-timeline" type="button" role="tab"
aria-selected="false" aria-controls="detail-panel" tabindex="-1">Timeline</button>
</div>
</nav>
</section>
</main>
<!-- Fixed overlay, narrow-only. No grid area. -->
<nav class="destination-dock" aria-label="Destinations">
<a class="dock-item" href="/pipelines">Pipelines</a>
<a class="dock-item" href="/runs" aria-current="page">Runs</a>
<a class="dock-item" href="/chat">Chat</a>
<a class="dock-item" href="/settings">Settings</a>
</nav>
</div>
</div>
```
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 (`<a>`), 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="<visible tab id>"`, 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 `<h1>`
(`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 `<button>` or `<a>`; selected row in wide carries
`aria-current="true"`. Nested status chips are text, not controls.
- **Touch targets**: 44px minimum (`min-height`) for rail items, tabs, dock
items and row actions; 48px for the dock item itself, matching the Android
platform minimum.
- Do not put `aria-hidden="true"` on focusable content that remains in flow.
- Preserve the existing search/attention/dialog focus traps; the layout rails
add no focusable content behind an open modal.
---
## 5. Reduced motion
The wide/narrow switch is instantaneous: no animated rail width, no sliding
list, no strip collapse. Section changes may cross-fade in place; they never
slide laterally (Android's `DetailTabs` is a tab swap, not a pager).
```css
@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;
}
}
```
Under reduced motion a pane navigation becomes an immediate swap, the active
indicator jumps rather than travels, and `scrollIntoView` uses `behavior:
"auto"`. Do not disable the selected state or the focus ring.
---
## 6. What moves into the bottom strip
Only the **detail section index**:
| Detail | Strip entries (in order) |
| --- | --- |
| Run | `Summary`, `Graph`, `Input`, `Output`, `Timeline` |
| Pipeline | `Summary`, `Graph`, `Source` |
Not in the strip: destinations, the back control, `Run`/`Refresh` actions, run
filters/sort, the attention bell, or chat composer controls. The top-level
destinations never share the strip; they are the rail on wide and the fixed bar
on narrow.
On wide the same entries render as the rail's `Sections` group. The active key
(`summary`, `graph`, `input`, `output`, `steps`, `source`) is the single source
of truth across both mounts.
---
## 7. Captures
Captured with `node web/design/layout/capture.mjs` through the repository's
read-only `web/test/browser.mjs` driver at device scale 1.
### Wide — 1440 × 900
![Wide pipelines: 200px rail, pipeline list, pipeline detail](../design/layout/captures/wide-pipelines-1440x900.png)
`web/design/layout/captures/wide-pipelines-1440x900.png`
### Narrow run detail — 420 × 900
![Narrow run detail: Summary/Graph/Input/Output/Timeline strip above the Pipelines/Runs/Chat/Settings bar](../design/layout/captures/narrow-run-detail-420x900.png)
`web/design/layout/captures/narrow-run-detail-420x900.png`
### Narrow runs list — 420 × 900
The list has no section selector, so no strip; the destination bar is still a
fixed overlay.
![Narrow runs list](../design/layout/captures/narrow-runs-420x900.png)
`web/design/layout/captures/narrow-runs-420x900.png`
Capture paths are gitignored by the repository's root `captures/` rule; the
PNGs are review evidence, not tracked source.
---
## 8. Android rules this layout cannot express in CSS alone
1. **Covered-pane compact geometry** (`SlidingPaneStack.kt`). Android measures
the compact identity (icon + shortest label + the live leading gesture inset)
and folds older levels into an edge's `"N more"` count; the active pane's
left edge is that measured region at every depth. CSS cannot measure text or
fold levels. This design avoids the peek entirely (wide shows the full list
beside the detail), as L2 asks. If covered peek strips are added later, JS
must measure and publish the width and the folded count.
2. **Destination visibility is route/state-dependent**
(`destinationPillVisible`). Android hides the pill on an open chat
conversation, an open run detail and an open pipeline detail; CSS cannot know
whether a conversation or detail is open. The brief explicitly asks for the
bar on the narrow run detail, so this design keeps it. Implementers who want
Android's exact predicate must compute it in JS (and clear
`--dock-clearance` with it).
3. **Measured strip height → bar offset** (`pillBottomOffset(stripHeight) =
SPACING_L + stripHeight`). With a fixed-height bar the CSS token is enough.
If the strip can grow (localisation, wrapping, a marker row), a
`ResizeObserver` must write its height into `--dock-clearance`; CSS alone
cannot feed a measured value back into the shell.
4. **Roving tabindex, focus restoration and `inert` on a covered pane** are DOM
behaviours; CSS expresses the visual selected state but not the keyboard
model or focus return.
5. **On-screen keyboard geometry**: Android reads `WindowInsets.ime`; the
browser should use `env(safe-area-inset-*)` plus
`<meta name="viewport" content="interactive-widget=resizes-content">` so the
shell shortens above the keyboard. This is a document/meta and viewport
concern, not a layout-grid rule.
6. **Device-width breakpoint semantics**: Android reads `screenWidthDp` from the
configuration; the browser uses the CSS viewport. At browser zoom, or with a
foldable's app-window width different from the physical screen, the two can
disagree. The CSS query is the correct web equivalent; do not substitute
`screen.width` or a user-agent check.
Two deliberate, documented deltas from the current Android shell:
- On wide, destinations live in the rail rather than in a floating bottom-right
pill. This is the L2 reading of “left rail + list/detail panes”.
- The wide layout shows the full list pane beside the detail rather than
Android's covered compact edge, per the same L2 wording. The destination bar
remains an overlay on narrow, so hiding/showing it never changes a grid
track.
No app code, stylesheet, markup or test was changed by this design item.