Notes on Clean CSS Architecture

After building a few small sites from scratch, I've started to notice patterns in how my CSS either stays manageable or turns into a mess. These are some notes — mostly for my future self — on what seems to work.

One File Is Fine (Really)

For small projects, a single stylesheet is perfectly fine. The urge to split everything into partials and imports comes from working on large codebases. A personal site with five pages doesn't need that complexity. One file, well-organized with clear section comments, is easier to navigate than ten small files.

CSS Custom Properties Change Everything

Using CSS variables (custom properties) for colors, spacing, and font sizes was the single biggest improvement I made. Changing the accent color of the entire site means editing one line. Before that, I was doing find-and-replace across hundreds of lines.

I keep all my variables in a :root block at the top of the file. Anyone reading the stylesheet can immediately see the design tokens without scrolling through rules.

Naming Things

I don't follow BEM or any strict methodology. Instead, I use descriptive class names that read like what they are: .project-card, .blog-list, .experience-item. If the name makes sense when you read the HTML without seeing the CSS, it's good enough.

The best CSS is the CSS you can delete without breaking anything you didn't intend to change.

Mobile-First vs. Desktop-First

I used to write desktop styles first and then override with media queries for mobile. Lately I've been doing the opposite — starting with a single-column layout and adding complexity for wider screens. It results in less code overall because the mobile layout is usually simpler.

None of this is groundbreaking, but writing it down helps me stay consistent. The goal isn't a perfect system — it's a system that doesn't get in the way six months later when I need to change something.