Grid
The app shell, report pages and the site share one set of layout rules.
On this page
App shell
AppShell lays out a header, the navigation, the page and an optional side panel. On a desktop the navigation is a
panel with its labels, 14em wide and dragged by its splitter between 11em and 24em, or folded to the icon rail; the
side panel is 20em, dragged between 14em and 36em, or shut. On a tablet the navigation is the rail and the side panel
goes under the page; on a phone the navigation is a tab bar or a menu. With layoutStorageKey each browser keeps the
widths and folds its crew set.
| Region | Size | Behavior |
|---|---|---|
| Rail | 4.5em | The navigation on a tablet, or folded on a desktop: icons, with alert badges on them |
| Panel | 14em, dragged between 11em and 24em | The navigation on a desktop: every destination by group, with live counts |
| Side panel | 20em, dragged between 14em and 36em | Beside the page on a desktop; under the page on a phone or a tablet |
| Header | Its content's height | Page title, alert zone, status strip; sticks to the top, on the alert layer |
| Page | The rest | Scrolls; its content reflows into columns |
The vessel application's own sidebar (a 52px rail and a 216px panel, changing at a 900px window width) has window rules of its own until it moves onto the kit shell.
Phone
On a screen up to 40em the kit shell exchanges the navigation column for a tab bar or a menu. Opened from the menu button, the navigation stands under the header, over the page, wherever the page is scrolled, and scrolls inside itself.
Breakpoints
Every kit component changes form at the same two widths of the screen it sits in, the bk-screen container: an app
shell, a device frame or a narrowed hero. The widths are in em of the screen's font size, so a larger size class lays
out as a narrower screen.
| Form | Screen width | Container condition | Token |
|---|---|---|---|
| Phone | up to 40em (640 px) | (max-width: 40em) | --bk-breakpoint-phone |
| Tablet | up to 68.75em (1100 px) | (max-width: 68.75em) | --bk-breakpoint-tablet |
| Tablet or desktop | wider than 40em | (width > 40em) | |
| Desktop | wider than 68.75em | (width > 68.75em) |
A phone form and a tablet form switch at these widths only. The upper bounds are inclusive and the lower ones exclusive, so at exactly 40em or 68.75em one form applies. Buttons, tabs, switches, chips and inputs take their 48 px touch size on a phone or a tablet, or wherever the pointer is coarse; a coarse pointer changes a target's size, never a layout. A component that rearranges by its own width wherever it is placed, such as the header bar or an AIS target row, keeps thresholds of its own.
The screen's height
A component's short form, for a phone on its side, is @container bk-screen (max-height: …). Only a screen of
known height is a size container: the design site's device preview and an AppShell with fillHeight. Inside a
shell that grows with its page the query matches nothing, and the component keeps its usual form. A component never
uses @media (orientation) or a viewport-height query: the screen is the container, not the window.
Report page
A report page has one reading column for prose, and figures (diagrams, hop traces, wide tables) that may extend past it. The reader's eye stays on one line length while the figures get the room they need.
Three different measures
| Measure | Question it answers | Ownership |
|---|---|---|
| Screen container | Which phone, tablet or desktop form fits? | AppShell, device preview or another bk-screen owner |
| Reading column | How long should a paragraph line be? | Document composition; template measure uses --bk-report-width |
| Figure area | How much room can this table or diagram use? | Available content space inside the site shell |
A wide report does not require a full-width documentation page. Keep the sidebar and “On this page” outside the
figure area. ReportGrid wraps panels within that area, and Mermaid's expand control scrolls the drawing inside
its frame. Use Desktop preview to inspect large-display compositions without changing the page layout.
Responsive composition checks
Test the region a component actually occupies: a narrow side panel on a desktop can need a compact composition. Let related actions wrap before reducing their target sizes. Tables and drawings may scroll horizontally within named regions; paragraphs and ordinary forms should reflow. Keep source order aligned with visual reading order when columns stack, and preserve the current selection and draft when the layout changes.
Document insets and section gaps use the communication tokens. UI gaps use the spacing scale; helm typography changes independently. A breakpoint copied from the vessel application's window layout is not a substitute for the kit's screen-container contract.
Using the grid
The anchor has held for four hours. The wind is forecast to back to the south after midnight, which puts the shore on the lee side of the swing circle.
Related
- Spacing: the distances inside the grid
- Elevation: how regions are separated
- Reports and docs