Notes on building a reading room

Most personal sites treat writing as a feature. A tab in the nav, a list of links, a page that exists because the template had a slot for it. This essay is placeholder prose, but it argues for the opposite: that the reading experience is the product, and everything else is in service of it.

If you are reading this on the deployed site, you are looking at the system it describes. The measure of the text, the rhythm between paragraphs, the way a code block sits in the page — all of it is the subject.

What a reading room is for#

A reading room is a single, quiet place to think with someone else’s words. It has no sidebar of unrelated links, no popovers, no autoplaying anything. The only ambition is that you forget you are reading on a screen.

That means the hard work is mostly subtraction. We set a comfortable measureThe “measure” is the width of the text column. Around 60–75 characters per line keeps the eye from getting lost on the return sweep. and then we protect it. We choose one reading face and let it carry the page.

The measure and the rhythm#

Long-form text wants a narrow column and generous vertical space. Crowd it and the reader feels the crowding even if they can’t name it. Give it room and the same words feel considered.

Vertical rhythm is the spacing between blocks — paragraphs, headings, lists. Consistency here is what makes a page feel composed rather than assembled.

Code should look right#

This is an engineer’s site, so code in essays has to look deliberate. Highlighting is done at build time, so no JavaScript ships just to color a keyword, and the theme follows the rest of the site.

// Estimate reading time from a word count.
const WORDS_PER_MINUTE = 220;
 
export function readingTime(words: number): string {
  const minutes = Math.max(1, Math.round(words / WORDS_PER_MINUTE));
  return `${minutes} min read`;
}
 
readingTime(880); // "4 min read"

Inline code like readingTime(880) is styled separately from blocks — quieter, so it sits inside a sentence without shouting.

A short list of principles#

A few things this system tries to hold to:

• One reading face, set at a comfortable size, with real line-height.
• Restraint over spectacle. No motion in the reading view beyond a slim progress bar.
• Sidenotes in the margin where there is room, and inline where there isn’t.

Restraint is a position. It says: I considered the loud version and chose the quiet one.

Sidenotes and asides#

Margin notes are a mark of a serious writing site, but they are easy to get wrong. On a wide screen they belong in the margin, near their reference.Like this one. On a phone, the same note collapses into a tap-to-expand affordance so it never breaks the column. On a narrow screen they have to fold away cleanly.

The implementation here favors robustness over cleverness: the note is always in the document, numbered by a CSS counter, and the layout decides where to put it.

Where this goes next#

The point of the example essays is to prove the system end to end, not to fill the site with real writing. Replace them. Keep the room.

When the words are yours, the room should disappear.