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.
21 KiB
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.htmlandprototype.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) andui/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.
<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-controlsalways names the one panel id (detail-panel).- The panel's
aria-labelledbynames the tab id of the visible mount. - A pipeline detail has
Summary,Graph,Source; a run detail hasSummary,Graph,Input,Output,Timeline. Order is the AndroidrunDetailTabs/pipelineDetailTabsorder; 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 setinertandaria-hidden="true"while covered. - Selecting a row sets
detail; Back setslistand restores focus to the originating row.open/closealso 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.
.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; }
}
: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:
.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:
.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:
.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:
.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", workspacemain id="pane-main" tabindex="-1", destinationsnav aria-label="Destinations", stripnav aria-label="Run sections". - Destinations are links (
<a>), not tabs. The current one carriesaria-current="page". Set it in both the rail and the dock; the hidden mount is not exposed. - Section tabs are
role="tab"insiderole="tablist"; the rail tablist isaria-orientation="vertical", the strip is horizontal. Selected tab hasaria-selected="true"andtabindex="0"; the rest havetabindex="-1"(roving tabindex). Implement Left/Right/Up/Down/Home/End in JS. Selection is conveyed byaria-selectedand 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 isdisplay:noneand, while animating,inert+aria-hidden="true". - Rows: the whole row is a
<button>or<a>; selected row in wide carriesaria-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).
@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
web/design/layout/captures/wide-pipelines-1440x900.png
Narrow run detail — 420 × 900
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.
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
- 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. - 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-clearancewith it). - 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), aResizeObservermust write its height into--dock-clearance; CSS alone cannot feed a measured value back into the shell. - Roving tabindex, focus restoration and
inerton a covered pane are DOM behaviours; CSS expresses the visual selected state but not the keyboard model or focus return. - On-screen keyboard geometry: Android reads
WindowInsets.ime; the browser should useenv(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. - Device-width breakpoint semantics: Android reads
screenWidthDpfrom 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 substitutescreen.widthor 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.


