A design system for a one-page résumé
Why a personal site got tokens, a component catalogue and a checklist — and what it cost.
This site is one page of résumé, a 404, and an offline screen. It nevertheless has a design system: tokens in in1t.scss, a working-surface layer with ~30 documented components, a catalogue rendered at /design-system/, and a checklist that gates every visual change. This is the note on why, and what it costs.
Why a small site wants rules
A personal site has one maintainer and no reviews — which is exactly why it drifts. Every "quick" tweak to a colour or a margin lands in a rule body somewhere, and a year later the stylesheet is a list of exceptions. A résumé has an additional failure mode: the PDF. The print theme and the screen theme are the same document in two media, and unreviewed tweaks on screen show up as paper bugs weeks later, in front of a recruiter.
So the system here is deliberately small and deliberately written down:
- Tokens first. Every colour, radius, spacing step and duration is a custom property in
:root. Rule bodies never carry a literal value, so a theme change is a token change. - Three surfaces, one language. The public site, the ops layer (forms, tables, an app shell), and the print document each get their own stylesheet and voice — but they share the tokens, and the boundary is explicit.
- The catalogue is the test. A component that is not rendered on
/design-system/will drift; the page makes drift visible the day it happens.
What it cost
Time up front, discipline after. Roughly: the token pass over the existing stylesheet was an afternoon; the ops layer and its catalogue were the real investment; every new component since costs a §4 entry, a render on the reference page, and the checklist — dark and light, contrast, keyboard path, the 720px breakpoint, and a rebuild of the PDF.
Was it worth it for a one-page site? The honest answer: the catalogue is doing what documentation does best — it turned "I should probably keep this consistent" from a memory problem into a file I can read. The PDF generation pipeline (npm run pdf, the same markup through Chrome's print engine) paid for itself the first time the résumé changed.