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
- 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.
- 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.
- 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. - Write sample data as if it were production. Typed in
src/lib/*-sample.tswithsatisfies. 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. - 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.
- 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. - 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 of | Build | Example |
|---|---|---|
| A table of attribute columns | Rows 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 page | pulls 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 2026 | repo/History.svelte |
| A dropdown for two to four options | A 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 list | A searchable combobox whose rows carry context (local time and UTC offset for time zones) | settings/TimeZonePicker.svelte |
| Two "from" and "to" pickers | One band over the whole range with real data on it, draggable at either end, with steppers for keyboards | settings/QuietHours.svelte |
| An emergency control behind Save | An action that applies at once and says so | Sign out a session |
| A status as one muted word | An icon plus words that say what the thing can and cannot do in that state | verified and unverified email |
| Tabs that split one task | One page read top to bottom, with the decision in the rail and each blocker carrying its fix | pull request page |
| A single-click Remove | settings/ConfirmButton: arms red with the consequence, re-locks after four seconds | keys, sessions, payment methods |
| Rows stretched across a wide screen, the action at the far edge, the same blocker repeated on every repository | From 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 2026 | halyard/migration, app/migrate/MoveDetail.svelte |
| Color to make it feel alive | Nothing. Life comes from real data, live consequences and motion that answers the user | see 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 opensapp/Peek; collapses to an icon rail with[),app/TopBar(breadcrumbs,monofor repository and agent names,railadds the side panel toggle),app/Rail(every right rail; collapses with],sheetopens it over the page belowxl),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 fromlg, orwide),Row(label and hint left, control right;inlinekeeps a switch beside its label on phones,stackgives the control the full width),SaveBar(appears only while dirty and names what blocks saving),ConfirmButton,TimeZonePicker,QuietHours,PaymentMethods. - Code: the
(code)route group keepsrepo/FileTree(expandable tree fromxl,tfocuses 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 itfileLogso 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-bleedtype-codetable on the commit and pull request pages, highlighted on the server byserver/highlight.ts. - Mirrors:
repo/mirror/mirrors.svelte.ts(MirrorStorederives each mirror's status from what the destination holds;MirrorDraftnames the one problem blocking Start mirroring),MirrorSetup(one form that grows as you answer:HostPicker, thenDestinationfor authorized hosts orServerConnectionfor any git server, thenRefsPicker),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;MoveDraftholds 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;compactdrops 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.tsis 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'sscriptso 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/StageTrackfor any lifecycle. - Shared rules:
lib/merge-gate.tsdecides what blocks a merge under aMergePolicy(the pull request page and the org merge rules dry run both use it). - Org settings:
/halyard/settingswith its own sidebar mode and nav (orgSettingsGroupsinsettings/nav.ts); people, roles and second factors live onorg.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; passdraftandonpickto 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; bindatand 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 incaissons/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 inrepo-trees-sample.ts;caissons-bulk-sample.ts(2,600 lines over 44 files) andcaissons-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 fromxlwrapped inapp/Rail, never a bare<aside>, so it collapses with the others. Passrail="sheet"toTopBarandsheettoRailwhen the page has no inline copy of the rail belowxl,rail="wide"when it does. Collapse state lives in thesf-panescookie so the server renders it. Page shortcuts on single letters must callpreventDefault, 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-tbetween 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 bare1fr, and long strings getmin-w-0plustruncateoroverflow-x-auto. - Settings layout follows the space a section gets, not the viewport:
Frame's column and eachGroup's content are container query roots. A Group puts its title beside the content from a 48rem container, aRowputs 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 viewportsm: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-0and 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.evaluateandInput.dispatchMouseEvent, and log the state that should change (the rail text, a count, the URL). document.scrollingElement.scrollHeightequalsinnerHeight; anything larger means the shell scrolls.document.documentElement.scrollWidthequals the viewport at 500px.- No
Runtime.exceptionThrownevents. - Screenshots at 1440x900 and 500 wide, opened and looked at, especially for label collisions and wrapping.