Design rationale · one page

Why this site looks the way it does.

Written for future-me, or whoever extends this next. The why ages worse than the what; this page is the why.

Reference notes

The vocabulary of this site borrows from four places, deliberately.

• Bartosz Ciechanowski — for treating a long article as a piece of careful typesetting, not a web page. Wide reading column, real diagrams, no chrome.
• Maggie Appleton & Andy Matuschak — for the “notes-as-first-class-output” idea. The Ideas stream and the Lab posts both descend from this.
• Edward Tufte — for sidenotes that live in the margin, and for the “remove all decorative ink” instinct that keeps tables and charts from getting crusty.
• Simon Willison & Julia Evans — for proving that writing-led, low-chrome blogs hold up for a decade. Aging well is a feature.

Type

Source Serif 4 for body. It renders cleanly on screen, supports real small-caps and old-style numerals, and reads as a technical serif rather than a bookish one. Inter for UI is deliberately boring — UI type should disappear, and Inter does. JetBrains Mono for code: ligatures available, never forced.

Indic fallbacks load only when the page actually renders Devanagari or Gurmukhi (:lang(hi), :lang(pa)) so the default font budget stays small. Total fontset target is <150 KB across all weights actually used, subset aggressively, self-hosted.

Color

One accent — deep teal — carries every interactive surface. Teal reads “engineering” without being clinical, and it ages well in both warm themes. The light background is a warm off-white (#FAF8F4), not paper-white; the dark background is a warm dark (#161310), not pure black. The dark theme is its own design, not an inverted light theme — saturation, contrast, and code colors are tuned independently.

Hairline 1 px borders, no gradients in chrome, no shadows, no neumorphism. Gradients are allowed inside content (a chart, a diagram) only if they carry meaning.

Layout

Single reading column, ~640 px text + a 14 rem sidenote gutter on wide viewports. Rhythm is on an 8 pt scale. Headings get visible # anchors on hover. Tables get ruled top and bottom, no zebra. Section dividers are typographic ornaments (default §), never <hr>.

Motion

Minimal: 150 ms ease on hover, smooth scroll on anchor click, fade on theme toggle. Everything respects prefers-reduced-motion: reduce. No scroll-triggered reveals, no parallax, no page transitions.

Performance & the build

Critical CSS (tokens + base + components) is around 28 KB uncompressed, well under the <30 KB gzipped target. No JS framework on reading pages; site.js is a small enhancement layer that the site degrades gracefully without. Theme is applied pre-paint via a 4-line inline boot script in each document head.

Accessibility

WCAG 2.1 AA minimum, AAA for body text contrast in both themes. Real focus rings (2 px, accent-colored, 2 px offset) on every interactive element. Semantic HTML (article, nav, aside, figure). Form labels are always visible — placeholder-as-label is forbidden. The site is fully usable with the keyboard alone, fully usable at 200% zoom, and fully usable with JavaScript disabled for reading flows.

What I’m worried about

The biggest aesthetic risk is that the engineer’s-notebook look done badly is just a default Hugo theme. The defenses against that are typographic details that take effort: real small-caps where the typeface supports them; old-style numerals running through body copy; hung punctuation in headings; sidenotes that actually sit in the margin; section ornaments that are chosen, not defaulted. If those start to slip, the whole thing starts to look generic.

See also: component library, tokens.css.