What you give up

Less than you think. A details element opens and closes, a form posts, a link prefetches the next page with Speculation Rules. The browser has learned a great deal since we last checked.

• Menus and accordions: <details> and <summary>
• Dark mode: prefers-color-scheme
• Instant navigation: prefetching on hover

What you get

Pages that render on the first round trip, that a screen reader understands, and that still work in ten years. When a page truly needs a script, it should say so out loud.

The fastest script is the one you never send.

Start from zero and add what the page asks for. It is a better default than starting from everything and trying to take it away.

A schema per collection

Describe the fields once, next to the collection, and let the build read every file through it.

const posts = z.object({
  title: z.string(),
  date: z.coerce.date(),
  tags: z.array(z.string()).default([]),
});

The same schema gives the editor its form and the layouts their types. A field that does not exist is a type error in the template, not a blank space on the page.

Errors that point somewhere

An error message is a user interface. "Invalid input" helps nobody; content/posts/hello.md:3: date: Invalid date sends you straight to the line.

Track reads, not files

Every layout reads something: a title, a date, the list of posts. If the build records those reads, it can answer a precise question after each save: which pages read the thing that changed?

1. Render each page through a proxy that notes the keys it touches.
2. Fingerprint the values behind those keys.
3. On the next save, compare fingerprints and render only the pages whose reads changed.

The boring part

The proxy is twenty lines. The hard part is making sure the incremental output is byte for byte the full build's, which is why every test runs both and compares them.

Edit the files themselves

The admin runs only on your machine, next to the dev server. It reads the collection schemas, draws a form for each field, and saves back into the same Markdown file.

Keep the diff small

The test of a file editor is the diff it leaves behind. Change one title and the commit should show one line, with your comments, quotes and key order untouched.

• Unchanged blocks are kept byte for byte
• New keys land where the schema puts them
• A conflict shows up as a conflict, not as lost work

When the panel is done, it is gone: nothing of it reaches the published site.

Constraints that make patterns

The weave only allows certain angles, so diamonds and steps appear everywhere. The limitation is the style. CSS grid gives us the opposite problem: anything is possible, so nothing is decided.

Decide the rows first

• Pick a column count and a gap, and keep them
• Let content span columns instead of inventing new widths
• Repeat a motif rather than adding a new one

A page that repeats three widths reads calmer than one that uses eleven. The weaver knew this centuries before we had a word for design systems.

Pattern is a promise kept many times.

Use the fonts already there

Every system ships a good serif. A stack like this one costs nothing to download and looks deliberate everywhere:

font-family: Charter, "Bitstream Charter", "Iowan Old Style",
  "Sitka Text", Cambria, Georgia, serif;

Set the measure, then the size

A line of 60 to 75 characters is the oldest rule in typography for a reason. Choose the column width first, then the size that fills it, then a line height around 1.6.

Serifs will not save a page with a 120 character line. A good measure will save almost any typeface.

Start narrow

At 375 pixels there is room for one idea per row. Anything that survives there will rearrange itself gracefully on a wide screen; the reverse is rarely true.

The usual suspects

• A long URL or a code line that refuses to wrap
• A table wider than the screen
• A fixed width somebody typed in a hurry

Each one creates the sideways scroll that makes a page feel broken. overflow-wrap: anywhere and a table that scrolls inside its own box fix most of them.

Check it every time

A layout that worked last month can break with one new post. Make the narrow check part of the build, not a thing you remember on launch day.

Noise is a cost

Every progress bar, emoji and banner asks for a glance. Multiply that by a hundred runs a day and the tool has become a colleague who never stops talking.

A checklist for quiet

• Silent on success, specific on failure
• One line per problem, with where to look
• Colors only when they carry meaning
• A --json flag for the machines

Quiet is not the same as hidden. A quiet tool can explain itself at length the moment you ask; it just does not assume you want to hear it every time.

1. The Craftsman by Richard Sennett, on the skill that lives in the hands.
2. Thinking with Type by Ellen Lupton, the friendliest typography book there is.
3. A Pattern Language by Christopher Alexander, which every software person eventually finds.
4. The Design of Everyday Things by Don Norman, for the doors you push that should be pulled.
5. Shop Class as Soulcraft by Matthew Crawford, on the dignity of fixing things.

How I read them

Slowly, with a pencil, one chapter an evening. None of them is about software, and all of them are.

What changed

The first hour became the most productive of the day, which surprised nobody but me. More interesting was the second hour: the messages were still there, and none of them had become worse by waiting.

What did not

Some days the hour went to staring out of the window. That counts too. The point was never to squeeze more work into the morning, but to start the day with something I chose.

I still check my phone too often. But I check it second.