Layout
The app is one flat white page beside a sidebar on a slightly darker ground. One line between them, and none around the page's header until the content scrolls under it. Depth comes from the layer a region sits on, not from shadows or nested boxes.
The shell
Regions
ground Full height, 240px wide, on the ground: a shade off the page, with one line on its edge. No header and no line across its top. Its first row is the brand or the organization switcher, as tall as the header and centred on the breadcrumbs, with the logo on the items’ icon column. Then the grouped navigation. The active item gets the primary rail.surface 56px, h-header. Part of the page, not a bar on top of it: no line under it until the content scrolls under it. Breadcrumbs on the left, the page’s actions on the right.surface One flat white plane with the header, scrolling on its own. Reading pages (forms, reports, settings) cap at 768px. Data pages (tables, maps, charts) use the full width.surface Straight on the page, rows split by hairlines, no box around them. Group with whitespace first; use a card only when content needs its own boundary.Dividers
Regions share edges. Separate them with one border-subtle line on the shared edge, not by wrapping each in its own bordered, rounded box. Inside the page, lines come from the content (a table's rows, a section's rule), not from boxes around regions. The header earns its line only once the content scrolls under it.
Breadcrumbs
The header's left side: where you are, as the chain of things you opened to get here. The same rules on every page, so the trail never changes for a reason the user can't see.
- The trail follows things, not views. Each crumb is something you can open: a list, a project, a mission, a report.
- Views of a thing never add a crumb: tabs, filters, sort and the views inside a sheet. Every tab of a project shows the same trail, so moving between tabs leaves the trail alone.
- A thing opened in a sheet keeps the trail of the page under it. Opened as its own page, it adds its crumb.
- Ancestors are links up. A link up goes back to the view you came through: from a mission, the project crumb opens its Missions tab.
- The last crumb is where you are, and never a link. When it has siblings it opens a menu to switch between them, keeping the view: switching project from the Reports tab lands on the other project’s Reports tab.
- Only the first crumb has an icon, the section the trail starts from. Labels are what the app titles the thing with (a mission by its date, a report by its title), never an id.
- The page’s title repeats the last crumb in full. The trail says where; the title says what.
Page actions
The header's right side. The page owns its actions and hands them to the layout, which shows them; nothing else goes there.
- Actions on the whole thing (Export, Share, Download PDF) sit in the header on the right of the trail, so they stay in reach however far the page scrolls.
- Actions on a part of the page stay with that part: a table’s filters above the table, a section’s edit button by its heading.
- At most one primary button in the header, and only when the page has one obvious next step. Usually there is none, and they are all secondary or ghost.
Spacing
A short scale on the 4px grid, picked by what is being separated: the bigger the things, the bigger the gap. Spacing belongs to the parent, as gap on a flex or grid; components carry no outer margins.
gap-1 A heading and its one-line description4pxgap-2 Icon and label, buttons in a row8pxgap-3 A label and its field, items in a toolbar12pxgap-4 Cards in a grid, a page title and its tabs16pxgap-6 Fields in a form, a section heading and its content24pxpy-8 Form sections, either side of their dashed rule32pxmb-12 The page title block and the first section48pxmt-16 Sections of a long page, like this one64px- A page without its own navigation is one centred column, max-w-5xl, 32px from the sides (16px on a phone). A page with a navigation list sits flush left beside it instead, and its content stops at max-w-5xl.
- Pages start 40px below the header and end 96px above the bottom, so the last thing never sits on the edge.
- Fields take the width of what goes in them: a time zone picker is not as wide as an address.
- Lines of text stop around 65 characters. Descriptions under a title get max-w-2xl.
- Settings pages are a title, then sections 40px apart: a heading, and a card holding the fields, with Save in a footer strip at the bottom of the card. Values you type have their label above; choices (a switch, a segmented control) sit on the right of their label.
- A list inside a card (members, API keys) runs edge to edge under the card heading, rows split by hairlines. Never a card inside a card.
- An irreversible action goes last, in a Danger zone section: a red-edged card that says what the action does and everything it costs, with a solid danger button in its footer named after the action.
- Group with space before reaching for a box. Two things that belong together sit closer than they sit to their neighbours; a border is for when space alone can't say it.
Container queries
Page content sizes itself against the main area, not the window. The shell's scroll region is @container/main, and everything inside responds with @…/main: queries. Never sm:, md:, lg: or xl: in page content.
The main area is the window minus the sidebar minus whatever side panel is open. Open a 400px assistant panel and a viewport query still insists the content has room it no longer has; a container query collapses two columns to one when the content runs out of width, which is what was being asked all along.
- sm: and md: land on the same step on purpose: the sidebar takes 16rem, so 32rem is the narrowest main area either was ever live at.
- Viewport queries stay for overlays (dialogs, sheets, popovers float above the frame), for content outside the shell, and for queries that aren't about width. Each says why in a comment.
- A component used in frames of different widths carries its own container instead of borrowing main, so it answers to its own box wherever it lands.
Responsive
Two decisions, made in two places. The frame (sidebar, header, overlays) switches on the window at md, 48rem. The content inside answers to its own container. Phones get the same app, rearranged, never a cut-down one.
- Type stays the same size on phones. The layout reflows; the scale doesn’t change.
- Inputs are 16px on touch screens, or iOS zooms the page when one is focused.
- Anything that appears on hover has another way in on touch: a visible button, a long press or a menu. Hover reveals live under @media (hover: hover).
- Targets are at least 40px on a coarse pointer, even when the visible control is smaller. Extend the hit area, not the drawing.
- Nothing is desktop only. A view too dense for a phone gets a simpler arrangement, not a "use a computer" message.
Global behaviour
Set once in the package's base styles, so every app behaves the same without asking.
- No bounce on desktop
- With a mouse or trackpad the page doesn’t rubber-band past its edges and show the window behind. Touch keeps it, and pull-to-refresh.
- Squircle corners
- Rounded corners use a superellipse where the browser supports it, softer than a circular arc. Full circles and pills stay round.
- Quiet scrollbars
- Thin, and hidden until you’re over the area that scrolls. no-scrollbar hides one completely, for strips that scroll sideways.
- Pages don’t jump sideways
- Pages that scroll the document reserve the scrollbar’s room. An app shell that scrolls inside itself sets data-app-shell on its root and skips it.
- Selection in brand blue
- Selected text gets a soft brand tint, the selection token, light enough to keep the text readable.
- Pointer on what you can click
- Buttons, tabs, menu items, options and summaries show the pointer cursor; disabled ones don’t.
- Sizes animate to auto
- interpolate-size lets height and width transition to and from auto, so disclosures can open smoothly without measuring.
- Steady on phones
- No text inflation when a phone rotates, and no grey flash when something is tapped.