Console redesign stage 7: Breakpoints, themes and final docs

Read the parent issue #1425, the approved console plan, and ui/AGENTS.md; this stage depends on stages 1–6 and independent spec review. Start with ui/src/ds/foundation.css and the owned screens, then inspect e2e/console/layout.spec.ts and e2e/console/views.spec.ts plus the listed DESIGN.md and website sections. Done means the integrated stack passes the specified responsive, theme, accessibility, keyboard, reduced-motion, documentation, and screenshot checks and is reviewed for atomic delivery.

Part of #1425.

Scope

Deliver stage 7 of the approved console plan: Breakpoints, themes and final docs. This is a reviewable slice of the single feature stack, not permission to merge a partial console into main. The parent Shared values owns every cross-stage value/interface. No issue is claimed or ready until independent spec checking finishes.

In short

The operator gets breakpoints, themes and final docs in the approved visual style, with existing identity, session and action semantics. The parent defines render, holder and view-only behavior; quantities below are CSS pixels for layout and milliseconds for request waits unless explicitly stated otherwise.

flowchart LR
  O[Operator] --> P["Stage 7 page or shared UI — changed"]
  P --> S[Existing state hooks]
  S --> M[Pure view models]
  P --> D[Shared design components]
  S --> A[Existing API and live connection]

If this goes wrong, the operator sees a missing control, a misleading value or content that cannot be read at the selected window size.

Technical spec

Facts

Commit 3b8c44d104c88db7a5cdbf0abff40343642ff0b0.

#	Fact	Source
F1	The current foundation switches theme using prefers-color-scheme.	ui/src/ds/foundation.css:54-82
F2	The current browser lane has a 360px no-horizontal-scroll test.	e2e/console/views.spec.ts:109-126
F3	The lane already runs axe in both themes, but only on a subset of paths.	e2e/console/views.spec.ts:349-379
F4	System accessibility and CSP provider are centralized DS concerns.	ui/src/ds/provider.tsx:4-8
F5	The lane has full-response stubs to avoid ETag 304 bodies.	e2e/console/stub-answers.ts:6-13
F6	Playwright has named Chromium, Firefox and WebKit projects and a bounded test timeout.	playwright.config.ts:8-22
F7	Read-resource mapping distinguishes loading, refusal, unsupported and retained data.	ui/src/state/resource.ts:22-46
F8	API requests use a 10000ms default timeout, counted from request setup.	ui/src/data/api.ts:1-10

Modules touched

Searches: rg -n 'prefers-color-scheme|AxeBuilder|hasHorizontalScroll|WorkersTable' ui/src e2e/console src/contract returned 39 matching lines at the Facts commit. Opened the source surrounding the Facts rows and the stage's model/state/screen entry points. Scope is the explicit file ownership below, not a repository-wide redesign.

• ui/src/ds (integration cleanup)
• ui/src/screens (responsive integration only)
• e2e/console/views.spec.ts
• e2e/console/layout.spec.ts
• e2e/console/render-cases (final audit)
• docs/internal/DESIGN.md
• ui/AGENTS.md
• website/src/content/docs/docs/worker/console.mdx
• website/src/content/docs/docs/gateway/fleet-console.mdx
• website/src/content/docs/docs/using-devices/watching-the-screen.mdx
• website/src/content/docs/docs/worker/console.mdx and other described website pages, only the owned sections below.

Changed callers follow screen → state → model/data and screen → ds. The In short diagram shows those arrows. The task adds no daemon module or new module factory. DS exports are React components with plain props; new hooks reuse the existing providers.

Integrate only after stages 1–6 have passed review and joined the feature stack. Implement every responsive transition in DESIGN.md: KPI and tile grids yield, Overview right column stacks, Leases pane becomes drawer below the shared threshold, phone sidebar becomes a menu below its threshold, stacked tables and contained feeds. Inspect the threshold on both sides, including 1279/1280 and 767/768, plus required verification viewports. Preserve the pre-existing 360px usability check as a compatibility floor in addition to 390px.

Finalize derived light values with identical layout and accessible status/focus/ring/chart contrast, not an invented alternate design. No new theme storage/UI. Capture every reference state and every no-render page in both schemes; reference dark remains the approved renders. Run axe on every listed page, selected inspector/drawer, menu, confirmation and search in both themes, requiring color-contrast to be evaluated. Verify keyboard focus/announcements, reduced motion, long names and absent data; no CSS that breaks CSP.

