# 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
Skip to content
```
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 `