Navigation that disappears once you know where you are.
Sidebar, SidebarProvider, SidebarToggle, and SidebarNavLink live in the design system. Brand lockup and identity stay app-local. Active state is weight, not a pill. The topbar right slot is the credit balance and the Help tab. See section 16 for the page-level contract.
Sidebar
Collapse persists per storageKey; click the panel control
15
Dashboard
Open positions
Dashboard content lives in apps/shortlist.
SidebarNavLink — states
dim, prominent, touch, collapsed; aria-current on active
The page owns its title. The topbar carries context.
Pages render their H1 via PageHeader. The topbar carries page actions, the credit balance, the Help tab, and page-provided route context on the shared TopbarFrame column (same max-width as RouteShell): a Dashboard back-link for creation wizards, a single immediate-parent back-link on nested detail routes, or a compact breadcrumb only when a multi-route wizard needs to expose its intermediate steps. Ordinary routes leave the left slot empty. Account stays in the sidebar. Reading the URL to reconstruct the current route name in the topbar remains forbidden.
PageHeader — anatomy
Eyebrow, title, description, actions
Admin
Overview
Users, shortlists, and recent activity.
BalancePill — three states
Slate ramp, no traffic-light hues
42ok
3low
0empty
States differ in contrast, not hue. Brand contract is sober — no mint, no amber, no red.
Minimum form
Title is the only required prop
Open positions
Custom title and eyebrow slots
title, eyebrow, and description accept ReactNode
Draft
Senior Operations Manager
Pass a node for editable titles, badge rows, or rich descriptions. Strings keep the default chrome.
Canvas and cards
Three tiers, card brighter than canvas
Canvasbg-slate-100 / --eg-muted
Page background. Slightly grey, never white.
Cardbg-card / --eg-card
Content surface. One step lighter than canvas.
Chromebg-card / --eg-card
Sidebar & topbar. Same tier as cards, separated by a single border.
With shell, no duplicate title
Sidebar highlights, page header names
15
Credits
Track evaluation credits, monthly usage, and screening outcomes.
Page content lives in the consuming app.
TopbarFrame — shared content column
Back-link, credits, and Help align with RouteShell, not the canvas flank
Dashboard
15
New shortlist
Topbar utilities and the workspace share one max-w-6xl column. On wide screens the outer canvas margin is quiet; chrome does not stretch to the pane edges.
Sidebar-backed creation route
Active sidebar item plus H1 are enough
Dashboard
15
New shortlist
The sidebar marks New shortlist as active. The Dashboard back-link keeps the wizard's exit destination visible throughout intake and review.
Nested route topbar
One immediate parent link. The brand mark stays in the collapsed sidebar.
Dashboard
65
Review
Doctoral Research Assistant in Transcriptomics and Biotechnology
The page H1 names the shortlist. Because the shortlist home is a redirect-only route, the back-link lands on the dashboard and uses that landing-page label.
Composition rules
Codified in packages/design-system/APP_SHELL.md
Pages own their H1. Every routable page renders <PageHeader title="…">. Nothing else duplicates the route name.
The topbar is utility plus route context. Page actions, credit balance, and the Help tab, plus a page-provided parent back-link (or a breadcrumb on multi-route wizards). Account stays in the sidebar identity footer. The topbar never derives the active route name from the URL.
Orientation is sidebar + page H1. Two signals, one from the shell and one from the page. No third.
Parent context belongs in the topbar. Ordinary depth-0/1 routes leave the left slot empty. Creation wizards render a Dashboard back-link. Depth-2+ routes render one immediate parent back-link, labeled by the parent entity. When that parent is a redirect-only route, the link skips to the nearest landable index and uses the landing-page label. Multi-route wizards may render a breadcrumb of their own intermediate steps. Sibling views never appear there. On small screens the back-link replaces the product lockup in the left slot — route context wins, and the brand stays in the menu drawer.
38Page help
A Help tab on the seam.
Closed: Help hangs from the TopbarFrame content-column edge, under the credits, chevron down. RouteShell reserves the closed-tab shelf from the help prop on first paint. Open: a white band with a title row, one horizontal rule, then topics and detail. Topics use the same muted row + chevron pattern at every width; below sm the row scrolls horizontally, from sm up it stacks in a left rail. Use navTitle for short rail labels when title is long.
Closed
Help tab, chevron down, on the topbar seam
Topbar
42
Doctoral Assistant in Transcriptomics
Confirm the evaluation basis before uploading resumes.
Required and nice-to-have criteria stay in view.
Open
white band; Help tab on the content-column lower seam
Topbar
42
Doctoral Assistant in Transcriptomics
Confirm the evaluation basis before uploading resumes.
Hide help with the tab on the band.
Content
workflow-first section titles; navTitle for the rail
Section title names the workflow moment and appears as the panel heading. Optional navTitle shortens the topic-rail label. Body copy leads with downstream impact; control names stay inside sentences.
Authoring table and examples: packages/design-system/APP_SHELL.md#page-help-content.
28Work surfaces
Page chrome recedes. The evidence surface stays white.
These primitives extract the reusable layout spine from the Shortlist sample: a muted route canvas, constrained work area, object identity header, context strip, and composable toolbar. Apps own routing, state, labels, and data.
Route shell
Fills its parent canvas · banner above title · 6xl default · 7xl review width
Example shortlist. Start your own to evaluate a live vacancy.
Evalgist Shortlist
Senior lecturer in data systems
Review candidate evidence against the committee criteria.
Senior lecturer in data systems
CompleteVacancy criteria
147 candidates analyzed. 18 require committee review before export.
3 shown of 147. Sorted by evidence coverage.
Anika Verbruggen
6 quotes attached to criteria
Suggested match
Reviewed
Milan Peeters
4 quotes attached to criteria
Possible match
Needs check
Sara Benali
2 quotes attached to criteria
Weak match
Queued
Header on a surface
headerSurface · for a page header that carries its own actions
Postdoctoral researcher in machine learning
Review the evidence and decide on each candidate.
3 of 4 candidates decided
Without the surface the actions read as a control strip floating on the canvas. On it they belong to the object the page is about.
Headerless wizard state
The step rail owns orientation
Editable wizard content starts without a duplicate page title.
Wizard content column
Keep the lifecycle rail full-width and constrain editable content below it
Forms, file rules, and optional supporting material follow one vertical reading path.
Bare work surface
Use when the route already owns the page frame
Evidence needing review
Possible match
A compact object header can sit inside any app-owned route.
12 quotes need human confirmation.
33Surfaces
Two surfaces: the white card, and the grey canvas. Controls adapt to the one they sit on.
Interactive controls hover to --accent. On a white card that slate-100 hover reads fine. On the grey canvas (the app shell paints bg-muted), the same hover equals the canvas and the control disappears. Mark a region data-surface="canvas" and the contract remaps hover one step darker; any card nested inside resets it automatically. No per-call-site opt-in.
On the card surface
white · hover → slate-100
On the canvas surface
bg-muted · hover → slate-200 · controls rest on white and lift
A card on the canvas resets
nested controls behave as on-card again
Hover the buttons above to see it: on the canvas the hover fill is distinct from the grey; inside the card it returns to the standard slate-100. The Select and Input rest on white in both, so they lift off the canvas instead of sinking into it.
24Sticky action bar
One pill, one decision.
Edit flows keep discard, save, and bulk decisions in one bar at the bottom of the work surface. Desktop is a single row: status, then the actions that screen uses. A narrow viewport wraps the actions into two columns. The pulse dot means work is still pending.
Unsaved changes
discard and one primary
2 unsaved changes
Continue
criteria and vacancy steps
Unsaved criteria changes
Bulk decision
review selection, one row
3 selected
Disabled
enabled subtle and disabled primary stay distinct
Up to date
Tones
warning, info, danger, success
Pending review
Analysis running
Quota exceeded
Ready to review
Interactive
save replaces the pending status
Unsaved changes
When to use
rule
Use when the user can leave an edit mid-change, or when a selection needs a decision before the next step. The bar is fixed to the viewport bottom in the product. These specimens sit in the flow so the layout reserve does not open a gap. One primary action. When the bar is persistent, those actions stay in the bar and the page header does not repeat them. Object-level maintenance stays in the heading overflow menu. Transient confirmations use the toast.
23Danger zone
Destructive actions get a card, a typed guard, and one red accent.
One surface for every irreversible action across products. The industry consensus — Mintlify, Clerk, GitBook, Hume, 1Password, Stripe — is no leading icon: the destructive button is the sole accent, which also matches our monochrome-chrome rule that colour is reserved for the action. The typed-confirmation guard is the safety feature; bypass it and the user can delete data with one click.
Typed-confirmation guard
default for irreversible actions
Delete account
Permanently removes your account, positions, resumes, and analysis results.
No typed guard
for lower-stakes confirms
Clear search history
Removes the cached search queries on this device.
Disabled with notice
action gated by policy
Delete account
Permanently removes your account, positions, resumes, and analysis results.
Account deletion is handled manually during the pilot. Contact an administrator to remove your account and associated data.
Outline emphasis
when several danger cards share a page, demote the narrower one
Remove all projects
Permanently removes every project in this product. Your account stays active.
Optional leading icon
opt-in; a muted warning glyph, never a chip
Delete workspace
Permanently removes the workspace and everything in it.
39Legal documents
One reading layout for every legal page, whichever shell wraps it.
LegalArticle, LegalNav and SubprocessorCards from @evalgist/design-system/legal. The website and the product landings share them; the surrounding header and footer stay with the app.
Article
Compliance eyebrow, large title, document body, contact line, last-updated stamp
Compliance
Example terms
Body copy comes from the legal markdown through LegalDocumentBlocks. This sample only shows the frame.