Page layout
Coherent presentation structure
An application page is built from a header, a sidebar, a canvas and a footer. The layout grid sets the space at the edge of the page, and flow sets the space between the blocks on it.
Design for small screens first, starting with a single-column layout, and add columns as the screen widens.
Choose a layout
A page uses one of two layouts:
- Contained is for document-like pages, such as articles, documentation, guidance and forms, where content should not stretch across a wide screen. It is centred, its width steps up with the breakpoints, and its padding grows as the viewport widens.
- Fluid is for dashboards and application shells, where the canvas should use the width available. It fills the width of the viewport, and its padding stays between 16px and 24px.
Application types says which layout each type of application uses.
Put the page content in .container or .container-fluid. Both classes are in the system's CSS, so they work without Tailwind:
<main class="container-fluid">…</main>In a dashboard or map, AppShell positions the sidebar, and the fluid container goes on the canvas beside it.
| Breakpoint | Contained width | Contained padding | Fluid padding |
|---|---|---|---|
base | 100% | 16px | 16px |
sm | 640px | 32px | 16px |
md | 768px | 32px | 24px |
lg | 1024px | 64px | 24px |
xl | 1280px | 80px | 24px |
2xl | 1536px | 96px | 24px |
In both layouts, the padding is on the container itself, so components don't add their own padding at the page edge.
There are no column tokens, because the number of columns depends on the content of each page. Set the columns with CSS grid or Tailwind's grid utilities. The layout grid page has the breakpoints.
Space on a page
Although it can be tempting to compress a lot into a small space, we let our applications 'breathe' by allowing for whitespace and page rhythm.
Each space on a page comes from one of three places:
- The space between blocks, stacked or tiled, comes from flow.
- The space at the page edge comes from the container's padding.
- The space inside a component, such as its padding and indents, comes from the spacing scale.
A number picked by hand is usually a sign that one of the three has been bypassed.
Space between tiled blocks
gap-flow on a grid sets the space between its items to the default flow step of the context. Cards in a row then have the same space between them as cards in a stack. In the standard context that is 8px, and in the spacious context 16px.
<div class="flow-standard">
<div class="gap-flow grid grid-cols-2">
<!-- cards -->
</div>
</div>A gap set by hand, such as gap-4, doesn't change with the context, so the grid drifts from the space around it.
Vertical rhythm on a canvas
The space between blocks within a section comes from a flow context, not from margins set on each element. Declaring the context on the section is usually enough. Set a step explicitly only where nothing else would choose it.
<section class="flow-standard typeset-product">
<h2 class="title-lg">Rough sleeping</h2>
<p class="subtitle-sm">Quarterly</p>
<div class="mt-flow-section gap-flow grid grid-cols-3">
<!-- cards -->
</div>
<p class="caption-sm">Source: GLA City Intelligence</p>
</section>typeset-product sets the typeset, so title-lg and subtitle-sm take their product values. flow-standard sets how far apart the blocks sit.
Dashboards
A dashboard has a title at the top of the canvas, then sections, each with a section title and a grid of cards. DashboardTitle and DashboardSectionTitle render headings with the dashboard-main-title and dashboard-section-title classes.

<div class="flow-standard">
<DashboardTitle title="Dashboard title" subtitle="A subtitle for this dashboard" />
<div class="gap-flow grid grid-cols-2">
<Card title="Title" subtitle="Subtitle">…</Card>
<Card title="Title" subtitle="Subtitle">…</Card>
</div>
<DashboardSectionTitle
title="Dashboard section title"
subtitle="A subtitle for this section"
class="mt-flow-section"
/>
<div class="gap-flow grid grid-cols-2">
<Card title="Title" subtitle="Subtitle">…</Card>
<Card title="Title" subtitle="Subtitle">…</Card>
</div>
</div>Dashboard title
A subtitle for this dashboard
Subtitle
Subtitle
Dashboard section title
A subtitle for this section
Subtitle
Subtitle
Anatomy
Header
The header sits at the top of the page. It contains the application title and the highest level of navigation between pages, if there is one.

Footer
The footer sits at the base of the page. It can contain secondary and tertiary navigation, branding, and links to user preference settings.

Sidebar
The sidebar contains the top-level navigation and filters for the application. Depending on the context, this could be a simple list of pages or a complex set of grouped filters. Filters in the sidebar should apply to the whole page. Place a filter that affects only one chart next to that chart.
The sidebar sits beside the canvas. The canvas fills the rest of the width, and the fluid layout applies only to the canvas.

Canvas
The canvas is the main area of the application.

Layers
The canvas is the lowest layer of the application, and the things placed on it sit at higher levels of elevation. Each level is shown by a shadow. A card sits just above the canvas at elevation-1, a tooltip above it at elevation-4, and a modal at elevation-5. Surfaces and chrome describes cards.
AppShell
AppShell, in @ldn-viz/ui, sets where the sidebar sits at each breakpoint, whether it is always open and whether opening it pushes the content aside.

The sidebar can sit at the top, bottom, left or right. sidebarPlacement sets the position from each breakpoint up:
<AppShell sidebarPlacement={{ initial: 'top', md: 'bottom', lg: 'left' }}>
{#snippet sidebar()}…{/snippet}
{#snippet main()}…{/snippet}
</AppShell>Storybook lists its props.