Update DESIGN.md only for settled implementation details; do not weaken approved render requirements to excuse mismatches. Consolidate the stage-owned website sections, refresh screenshots using the repo's existing screenshot assets/convention, and check worker/gateway console and Watch instructions all match. Stage 7 owns cross-section intros, screenshots and sidebar additions if needed; earlier stages own their scoped text updates in their own changes. Remove unused DS components/exports and obsolete WorkersTable after import search; hooks/CI run Fallow, agents never invoke it by hand. Carry the explicit Baselines ready-row DATA/filter/link amendment through the integrated audit and paired images; preserve original references and every other geometry requirement.

Review all stage evidence at the integrated head. Foundation review unblocks page branches without merging to main; the entire feature remains one stack, integrated by merge-forward in review order and merged atomically under delivery rule 15.

Contract and event changes

None. Search: rg -n 'baselineEntrySchema|requesterIdSchema|stream|baseline.save' src/contract src/http and the stage symbol search above. No daemon wire shape, operation, input socket or business event is added. Reuse existing route paths and validation; no protocol bump. The parent Baselines amendment uses only ready/stale list data and a documentation link; no baseline-saving workflow or progress field is added.

Other code on the same state

Searches: rg -n 'color-scheme|sidebar|tabIndex|prefers-reduced-motion' ui/src e2e/console returned 118 matching lines at the Facts commit. Existing readers/writers are the route-query cache and live invalidation in state/live.tsx and state/queries.ts, session/API connection classification, state/actions.ts per-item in-flight guard, state/router.ts navigation and shared recent feed in state/events.ts. New presentation consumes these owners, never replaces their persistence, timers or duplicate-write rules.

Component or parallel stage	Interaction and winner
Live events and polling	Query/cache remains authoritative; server facts update the view, never fixture or screenshot values in production. Renewal changes use the existing renewal path.
Row, inspector, Inbox and search actions	One state/actions runner shares the item key; the first active action wins, later clicks stay disabled until completion. No screen sends its own write.
Browser history, page selection and disappearance	URL and latest loaded server identity decide selection; missing subject renders the existing missing/refused state, with no stale action target.
Shared recent feed and Activity	Existing recent feed owns drawer/inspector subscriptions; Activity owns its own feed, and stage 6 changes only its hook body. Navigation releases the consumer.
Stages 0–7	Parent Shared values is the ownership contract. Stage 0 APIs are frozen at reviewed baseline; stages 1–6 use disjoint page files/hunks/cases/docs sections; stage 7 integrates serially. A necessary shared API change goes back to the foundation owner and is merged forward before consumers continue.
External device/settings drafts and Screens PR	Parent Shared values and Tasks schedule redesign first on the current committed baseline. Redesign owns overlapping DevicesTab/actions, Warm pool and DeviceDrawer hunks throughout this feature; external drafts adapt afterward through normal merge-forward resolution. Stage 4 rechecks actual Screens PR merge-base/head and preserves compatible capture APIs; foundation changes only its owned shell docs. No external task is a prerequisite, claimed, edited or imported.

Failure modes

Call	Outcome	What happens	Limit, counted from
Existing route query → API	ok, 200/304	Render mapped data; 304 retains cached identity. Visual/functional Tests below cover the changed presentation.	Existing default 10000ms from request setup; no new wait
Same	error reply / malformed reply	Existing LoadView refusal/unsupported or cached data plus refusal is rendered; no success counts fabricated. Visual Tests include refused/unavailable data.	Same request bound
Same	absent worker/device/lease	Existing missing-subject view; clear actionable selection and avoid stale target. Functional cases below cover missing identity where applicable; shared foundation behavior is exercised by existing workers/leases specs.	After bounded request settles, no additional wait
Same	network unavailable / throws / no answer	Preserve cache and connection/session handling; do not show connection loss as a page-specific business failure. Existing queries/live/session tests own transport classification; this task adds no transport branch.	Existing API timeout from request setup
Existing action runner	ok / refused / no answer / concurrent click	Keep confirm, cancel, daemon message and shared in-flight behavior. Existing actions.spec.ts owns unchanged runner behavior; changed presentation cases below extend that seam, not duplicate it.	Existing action timeoutMs or API default from send; task adds no write

