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

21 KiB
Raw Blame History

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.

<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.

.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", 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).

@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

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

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

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.