staging-org / ocean-landing-serve / docs/ app-screens.md

Building app screens

How to build a screen under src/routes/(app): the steps, the patterns that replaced defaults Fenil rejected, and how to prove a screen works. Type, color and motion rules live in docs/ui-rules.md; repo gotchas in CLAUDE.md.

Steps

  1. Name the decision. Write one sentence: "On this screen, who decides what." A billing page decides which plan you pay for; a pull request page decides whether it merges. Done when the sentence exists and every section on the screen serves it.
  2. Reuse first. Check the parts in the catalog below before writing new ones. Done when every piece of the screen maps to an existing component, or you can name why none fits.
  3. Design the rail, or leave it out. Wide screens get information, not wider fields. The right rail answers "what happens if": the next bill for this plan, a dry run of these permissions, what still blocks this merge. Done when changing anything in the main column visibly changes the rail, and the rail also renders below the content under xl. A screen whose job is working through a queue (the pulls list) gets no rail; extra panels only compete with it.
  4. Write sample data as if it were production. Typed in src/lib/*-sample.ts with satisfies. People, agents, numbers and dates agree across every page (sidebar counts, inbox, lists, details). Compute what can be computed (line numbers from diff text, totals, projections); never type a derived number by hand. Money is integer cents. Done when every number on screen traces to one source.
  5. Build every state. Empty, loading, blocked, done, error, and the one-item case (the last passkey, the only payment method). Each blocked state says what unblocks it and offers that action beside it. Done when you have rendered each state, not imagined it.
  6. Prove it. Run bun run check && bun run check:ui && bun run build, then drive the real page in headless Chrome (see Proof). Done when the interactions behave, the shell does not scroll, a 500px phone has no sideways scroll, and you have looked at screenshots at 1440px and 500px.
  7. Commit small. One commit per logical piece, body with the why and the exact verification and its result.

Patterns

What each rejected default became. Reach for the right-hand column first.

Instead ofBuildExample
A table of attribute columnsRows grouped by who acts next: a mono number gutter, the title, and one line naming the author and the next step. The StageTrack and the rest of the metadata live on the detail pagepulls list (the issues list still carries a StageTrack)
A chart above the code (a churn histogram, then a growth line)The commit on screen with Earlier, Later and Latest, so the code stays the focus. Fenil cut the growth line in October 2026repo/History.svelte
A dropdown for two to four optionsA segmented control that shows every option, the chosen one filled in the brand blue (bg-primary)grant cells, merge method, spend action
A native select over a long listA searchable combobox whose rows carry context (local time and UTC offset for time zones)settings/TimeZonePicker.svelte
Two "from" and "to" pickersOne band over the whole range with real data on it, draggable at either end, with steppers for keyboardssettings/QuietHours.svelte
An emergency control behind SaveAn action that applies at once and says soSign out a session
A status as one muted wordAn icon plus words that say what the thing can and cannot do in that stateverified and unverified email
Tabs that split one taskOne page read top to bottom, with the decision in the rail and each blocker carrying its fixpull request page
A single-click Removesettings/ConfirmButton: arms red with the consequence, re-locks after four secondskeys, sessions, payment methods
Rows stretched across a wide screen, the action at the far edge, the same blocker repeated on every repositoryFrom xl, a list pane of two-line rows (state mark, name, one status line) beside a detail pane for the selected item that holds every action and fills the rest of the width (two columns inside once the pane passes 56rem); below xl the detail opens under its row. Blockers are grouped by cause with one fix. Fenil rejected the stretched list, then the capped list that left the screen empty, in October 2026halyard/migration, app/migrate/MoveDetail.svelte
Color to make it feel aliveNothing. Life comes from real data, live consequences and motion that answers the usersee Color in docs/ui-rules.md

Catalog

  • Shell: app/Sidebar (workspace switcher; typing anywhere outside a field lands in its search, which finds places and acts on the queue; hovering a row or pressing Space opens app/Peek; collapses to an icon rail with [), app/TopBar (breadcrumbs, mono for repository and agent names, rail adds the side panel toggle), app/Rail (every right rail; collapses with ], sheet opens it over the page below xl), app/here.svelte.ts (what each page offers: the sidebar shows it under the page title and the command menu leads with it; add a page's actions here when you add the page), app/CommandMenu (⌘K: page actions, then Needs you, then recent pages; scoped to the repository or settings you are in, Backspace widens it), app/queue.svelte.ts (one set of decisions on what waits for you; act where the ask appears and offer Undo), app/jump.ts (every place and action search can reach).
  • Settings: settings/Frame (main column plus consequence rail), Group (ruled section, title left from lg, or wide), Row (label and hint left, control right; inline keeps a switch beside its label on phones, stack gives the control the full width), SaveBar (appears only while dirty and names what blocks saving), ConfirmButton, TimeZonePicker, QuietHours, PaymentMethods.
  • Code: the (code) route group keeps repo/FileTree (expandable tree from xl, t focuses Go to file) beside one scroll pane that resets on a new path and keeps its place while scrubbing; repo/PathBar (sticky 48px band sharing the tree header's rule), repo/History (the commit on screen with Earlier, Later and Latest; the file page feeds it fileLog so it steps through only that file's commits), repo/TreeView (listing plus the folder's README), repo/Crumbs, repo/Churn, repo/file-icon.ts; diffs render as the full-bleed type-code table on the commit and pull request pages, highlighted on the server by server/highlight.ts.
  • Mirrors: repo/mirror/mirrors.svelte.ts (MirrorStore derives each mirror's status from what the destination holds; MirrorDraft names the one problem blocking Start mirroring), MirrorSetup (one form that grows as you answer: HostPicker, then Destination for authorized hosts or ServerConnection for any git server, then RefsPicker), MirrorRow (status in words, the one fix beside it, details on expand), HostMark (monochrome host logos).
  • Migration: app/migrate/moves.svelte.ts (moveStore, one module-level store shared by the hub and the start page; lost GitHub access is read from the organization so one reauthorization frees every move it stopped; MoveDraft holds the picks, renames and people matches), MigrationStrip (one segment per repository, colored by state, copying segments fill as they progress, each links to its row), MoveDetail (the selected repository or stopped organization: steps with figures, the state's action, facts, what stays on GitHub; compact drops the header when it opens under its row), MoveName, SwitchPanel (last copy, what happens on GitHub, the remote command, what stays behind), RepoPicker, UrlList, PeopleMap.
  • Branches and runs: branches-sample.ts is the one list of ledger branches (the code page's count and the rail's recent branches derive from it); repo/Divergence (behind and ahead of main on a square-root scale). repo/ci/ci.svelte.ts (ci, module-level: run state from its jobs, the critical-path duration, live log streaming, rerun that replays each job's script so a flaky failure can pass and a real bug fails again, cancel, approving a gated deploy, rollback as a run of its own), RunStatus, PipelineGraph (jobs in columns by what must finish first), LogView (steps fold; the failing or running step opens by itself and the log follows a running tail). Production deploys that carry a migration wait for a person; an agent's approval never counts.
  • Lists: app/StageTrack for any lifecycle.
  • Shared rules: lib/merge-gate.ts decides what blocks a merge under a MergePolicy (the pull request page and the org merge rules dry run both use it).
  • Org settings: /halyard/settings with its own sidebar mode and nav (orgSettingsGroups in settings/nav.ts); people, roles and second factors live on org.members.
  • Caissons: caissons/RepoMap (one repository as a partition of its files, each live caisson a lane under it with what it may write, changed and read; collisions drawn as dashed lines; pass draft and onpick to make it the scope picker), caissons/Replay (a session on a time-true track with the branch's drift from its base hanging below it; bind at and let the rest of the page follow), caissons/AgentHandoff (the same request as CLI, HTTP and MCP, because agents are the main users), caissons/ChangeSet (a caisson's changes at any size: six files and 400 lines or fewer read top to bottom; above that, a reading-cost meter and sections ordered by what needs a person, with identical edits and name-swapped templates folded to one copy, generated files folded, crowded sections split by folder, viewed marks and j/k; the sorting lives in caissons/change-set.ts), caissons/DiffBody (pages a diff 160 lines at a time; new files render as plain files). Repository files for the map live in repo-trees-sample.ts; caissons-bulk-sample.ts (2,600 lines over 44 files) and caissons-greenfield-sample.ts (10,500 lines over 115 new files) exercise the large layouts.

Rules for app screens

  • The shell: sidebar, a 48px TopBar, content that scrolls on its own, and a right rail from xl wrapped in app/Rail, never a bare <aside>, so it collapses with the others. Pass rail="sheet" to TopBar and sheet to Rail when the page has no inline copy of the rail below xl, rail="wide" when it does. Collapse state lives in the sf-panes cookie so the server renders it. Page shortcuts on single letters must call preventDefault, or the key also starts a sidebar search. Full width, left-aligned, no marketing navbar or footer.
  • Navigation sits on one grid. Sidebar icons at 20px from its edge, labels at 46px, nested lists hang from a rule under the parent icon's center (28px), rows 32px (28px nested); the sidebar header shares the TopBar's 48px band and rule. The command menu keeps icon, heading and footer on one 20px edge with 40px rows. Merge overriding classes with cn() so an override actually wins, and measure edges in the browser rather than trusting a screenshot.
  • The marketing language carries over: hairline border-t between sections, peers in plain grids or divided lists. No rounded bordered panels, tinted pills or drop shadows; floating layers (popovers, the command menu, tooltips) are the only exception.
  • Agents are always monospace and people never are, so who did what reads at a glance.
  • Grid tracks holding text use minmax(0,1fr), never a bare 1fr, and long strings get min-w-0 plus truncate or overflow-x-auto.
  • Settings layout follows the space a section gets, not the viewport: Frame's column and each Group's content are container query roots. A Group puts its title beside the content from a 48rem container, a Row puts its control beside the label from 28rem. Inside a Group, switch width-dependent layouts with @md:/@lg:/@xl:, because between 1024 and 1400 px the viewport is wide but the column is not. Keep viewport sm: only where phone and desktop must differ at the same container width.
  • A Group already draws the rule above it and trims the last row's bottom padding; rows add py-4 first:pt-0 and no borders of their own.
  • Anything only in the rail also has a way in below xl.
  • A switch row's label toggles its switch; checkboxes and other small controls get a 40px hover target.
  • Draft edits sit behind SaveBar; things that act on the world at once (sign out a session, add a payment method, remove a key) do not.
  • An automated approval is shown but never counts toward a merge; anything touching migrations waits for a person. Screens that show permissions or merges keep to this.

Proof

The scratchpad scripts drive Chrome over CDP: launch with --headless=new --remote-debugging-port=<port>, wait about 3.5 s for the port, and kill strays with pkill -f remote-debugging-port=<port> before a rerun. Headless Chrome will not lay out narrower than 500px, so 500 is the phone check. For each screen:

  • Drive the real interactions with Runtime.evaluate and Input.dispatchMouseEvent, and log the state that should change (the rail text, a count, the URL).
  • document.scrollingElement.scrollHeight equals innerHeight; anything larger means the shell scrolls.
  • document.documentElement.scrollWidth equals the viewport at 500px.
  • No Runtime.exceptionThrown events.
  • Screenshots at 1440x900 and 500 wide, opened and looked at, especially for label collisions and wrapping.