Mastering Clean CSS: Architecture, Naming Conventions, and Best Practices

What makes good CSS code?

Maintainable stylesheet

Readable code

Scalable stylesheet

To keep CSS clean, establish a consistent team style guide, starting with CSS architecture.

CSS Architecture

There are five main design architectures:

1. OOCSS

Object‑Oriented CSS separates structure from theme and theme from skin, reducing HTML dependency and increasing reuse.

2. BEM

A naming methodology that makes page structure clear: Block, Element, Modifier.

Key rules include:

Block elements should focus on the element’s own properties.

Elements depend on their position and shape.

Modifiers describe current state or theme.

Elements must exist inside a Block.

Modifiers mainly represent component shape and state.

In component‑based scenarios, a Block represents an independent UI component, while Elements encapsulate behavior (JavaScript), template, and style.

3. SMACSS

SMACSS (Scalable and Modular Architecture for CSS) defines three main guidelines: categorizing CSS rules, naming rules, and minimizing depth of applicability.

It splits CSS into Base, Layout, Module, State, Theme, and JavaScript hooks.

.button {
  font-family: Arial, sans-serif;
  border: 1px solid #eee;
  color: #ddd;
}

textarea {
  @extend .button;
  padding: 10px;
}

4. ITCSS

ITCSS adds a detailed layering: Settings, Tools, Generic, Base, Objects (Layout), Components (Module), and Trumps (State, Theme).

5. ACSS

Atomic CSS (e.g., TailwindCSS) uses one class per property, improving utility but reducing semantic meaning.

.block { display: block; }
.hidden { display: none; }
.p-2 { padding: 0.75rem; }
.flex { display: flex; }
.text-base { font-size: 1rem; }
.bg-green-200 { background-color: #123456; }

Comments and Spacing

Use clear section comments and appropriate blank lines to convey structure.

/*------------------------------------*
 #A-SECTION
*------------------------------------*/
.selector { }

/*------------------------------------*
 #ANOTHER-SECTION
*------------------------------------*/
.another-selector { }

Recommended Principles

Single Responsibility Principle

/* Correct */
.button {
  font-family: Arial, sans-serif;
  border: 1px solid black;
  background: #fff;
}
.header__button {
  margin: 30px;
  position: relative;
}

/* Incorrect */
.header__button {
  font-family: Arial, sans-serif;
  position: relative;
  border: 1px solid black;
  margin: 30px;
}

Open/Closed Principle

<!-- Extend with modifier -->
<button class="button button_size_s">...</button>
.button_size_s {
  font-size: 13px;
  line-height: 24px;
}

DRY Principle

@mixin my-web-font() {
  font-family: "My Web Font", sans-serif;
  font-weight: bold;
}

.btn {
  display: inline-block;
  padding: 1em 2em;
  @include my-web-font();
}

Composition over Inheritance

<div class="layout">
  <div class="layout__item two-thirds">
    <section class="content">...</section>
  </div>
  <div class="layout__item one-third">
    <section class="sub-content">...</section>
  </div>
</div>

References:

BEM Introduction

OOCSS Introduction

Exploring SMACSS

Writing Efficient CSS Selectors

CSS Single Responsibility Principle

Thinking about CSS Architecture