A short guide to CSS architecture

The advice here is unglamorous, which is probably why it gets skipped. Everything we would tell a client about CSS architecture in the time it takes to drink a coffee.

Most development decisions are really maintenance decisions wearing a different hat. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

Why it matters

Naming conventions prevent the specificity arms race. Small and consistent beats large and occasional here. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

How we handle it

Custom properties centralise the values you change most. This is the sort of thing that compounds, quietly, in both directions. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

The mistakes we see most

Deleting CSS should be as easy as adding it. The reasoning matters more than the rule, because the rule has exceptions. It is the sort of thing that looks like polish right up until it costs you an enquiry.

What this looks like day to day

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Three things worth confirming about CSS architecture before you move on:

• Someone can say what the current setup is without going to look
• Deleting CSS should be as easy as adding it — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Most of the value here comes from doing the first two things, not all of them.