Why I’m writing my own CSS for this site

The first real decision on this site was what to build the interface on. I picked the option that takes the most work up front, and here’s why.

What the site actually needs

A portfolio doesn’t need much: buttons, cards, a case-study header, a theme switch, and a small tool for exploring the color tokens. That’s roughly 8 to 12 components. The question was never whether a library could handle it. Any of them could. The question was what each choice would say about the work, and what it would cost me.

The options I weighed

• A copy-in component kit (shadcn/ui on Tailwind)Fastest · rejected

  The quickest way to a good-looking site, and coding agents know it extremely well. But the default look is easy to recognize, and on a design portfolio that weakens the claim that I designed what you’re looking at.

• A full component library (MUI)The one I know best · rejected

  I’ve built a design system on it at work, so it would be comfortable. It’s also heavy for a handful of pages, and it would tell the same story twice.

• Everything from scratch, including keyboard and focus behaviorMost craft · rejected

  Writing my own focus traps and keyboard handling for a dialog shows effort, but it doesn’t make the site better for anyone. That part is a solved problem.

• Hand-written CSS driven by tokens, with accessible primitives only where neededChosen

  I write the styles and the components. If a hard interactive piece comes up, like a dialog or a tooltip, I use an unstyled primitive (Radix or Base UI) for the behavior and style it myself.

How it works

Every value starts in one token file. Base values (the raw colors and sizes) sit at the bottom, and the semantic tokens the components use, like “text on accent,” point to them. A build step turns that file into CSS custom properties, so the same variables work in the static Astro pages and in the React pieces.

The token file also lists the text and background pairs that have to be readable together. If a change pushes one of those pairs below its contrast target, the build fails. I’d rather find that out from a failed build than from someone squinting at the page.

What I’m giving up

Speed, mostly. A kit would have had me further along today, and its components have years of edge cases worked out that mine don’t yet. I’m accepting that because the site is small and the payoff is specific: every visible pixel is a decision I made, and I can explain each one.

There’s a second payoff. A token file in a known format is something tools can read. Next, I’m building a small tool that lets coding agents look up these tokens and check contrast, so they use the system instead of hardcoding values.

The rule I’m keeping

Borrow where it’s a commodity, design where it shows taste. If I catch myself rebuilding focus handling for a dialog, that’s my cue to reach for a primitive, not to write it myself.