Block guidelines — Alexis Reyna

Three rules above the vocabulary

Rhythm belongs to the container. Blocks carry no outer margin. One > * + * rule owns all vertical spacing, so the gap between a paragraph and a table always equals the gap between two paragraphs. The only exceptions are relationships — a heading and the text beneath it tighten up, because they are one unit.

The measure is applied to text, not the container. Prose caps at 68 characters. Capping the container instead would clamp its children, and then a table could never reach full width without negative-margin escapes that break when the gutter changes.

Inline emphasis does not nest. A strong cannot contain a link. When you reach for nested emphasis, the honest fix is usually that the sentence wants to be two sentences.

The vocabulary

Ten blocks. Adding an eleventh has to be argued for — a constraint that changes what you write has earned its place; one that only prevents ugly output is better handled by a lint rule.

headingSection boundary. One per section, never two in a row — a heading immediately followed by another means the first section has no content and shouldn't exist.

The validator is the feature

subheadingSub-boundary inside a section. Only legal after a heading. There is no level three; if you need one, the section is too long.

Rhythm belongs to the container

paragraphThe default. Everything that isn't one of the others is this. Capped at the 68-character measure; body ink is softened to #444141 so headings stay dominant.

A deployment manifest is a whole chain definition, not a patch. It carries the addresses and the capabilities together, so you cannot commit one without the other — they are one file.

ledeThe single most important sentence in a section. Maximum one per section. This is the constraint that changed how I write: having exactly one slot forces you to name the point, and often reveals a section holding two arguments.

A feature flag is a promise. Most of the time, breaking it renders a button in the wrong place. Sometimes it sends money to the empty string.

listUse ordered only when order is load-bearing — steps that must happen in sequence. An ordered list of parallel items misleads the reader into thinking sequence matters.

Deploy the contract. No address, no flag. Not optional, not parallelizable.
Add the address to the manifest using the key the loader reads.
Set the flag to true.

codeSteps outside the reading measure to full width — code that wraps is code that lies about its shape. The caption labels what the reader is looking at, so it never has to be inferred from context.

src/lib/blog/skills.ts

export function installCommand(id: string): string {
  return `mkdir -p .claude/skills/${id} && curl -fsSL …`;
}

terminalFor commands the reader is meant to run — distinct from code they're meant to read. Only $ lines are copyable; output and comments are user-select:none, so a drag-select produces something runnable.

bash

# install one skill

curl -fsSL alexisreyna.dev/skills/theme-tokens/SKILL.md -o SKILL.md

→ 11.2 KB written

callout · noteA rule or principle worth isolating from the argument around it. Not for asides — if it's skippable, it's a parenthetical, not a callout.

callout · warnReserved for things that will cost the reader real time if ignored. Rationed deliberately: a page with three warnings has none, because the reader stops seeing them.

tableThree columns maximum. Wider tables don't survive a phone, and the horizontal scroll they get instead is a worse experience than the prose you'd have written.

Hop	Where	What it does
1	deployments/*.json	Declares capabilities and backing addresses
3	ChainRegistry.Validate	Throws if a flag lacks its deployment
4	ChainsController	Filters on .Enabled

dividerBreathing room between movements of an argument — a turn, not decoration. If you can't say what changed above versus below it, delete it.

← Back to writing