Build the System
Building This Site on a Production-Grade Foundation
Why a two-page personal site runs a tokenized design system, feature folders, layout-owned SEO, and a typed analytics catalog — and what that buys later.
Most personal sites start as a single HTML file and grow scar tissue. This one started the other way: the smallest possible content on top of the same architecture I use for production apps. Two pages, but a real system under them.
The rules that do the work
The whole setup reduces to a handful of conventions, each enforced by structure rather than discipline.
Tokens are the source of truth. Color, type, spacing, elevation, and
motion live as semantic CSS variables, bridged into Tailwind through @theme.
The variable and the utility can never disagree, because the utility is the
variable.
Routes stay thin. A file in src/pages/ maps a URL to a feature page and
does nothing else. Composition lives in the feature’s own folder, next to its
copy and helpers.
Copy lives apart from markup. Every user-facing string sits in a
content.ts as a typed constant. Rewording a page never touches layout code.
SEO is not per-page work. Canonical URLs, Open Graph, Twitter cards, and JSON-LD all render from one component that pages feed with props. A page cannot forget its meta tags, because it never writes them.
Why bother for two pages
Because the cost curve is flat. The foundation took one evening, and every page after it inherits the system for free. The blog you are reading this on — content collections, hub archives, feeds, the works — dropped onto this structure without changing a line of what came before.
The deeper reason is that conventions only work when they are older than the content. Retrofitting a design system onto fifty pages is a migration; starting with one means there is never a “before”.
If you are curious how the machine-facing half works — the markdown mirrors,
llms.txt, and structured data — that gets its own write-up in
How This Site Talks to LLMs.
