CSS Architecture & Naming Conventions
Why CSS needs deliberate naming and structure at scale, and how BEM, utility-first CSS, and custom properties each address the specificity-war problem.
CSS Architecture & Naming Conventions
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- A specificity war happens when developers respond to style conflicts by writing more specific selectors or adding !important, which escalates rather than resolves the underlying problem.
- BEM (Block, Element, Modifier) names classes to describe a component's structure directly in the class name, so almost every selector stays at the same, low specificity.
- Utility-first CSS (like Tailwind) takes the opposite approach: tiny, single-purpose classes composed directly in markup, trading some HTML verbosity for near-zero specificity conflicts.
- Component-scoped CSS (CSS Modules, styled-components, Vue/Svelte scoped styles) sidesteps naming collisions entirely by generating unique class names per component at build time.
- CSS custom properties (variables) let you define a value once and reference it everywhere, and they can be scoped and overridden per component the same way regular CSS properties can.
The problem that only shows up at scale
A single-page site with 200 lines of CSS doesn’t need an architecture. You can see the whole stylesheet at once, and if two rules conflict, you just scroll up and fix it. That stops being true somewhere around the time a project has a few dozen components, written by more than one person, over more than a few months. At that point, CSS’s biggest structural weakness starts to bite: every single rule in a CSS file can affect every element on the page that matches its selector, with no built-in way to contain that effect to one component. Unlike a JavaScript function, a CSS rule has no natural scope boundary.
This produces a very specific, very common failure mode: the specificity
war. Someone writes .card { padding: 16px; }. Someone else, working on a
different page, needs a card with different padding, and rather than
understanding why the existing rule applies, they write
.sidebar .card { padding: 24px; } to beat it on specificity. A third
person needs to override that, so they reach for !important. Now the
codebase has three competing rules for the same property, each written to
defeat the last one, and nobody can predict what a fourth change will do
without testing it in the browser. None of the tools you’ve learned so
far — the box model, Flexbox, Grid — fix this. It’s a structural problem,
and it needs a structural answer: a deliberate naming and organization
convention that the whole team agrees to use.
BEM: let the class name describe the structure
BEM — Block, Element, Modifier — is a naming convention, not a new CSS feature. The idea is to encode a component’s structure directly into class names, so the relationship between pieces is obvious just by reading the HTML, and so that almost every selector in your stylesheet stays at the same specificity level (a single class).
- Block — a standalone component:
.card. - Element — a part of that block, joined with a double underscore:
.card__title,.card__image. - Modifier — a variation on a block or element, joined with a double hyphen:
.card--featured,.card__title--large.
<div class="card card--featured">
<img class="card__image" src="..." />
<h3 class="card__title card__title--large">Headline</h3>
</div>
.card { /* base block styles */ }
.card--featured { /* modifier override, still specificity of one class */ }
.card__title { /* element styles */ }
.card__title--large { /* element modifier */ }
Notice what’s absent: no nested selectors like .card .title, no
.sidebar .card reaching across components. Every rule targets exactly one
flat class, so no selector ever needs to out-rank another one — there’s
nothing to fight over, because each name only ever means one specific thing.
The tradeoff is verbosity: class names get long, and the convention requires
discipline, since nothing in CSS enforces BEM syntax for you. It’s a social
contract, not a compiler rule.
Utility-first: skip component CSS almost entirely
A newer approach, popularized by Tailwind CSS, takes the opposite bet: don’t write component-level CSS classes at all. Instead, compose a component directly in markup from small, single-purpose utility classes:
<div class="rounded-lg shadow-md p-4 bg-white">
<h3 class="text-xl font-bold">Headline</h3>
</div>
Each class does exactly one thing — p-4 sets padding, text-xl sets font
size — and virtually never needs to be overridden by another rule, because
you adjust the component by adding or removing classes in the markup, not by
writing new CSS. This sidesteps specificity wars almost entirely, since
there’s rarely a competing rule to out-rank. The tradeoff moves in the
opposite direction from BEM: markup gets noisy and repetitive, and some
developers find it harder to read the intent of a component versus its
individual style declarations. Both are legitimate, widely used approaches —
picking one is often more about team preference and project shape than one
being objectively better.
Component-scoped CSS: let tooling solve it instead of convention
A third approach doesn’t rely on naming discipline at all — it uses build
tooling to generate unique class names automatically, so collisions become
structurally impossible rather than merely avoided by convention. CSS
Modules, styled-components, and the built-in scoped styles in frameworks
like Vue and Svelte all work this way: you write .title { ... } as if it
were global, and the build step rewrites it to something like
.title_a8f3k behind the scenes, unique to that component. Two components
can both have a class called .title and never conflict, because the
tooling guarantees the generated names never collide. This is often the
smoothest option in a framework-based project, precisely because it doesn’t
depend on every contributor remembering and following a naming convention —
the guarantee is enforced by the build step, not by agreement.
Custom properties: one value, many consumers
None of the conventions above address a separate, common need: reusing the same value — a brand color, a spacing unit, a border radius — in dozens of places without retyping it. CSS custom properties solve this natively:
:root {
--brand-color: #3b5bdb;
--spacing-unit: 8px;
}
.button {
background-color: var(--brand-color);
padding: calc(var(--spacing-unit) * 2);
}
Set once on :root, a custom property is available everywhere, and — unlike
a preprocessor variable, which gets resolved once at build time and baked
into static output — a CSS custom property is live in the running page. It
can be read and changed with JavaScript, and it can be redeclared at a more
specific scope to override it locally, the same way any other CSS property
cascades:
.dark-theme {
--brand-color: #748ffc;
}
Anything inside .dark-theme that references var(--brand-color)
automatically picks up the new value, with no JavaScript required. This
makes custom properties a genuine architecture tool, not just a convenience:
they’re how a lot of real dark-mode implementations and themeable design
systems work under the hood.
Picking an approach
None of BEM, utility-first, or component-scoped CSS is strictly correct — each is a different trade between verbosity, tooling dependency, and discipline. What matters is picking one deliberately, applying it consistently across a project, and understanding that the goal in every case is the same: keep specificity flat and predictable, so the next person who touches the stylesheet can change one thing without triggering a chain of unrelated overrides somewhere else.
Check yourself
What is a specificity war, and why does adding !important usually make it worse rather than better?
It's an escalating cycle where developers override a style they can't beat by writing an even more specific selector or adding !important, which then becomes the new thing a future override has to beat. !important sits outside the normal specificity hierarchy, so once it's used, the only way to override that rule later is with another !important or a less maintainable hack, compounding the problem instead of fixing it.
In BEM, what do the double-underscore and double-hyphen in a class like card__title--large signal?
The double underscore separates the block name (card) from an element within it (title) — a part of the component. The double hyphen marks a modifier (large) — a variation on that block or element's appearance or state. The naming itself documents the component's structure.
Why does utility-first CSS largely avoid the specificity problems that plague hand-written component CSS?
Utility classes are single-purpose and nearly always consist of one class selector each, so almost every rule sits at the same, flat specificity level. There's rarely a need to override one utility class with another, because you simply add or remove classes in the markup instead of writing new CSS to fight an existing rule.
What advantage do CSS custom properties have over a Sass variable for something like a brand color used across a site?
A Sass variable is resolved at compile time and becomes a fixed value baked into the output CSS — it cannot change after that. A CSS custom property is live in the browser, can be read and changed with JavaScript, and can be overridden at different scopes (like inside a specific component or a dark-mode selector), making it useful for things that need to change at runtime, not just at build time.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.