CSS Naming Conventions

Naming conventions improve maintainability — class names should describe purpose clearly.

01 — Purpose

Names that explain intent

Naming conventions improve maintainability and readability — class names should describe purpose clearly.

CSS without naming discipline becomes archaeology. The next developer should understand what a class does from its name — not from tracing fifteen selectors or guessing which framework leaked in.

This site follows LSCSS — see CSS architecture and the CSS standard for project conventions.

02 — Principles

Purpose over presentation

Naming systems should reduce cognitive load.

  • predictable structure — block, element, modifier or layer-based patterns used consistently
  • readable naming — full words over cryptic abbreviations
  • consistent patterns — same rules for components, utilities, and layout
  • restrained specificity — names should not require long compound selectors

03 — Practice

Good naming conventions

Describe role and structure — not colour, position, or today's design trend.

  • component names reflect purpose — site-header, content-card, not pink-box
  • child selectors use clear hierarchy — .site-header > .inner or BEM-style elements where the project defines them
  • utilities describe function — skip-link, vh, content-prose — not implementation
  • state classes follow a documented prefix — see state classes
  • keep specificity flat — one class per concern where possible

04 — Avoid

Naming that obscures

Bad names force every change through grep and hope.

  • overly verbose naming — page-section-hero-banner-wrapper-inner-container
  • unclear abbreviations — .c-hdr-nav-lnk saves characters, not time
  • styling by IDs — high specificity, poor reuse, brittle overrides
  • framework dependency leakage — .bootstrap-row-col-md-6 in application CSS
  • presentation in names — .text-blue-14px breaks when design shifts

05 — Close

Consistency beats cleverness

Pick a system, document it, and enforce it in review.

New contributors should find one page that explains how classes are named. Deviations need a reason — not personal preference.

See CSS architecture, state classes, and CSS standard.