# 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
…
…
…
…
…
``` 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 `