Layout patterns

Evaluating user needs

What a user needs to learn determines the right organizational pattern to employ for any group of content. Use the four questions below as a starting point. Each question has a test and a set of patterns that answer it. Most content will fit under one of these questions. Have an edge case? Discuss it with the design team.

The main content comes first

Before choosing components, decide what the page is for and which content is primary. Everything else is arranged so it does not push the primary content down.

• A page either sends the reader on or is where they work. A page that sends the reader on, such as a list of sections or reports, shows each destination as a card that links, with only what helps the reader choose. A page where the reader reads, compares or acts on records uses tables and filters.
• Leave detailed figures for the page they belong to. A card shows a name and, at most, a count or a mark that something needs attention; the figures are on the page it opens.
• The page heading is followed by the main content. At most one short line comes between them. A line that sets the data in context, such as the period it covers and when it was last updated, goes there, just above the main content. The refresh control ends that line: a text button with the refresh icon (refresh-cw). An explanation of the figures is secondary: see Where secondary content goes.
• Controls for a list sit on one row just above it. The sort bar is at the left edge; another control, such as a Categories button, is at the right edge (.ds-btn-group--split around the two). The row is close to the list and clearly apart from the text above it.
• A page with little on it needs no section headings. The page heading names it; a heading such as “Subject groups” under “All sections” adds nothing.
• A link in the header navigation is not repeated on the page, and no link on the page repeats the page heading.
• One name for one thing. Choose one word for each kind of thing, such as “section”, and use it in every heading, link and sentence.
• Mark what needs attention where it is. A status tag on the card or row, not an alert that lists the items, which the reader then has to find.
• Only the page's main action is a primary button. Refresh, export and other secondary actions are text buttons.
• Show readers what they can use, without labelling their access. A page shows each reader only what their permissions allow. It does not label parts of the page with who is allowed to see them.
• Dense pages do not organise content with page zones, and neither do the lighter pages of the same tool, so every page of the tool looks the same.

Where secondary content goes

Each kind of secondary content has a home that keeps the main content high and wide. Compare at least two homes for each piece, and keep the one that leaves the main content highest and widest.

• A line or two: a line below the main content. A short note, such as what the figures count, reads as a footnote. It needs no heading and no accordion.
• A labelled section the reader may want: an accordion below the main content. An accordion holds more than a line or two.
• The rest of a list whose first items matter most: show more, such as authors after the first eight. A list of equal items, such as the categories a report covers, is shown or hidden whole.
• A list or explanation the reader opens when needed: a popover or a modal, opened from a button with a visible label, such as “Categories (40)” or “About these charts” beside the heading; an icon on its own is easy to miss. A popover opens beside its button and leaves the page usable; a modal takes over the page while the reader looks through it.
• A sentence about one label or control: a tooltip.
• Supporting content beside short main content: a sidebar.

The page container

Every page sits in .ds-container. It centres the content in a column at the standard reading width, 850px at most, with a margin of at least 24px on each side. For a band that runs edge to edge, see Page zones.

<main class="ds-container">…</main>

.ds-container places every direct child in the reading column and puts --ds-space-section (48px) between them, so a section has no margin of its own.

• One width per page. Prose, tables, demos, code and callouts share the reading column, so everything on a page has the same left and right edge. A page that needs a different width changes the width token; it does not add a second width.
• Long-form reading is narrower. An abstract, a paper body or an explanation read from start to finish targets a line of about 65 characters, set on the page, not on the paragraph.
• Reference pages accept a longer line. At 850px a line is about 109 characters. That suits short reference paragraphs and two-column layouts; it is not a reason to set long text that wide.
• Few breakpoints, each for a change in structure. Prefer a layout that needs no query, then a container query, then a media query. Breakpoints about text are in rem; breakpoints about fixed widths are in px. A threshold that CSS and JavaScript share is a custom property, read by the script with getComputedStyle.

Sidebar

A sidebar sits to the right of the main column and contains supplementary content. If the content is secondary, distinct from the main content, and it is important that it not be pushed far down the page, then a sidebar is appropriate.

The sidebar has no background and no border. Space alone separates it from the reading column and separates its blocks from each other.

<div>
<article>…</article>
<aside class="ds-sidebar" aria-label="Paper details">
  <details class="ds-acc" open>
    <summary>Versions</summary>
    <div class="ds-acc-body">
      <dl>
        <dt>v3 · current</dt><dd>24 Apr 2026</dd>
        <dt>v2</dt><dd><a href="#">2 Mar 2026</a></dd>
      </dl>
    </div>
  </details>
  <details class="ds-acc">
    <summary>Paper information</summary>
    <div class="ds-acc-body">…</div>
  </details>
</aside>
</div>

• A sidebar is for a page whose main content is about as long as the sidebar, such as an abstract page beside its versions and citation. The main content gives up the sidebar's width and the gap, about 22rem.
• When the main content needs its width or runs long, choose another home. Charts, tables and wide pages need the width, and beside a long main column a sidebar leaves an empty column for most of the page. See Where secondary content goes.

Dividers

A rule between things. It belongs in the same conversation as the card, because both answer the same question and the answer is usually neither: this system groups with space first, and a line drawn where space would have done adds noise without adding meaning.

<p>A section of content.</p>
<hr>
<p>The next section.</p>
<hr>
<p>And the one after it.</p>

<p>An item in a group.</p>
<hr class="ds-divider ds-divider--tight">
<p>The next item in the same group.</p>
<hr class="ds-divider ds-divider--tight">
<p>And the one after it.</p>

<div class="ds-btn-group">
<span>Search</span>
<span class="ds-divider ds-divider--vertical" aria-hidden="true"></span>
<span>Submit</span>
<span class="ds-divider ds-divider--vertical" aria-hidden="true"></span>
<span>Donate</span>
</div>

Marginalia and gutter space

At wide screen widths, our max content width leaves enough gutter space on the sides for marginalia. A short note beside the block it belongs to is appropriate for annotation-style content. At narrower widths, it is hidden in an info icon in the block’s top-right corner. Try it by widening and narrowing your screen.

<div class="ds-card">
<details class="ds-marginalia">
  <summary><svg aria-hidden="true">…</svg><span class="is-sr-only">Note</span></summary>
  <p class="ds-marginalia-body ds-annotation">The note.</p>
</details>
…
</div>

• No JavaScript required. Even the info links use a native disclosure.
• The marginalia appear at 1314px width. The page width plus a note and its gaps on each side. Below that width, marginal notes are hidden behind an info icon.
• A note should never contain required information. A reader on a narrow screen may never open or see it, so annotations must contain only optional content.