reference

How this page sets

Every size on it comes off one scale and every gap off one grid. That is not a house style — it is the only thing that lets a reader tell a heading from a title from a label before they read any of them.

The two registers

Prose is the reading register: a paragraph at 16px, held to a measure, with headings above it that get quieter as they get deeper. Anything the machine wrote — a control, a table row, a code block — runs on the same scale a few steps down, because a reader scans it rather than reads it.

The mistake the scale exists to prevent is a third voice — a size chosen for one component because neither register looked right that afternoon. Every such size reads as a fourth level of hierarchy that means nothing.

Register	Steps	What it is for
Display	58 / 44 / 34	A page opener and the two headings under it. Once each.
Reading	20 / 19 / 16	A third heading, a lead, and the paragraph that is the measure for everything else.
Dense	14 / 13	Every control, every table row, and everything the machine wrote.
Label	12 / 11	A machine name, a table head, a caption. Never a sentence.

Inside a block

A reader reads anything with a heading over its own text, so its body is the page's own size. Only the title tells two kinds apart: a card and a result carry the louder one, because their title is somewhere you can go rather than something you read.

A block reads at the page it stands on

There is no second register to rebind and nothing to keep in step. What is dense is what the machine wrote — a control, a row, a code block, the line about the thing beside it — and each of those says so itself.

Below is the same shape twice: once as an entry, whose title is a destination, and once as a surface, which states something in place. The bodies are one size and only the titles differ.

entry

An entry

Its title is a link, so it is the louder of the two and a page of them can be scanned by title alone.

A surface

It states something in place. Its title stays the quieter one, because nothing here is a destination and a title that looks like one is a promise the box does not keep.

The vertical step

What separates two things on a page is the air between them, and the air is what says which of them owns the other. A second-level heading takes 40px above it and the flow gap below: the large one belongs to the section it opens, the small one binds it to what it introduces.

Get that pair backwards and the heading floats between two sections and belongs to neither. That is the most common way a page with correct sizes still reads as a list of fragments.

A heading is the top of what follows, not a gap after what came before.

base.css · the rule the flow contract is built on

Behind a value

A token, or it is a defect. The scale holds the sizes and the grid holds the gaps, and a component that needs something between two steps has found either a missing step or a decision it must not make alone.

css

/* a reader reads a block, so it takes the page it stands on */
--block-title-size: var(--font-size-body);
--entry-title-size: var(--font-size-h3);
--block-body-size:  var(--font-size-body);

/* and the line *about* a thing is not the thing */
--aside-size: var(--font-size-small);

type steps

every size on every surface

space steps

halved below 16px, thinning above 24

a reader reads it, so it takes the page’s size

Questions

Is a block smaller than the text around it?

It is not. A block that holds sentences takes the page's own size wherever it stands — an admonition is the paragraph above it with a border around it. What stays small is what the machine wrote, and a caption, which is a label rather than a sentence.

Where does a value that is not on the scale come from?

Nowhere it can. A size that is not a --font-size-* and a gap that is not a --space-* are both values somebody typed, and the only route onto a surface is a token or a component’s own property set, where a review reads the number beside its reason.

What decides how much air a heading gets above it?

Its level. The step above a heading says which one it is, and the size only confirms it. At the fourth level the size no longer changes at all.

reference tokens

The tokens themselves

Every value named above, with what it is for and what it is never for.