Sections

A section is a page's one structural unit — one around each heading and its content, nested to mirror the outline. It carries the page's spacing, and it's what a background is painted onto — but structure and styling stay strictly apart: the markup holds the outline at all times, and CSS decides what it looks like.

Structure

Wrap every heading-and-its-content in a section, nested to match the outline — always, whether or not it will carry a background. The structure sits in the markup in readiness for styling; you never add or remove a tag to change how the page looks.

<main>
  <h1>Page title</h1>
  <section>
    <h2>A part</h2>
    <p>…</p>
    <section>
      <h3>A sub-part</h3>
      <p>…</p>
    </section>
  </section>
</main>

A section always opens with its heading, so the heading is its first child and sits flush to the top. Headings carry no spacing of their own — the section does.

Spacing

Two rhythms, and only two. Within a part, everything is one constant gap — heading to text, paragraph to paragraph — at every depth. Between parts, a section adds a top margin that shrinks the deeper it nests, so siblings sit apart and subsections draw in. That section margin is the only margin in the flow; everything else is the gap.

Outlines added to show the section structure:

A part

Body text at the base gap.

A second paragraph, the same gap apart.

A sub-part

Set apart by a smaller step; its own text is back at the base gap.

Another sub-part

Siblings sit the same step apart.

Because the separation lives on the section and not the heading, the same heading spaces differently at different depths for free — the outline spaces itself, with no classes.

Backgrounds

A background is a styling layer painted onto that structure in CSS — never a reason to touch the markup. And because the between-part space sits outside the section as margin, switching a background on just moves that same space inside as padding: the box goes flush to its neighbours and the heading lands in exactly the same place. Nothing reflows.

The same markup — the second section has a background applied purely in CSS:

Plain part

The separation sits outside, as margin.

Painted part

The same separation, now inside as padding — flush, heading unmoved.

/* opt in wherever you want a surface — no markup change */
section.surface {
  margin-top: 0;                   /* the between-part space moves… */
  padding: var(--gap);             /* …inside, as padding */
  background: var(--surface-soft);
  border-radius: var(--radius-sm);
}

By default the theme paints only the top-level sections, as full-width bands; deeper sections stay transparent until a rule like the one above opts them in. Whether a part is a band, a floating card, or nothing at all is decided entirely here, in the stylesheet — selected by position, by :has(), or, rarely, by a class.