CSS Architecture
Good CSS architecture reduces entropy; bad architecture creates specificity warfare.
01 — Purpose
CSS that survives handover
Good architecture reduces entropy; bad architecture creates specificity warfare and files nobody dares touch.
CSS architecture is how you organise files, naming, layers, and tokens so the next developer can change a button colour without a three-day investigation. It is organisational design — not a preprocessor feature.
Frontend Foundations uses LSCSS. See the CSS standard for full team rules.
02 — Principles
Predictable, scalable, maintainable
Styles should be understandable without oral tradition.
- predictable — same problem, same layer and naming approach every time
- scalable — new components do not require global rewiring
- understandable — selectors describe structure, not visual accident
- maintainable — safe to delete unused rules without roulette
03 — Practice
Architecture habits
Structure, specificity, layers, tokens — together.
-
quarantine vendor and legacy CSS in
legacy/— see cascade layers - folder structure mirrors layer order — see cascade layers
- low specificity — prefer single class selectors; avoid deep nesting
-
semantic class names — describe role, not appearance (
is_activenotis_pink) - shared values via design tokens — not duplicated hex codes
- co-locate component styles — one file per component where practical
04 — Avoid
Frontend archaeology
These patterns signal architecture debt.
-
!importantas default override — fix layer order instead - styling by ID or tag cascades that fight every new feature
- deeply nested SCSS that mirrors DOM depth
- duplicated spacing and colour values across dozens of files
05 — Close
Long-term maintainability
CSS should support the product for years — not create a excavation site.
Review CSS changes for layer placement, token use, and selector weight — same rigour as JavaScript modules. Architecture is what you do on every pull request.
Related: CSS code review checklist, design tokens.