Presentation/filter/selection state is tab-local; a reload rebuilds from URL and server data. Two tabs read independently and share no new mutable store. The daemon resolves conflicting writes; UI uses the existing runner. A process restart creates no new durable partial state. Existing session/connection tests cover unchanged restart behavior; page Tests exercise remount and selection where changed.

Rules in play

• coding rule 1, “body is the spec”: implement this stage and parent shared decisions, apply the recorded pending-maintainer delivery decisions.
• delivery rules 7/14/15, “checked before it is ready” and “one stack”: independent spec/review gates, reviewed foundation baseline and merge-forward integration, no early main merge.
• documentation rule 9, “same change”: update the owned website section and every other page describing the changed behavior.
• ui/AGENTS.md Layers, “A screen never fetches”: state hooks expose view models; DS receives plain values, no screen-to-screen imports in final code.
• ADR 0011 §§1–5, “No inline script and no <style> element”: bundle assets, retain CSP provider and existing session.
• ADR 0037 §§3–5, “One list of actions per kind of item”: reuse runner, model availability, confirmation, errors and toast semantics.
• ADR 0044 §§1–3, “One query cache”: consume existing keys, clock and feed; no new independent polling.
• ADR 0045 §§1,3–6, “route names a worker and a device”: keep identity/lifetime and existing policy, view-only console.

Tests

Seam: signed-in console browser, model pure exports where explicitly named; extend e2e/console/layout.spec.ts, e2e/console/views.spec.ts and model the screenshots on e2e/console/views.spec.ts. Do not duplicate unchanged transport or action-runner tests. Copy these parent Behaviours rows, one test per line with cases in a table.

• An operator resizes every console page and sees contained cards, legible text and usable navigation: cases 1440x900, 1280x800, 390x844, 1279/1280 and 767/768 boundaries, existing 360px floor, long names and empty or unavailable data.
• An operator uses every console page in light or dark and gets accessible controls and text: cases all reference states, Inbox, Queue, Usage, sign-in, not found, menu, confirm, search and selected lease drawer; axe must evaluate color contrast and report no WCAG AA violations.
• An operator uses keyboard and reduced motion on the integrated console and retains focus, announcements and readable chart data: cases menu, palette, inspector close, navigation, sign-out, chart table and reduced-motion preference.
• A reviewer inspects stage 7 pages and sees the approved shape with no overflow or accessibility violations: cases all eight reference states plus Inbox, Queue, Usage, sign-in and not found, 1440×900, 1280×800, 390×844, dark and light; compare each dark reference and current PNG, run both-theme axe and list DATA differences plus the explicit Baselines Ready filter and Prepare baseline link amendment, retaining all other reference geometry.

Done when

• Every Tests line is covered at its named seam; relevant model/unit tests and touched Chromium page specs pass. The browser lane uses faked drivers, not native hardware.
• Capture this stage's pages through pnpm test:console --project=chromium e2e/console/renders.spec.ts (page-specific --grep permitted). Compare current PNGs to all eight reference states plus Inbox, Queue, Usage, sign-in and not found; record the explicit Baselines filter/link amendment, then inspect every other non-data difference and fix/rerun until none remain except the explicit Baselines/Fleet amendments recorded in PLAN. The PR includes paired images for each reference page and lists remaining data differences; no-render pages include current images. Do not commit generated current/ or prototype/screens/.
• Check the same pages at 1440×900, 1280×800 and 390×844: no horizontal page scroll, card escape or text collision. Axe in both light and dark has no WCAG AA violations and actually evaluates color contrast. Per-page verification is required in this stage, not deferred to stage 7.
• Update website pages describing this stage in the same change. Ownership: Own final consolidation, intros, screenshots and cross-page navigation; preserve per-stage factual edits. Run pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs when the website changes.
• Every page/state has dark/light evidence at the integrated head; DESIGN/manual/website agree, unused DS and WorkersTable are removed after import search, and hook/CI Fallow results are clean. Whole-feature stack remains intact for the parent merge gate.

Out of scope

Other stages' owned files/hunks; new device management, warm-target editing, Settings or multi-device Screens behavior; backend/protocol/native capture changes; new input sockets. Apply the parent delivery decisions and document the explicit Baselines amendment; preserve every other reference requirement.

Depends on

• #1427
• #1428
• #1429
• #1430
• #1431
• #1432

Written by an agent.