CSS Architecture

Last updated:

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 theCSS 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 — Naming

Names that explain intent

Class names should describe purpose — not colour, position, or today's design trend.

The next developer should understand what a class does from its name — not from tracing fifteen selectors. Pick a system, document it on this page and in the CSS standard, and enforce it in review.

  • component names reflect purpose — site-header, content-card, not pink-box
  • utilities describe function — skip-link, content-prose — not implementation
  • state classes follow a documented prefix — see state classes
  • keep specificity flat — one class per concern where possible

Avoid

  • presentation in names — .text-blue-14px breaks when design shifts
  • styling by IDs or cryptic abbreviations — high specificity, poor reuse
  • framework leakage in application CSS — .bootstrap-row-col-md-6

04 — Practice

Architecture habits

Structure, specificity, layers, tokens — together.

  • quarantine vendor and legacy CSS in legacy/ — see cascade layers
  • folder structure mirrors layer order
  • low specificity — prefer single class selectors; avoid deep nesting
  • shared values via design tokens — not duplicated hex codes
  • co-locate component styles — one file per component where practical

05 — Avoid

Frontend archaeology

These patterns signal architecture debt.

  • !important as 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

06 — Close

Long-term maintainability

CSS should support the product for years — not create an excavation site.

Review CSS changes for layer placement, token use, and selector weight — same rigour as JavaScript modules.

Related: CSS code review checklist, CSS scope strategy.