CSS Architecture

Eduardo de la Cruz Palacios — Mon, 04 May 2026 20:37:05 +0000

Have you ever opened a large codebase and wondered why changing one color broke styles in five unrelated places? Or why two buttons that look identical are defined in completely different ways across the project?

These are symptoms of the same root problem: no clear separation between layers of concern in the CSS. CSS Architecture exists precisely to solve this.

Have you noticed that popular libraries like Tailwind or Bootstrap follow recognizable naming patterns such as btn, btn--disabled, and color-primary? That's not coincidence. Those patterns reflect an underlying architectural model, i.e., a shared set of conventions that brings structure to the way styles are written, organized, and scaled across a project.

This post breaks down what CSS Architecture is, why it matters, and how to apply it.

Definition and purpose

CSS Architecture is a set of conventions, principles, and patterns that bring structure to the way styles are written, organized, and scaled across a project. Rather than leaving each developer to make ad-hoc decisions, it establishes a shared language that the whole team follows.

This structured approach enables teams to develop more efficiently, reduce regressions, and deliver consistent interfaces that scale with the product over time.

To understand why, let's break it down into its benefits:

Scalability, maintenance & reusability: The codebase should grow without collapsing. Adding a new component shouldn't require rewriting global styles or introduce visual regressions elsewhere. Define once, use everywhere to avoid reinventing the wheel and copy-pasting styles that drift out of sync. Also, the time to learn the codebase, make changes and debug visual regressions is reduced.
Collaboration & onboarding speed: When conventions are explicit (naming, file structure), multiple developers can work in parallel without stepping on each other. Reviews are faster and merge conflicts are fewer. When styles are predictable, new developers can jump in more quickly.
UX & theming: Users experience a coherent product with the same spacing, typography, and color signals throughout every screen and flow. Furthermore, a well-architected system makes dark mode, white-labeling, or brand refreshes a token swap instead of a full rewrite. If colors and spacing are hardcoded everywhere, a rebrand becomes a nightmare.

In summary, architecture gives you guardrails as the team and product expand.

Abstraction layers in UI

Well-architected UI systems split styles into distinct, purposeful layers. Each layer answers exactly one question, and never answers another layer's question.

These are examples of abstraction layers you will find across libraries and design systems:

Tokens: The raw design values of the system such as colors, spacing, border radius, or shadows. Everything else references these. Changing a token propagates everywhere automatically.
Themes: Token overrides scoped to a context, such as dark mode, brand variants, high-contrast accessibility mode, or white-label products. Themes swap values; they don't rewrite component logic.
Layout: How children are distributed inside a parent: grids, flexbox, spacing between siblings, or page regions like main and header. Layout classes are agnostic of visual design, so they must not carry colors, borders, or shadows.
Components: The visual identity of a UI piece such as a button, card, badge, or input. Components own their own appearance (color, border, typography) but are completely unaware of where they sit on the page. It means a component must render correctly regardless of its parent, which is achieved by not including positional styles inside a component.
States: Variations of a component triggered by user interactions or system context, such as hover, focus, active, disabled, loading, error, or selected. States modify a component without replacing it.
Utilities: Single-purpose helper classes for one-off adjustments that don't belong in a component, e.g., cursor-pointer and border-0.

Methodologies to implement CSS Architecture

Object-Oriented CSS (OOCSS)

OOCSS focuses on building flexible and reusable components where each class does one thing well. Coined by Nicole Sullivan, it borrows the principles of object-oriented programming and applies them to CSS: identify repeating visual patterns, abstract them into reusable objects, and compose them freely across the UI.

It is the mindset and/or method of separating:

Containers and content: a component should not know where it lives. Avoid location-specific styles that tie appearance to a position in the DOM, such as nested selectors like .page .content h3 {}. If a heading needs a style, that style belongs on the heading itself instead of its ancestors.
Structural and visual styling: keep layout concerns like padding, margin, and display separate from visual ones like colors, fonts, and borders. This way, the same structure can wear different skins, and the same skin can be applied to different structures.

Tradeoffs:

More maintainability: reducing or eliminating duplication in CSS means fewer places to update when a design decision changes.
More classes per element: composing styles from multiple single-purpose classes means HTML elements tend to carry more class names, which can feel verbose and harder to read at a glance.

Example 1:

/* BAD */

.page-about {
  background-color: grey;
  display: flex;
}

.page-contact {
  background-color: white;
  display: flex;
}

/* BETTER

<section class="page page-contact">...</section>

*/

.page {
  display: flex;
}

.page-about {
  background-color: grey;
}

.page-contact {
  background-color: white;
}

Example 2:

/* BAD */

article.card {
  column-gap: 10px;
  display: flex;
  flex-direction: row;
}

div p {
  background-color: #ddd;
  color: #111;
  font-size: 1.25rem;
  padding: 8px 12px;
  text-align: right;
}

/* BETTER

<article class="card-container bgc-primary">

    <div class="card">
        <p class="card-content text-primary"></p>
    </div>

</article>

*/

:root {
  --fontSizeL: 1.75rem;
  --fontSizeM: 1.25rem;
}

.card-container {
  column-gap: 10px;
  display: flex;
  flex-direction: row;
}

.bgc-primary {
  background-color: #ddd;
}

.card {
  padding: 8px 12px;
}

.card-content {
  font-size: var(--fontSizeM);
  text-align: right;
}

.text-primary {
  color: #111;
}

Learning resources:

Atomic / Functional CSS (ACSS)

ACSS focuses on creating the smallest possible single-purpose utility classes and applying them directly in the HTML. Rather than writing semantic component classes that bundle multiple declarations together, each class maps to exactly one CSS rule.

The name comes from the idea of atoms: the smallest indivisible unit of style.

Tradeoffs:

Classes are immutable: an atomic class always does the same thing regardless of context, making the CSS highly predictable. .mt-16 will always apply a 16px top margin. It will never be overridden by another rule or behave differently depending on where it is used.
Reusable across projects: because atomic classes carry no semantic meaning tied to a specific UI or domain, the same utility layer can be dropped into entirely different projects without modification.
Easier to debug: since styles live directly in the HTML as class names, you can inspect an element and immediately understand what is being applied without jumping between files or hunting through cascading rules.
Verbose upfront: the initial cost is high, as there are many classes to define before the system pays off, and HTML markup can become dense with long chains of class names on a single element.
Watch out with absolute values: atomic classes that encode fixed values like w-320 or text-14 can cause problems across devices and screen sizes. Prefer classes built on a relative scale or design tokens to keep the system adaptable.

Example:

.bg-blue {
  background-color: blue;
}

.bg-yellow {
  background-color: yellow;
}

.text-2rem {
  font-size: 2rem;
}

.padding-0 {
  padding: 0;
}

.padding-1 {
  padding: 1;
}

/*

<article class="bg-blue padding-1">
    <p class="text-2rem"></p>
</article>

*/

Learning resources:

https://css-tricks.com/lets-define-exactly-atomic-css/

Block Element Modifier (BEM)

BEM is a naming convention for CSS classes that brings clarity and predictability to how styles are structured and related. Rather than relying on the cascade or nesting to express relationships between parts of a UI, BEM makes those relationships explicit in the class name itself.

A Block is a standalone component, an Element is a part that belongs to a block and has no meaning outside of it, and a Modifier is a variation of a block or element.

Tradeoffs:

More control over specificity: because BEM styles are almost entirely class-based and flat, there is little or no nesting in the CSS. This keeps specificity low and uniform across the codebase, which means fewer unexpected overrides and side effects when styles are added or changed.
Blocks must remain independent: a block should never override the styles of another block or its modifiers. When it does, specificity is no longer controlled and the predictability that BEM provides starts to break down. Each block is responsible for itself and nothing else.

Syntax:

Modifiers apply to both blocks and elements like block--modifier and block__element--modifier.
Naming must be meaningful and non-descriptive of appearance. If a class name describes how something looks rather than what it is, renaming it becomes necessary every time the visual design changes, so it forces updates to both the selector and the styles. blog-post__title and button--primary are correct. yellow-title is wrong.
Elements should be written as direct children of their block, never nested beyond one level. Deep nesting creates class names that are tightly coupled to a specific DOM structure, making them fragile and hard to reuse. photo__caption and photo__text are correct. photo__caption__text is wrong.

Example:

.social {
  display: flex;
}

.social--vertical {
  flex-direction: column;
}

.social__link {
  align-items: center;
  font-size: 1.5rem;
  justify-content: center;
  text-decoration: none;
}

.social__image {
  height: 24px;
  width: 24px;
}

.social__image--network1 {
  background-color: blue;
}

.social__image--network2 {
  background-color: red;
}

/*

<section class="social social--vertical">

    <a href="#" class="social__link">
        <img src="fb.svg" class="social__image social__image--network1">
    </a>

    <a href="#" class="social__link">
        <img src="tw.svg" class="social__image social__image--network2">
    </a>

</section>

*/

Learning resources:

Inverted Triangle CSS (ITCSS)

ITCSS organizes CSS into a set of ordered layers, each with a clear role and a defined level of specificity.

Source: https://www.wpdesk.pl/blog/struktura-itcss-czyli-jak-zapanowac-nad-plikami-css/

Each layer is explained in detail below:

Settings: variables used by other layers.
Tools: functions and mixins used by other layers.
Generic: reset or normalize browsers’ base styles.
Elements: rules affecting HTML tags.
Objects: generic classes that are reusable throughout the project, such as .container.
Components: specific parts of the interface, such as the main navigation bar. Styles here will only affect that component.
Trumps / Utilities: rules that override any other rules defined in the previous layers. It is the only layer where !important is allowed. For instance, a selector for a class .hidden with display: none.

The inverted triangle metaphor is intentional: the widest, most generic styles sit at the top and affect the broadest scope, while the narrowest, most specific styles sit at the bottom and affect the smallest scope. Rules flow in one direction from low specificity to high, which prevents the specificity conflicts and accidental overrides that result in unstructured codebases.

Tradeoffs:

Specificity is always intentional: as each layer has a defined place in the order, styles never fight each other by accident. It reduces the amount of side effects.
Highly compatible with other methodologies: ITCSS is not a naming convention, so it works alongside BEM, OOCSS, or ACSS without conflict. While it provides the folder and layer structure, other methodologies handle the naming within each layer.
Requires upfront discipline: the system pays off at scale, but it demands that the team agrees on and respects the layer boundaries from the start. Dropping styles into the wrong layer quietly undermines the entire model.
Though not strictly required, ITCSS strongly encourages the use of a CSS preprocessor such as Sass or Less to increase the productivity of the team.

Example for Sass preprocessor:

/* Should live in: settings/colors.settings.scss */

$colorPrimary: #000;

/* Should live in: tools/mixins/polygons.mixins.tools.scss */

@mixin circle {
  border-radius: 50%;
  height: 50px;
  width: 50px;
}

/* Should live in: generic/reset.generic.scss */

* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

/* Should live in: elements/text.elements.scss */

@import '../settings/colors.settings.scss';

h1,
h2,
h3,
p {
  color: $colorPrimary;
}

/* Should live in: objects/flex.objects.scss */

.container-flex-vertical {
  display: flex;
  flex-direction: column;
}

/* Should live in: components/icon.components.scss */

.icon {
  height: 24px;
  width: 24px;
}

/* Should live in: trumps/display.trumps.scss */

.display-none {
  display: none !important;
}

Learning resources:

Scalable and Modular Architecture for CSS (SMACSS)

SMACSS provides a set of abstraction layers built around the following idea: certain CSS properties belong in certain layers and nowhere else.

Tradeoffs:

Scalability and maintenance: by enforcing a clear separation between layers, SMACSS prevents styles from bleeding into the wrong context. As the codebase grows, each layer remains predictable and contained, making it significantly easier to locate, change, and extend styles without unintended side effects.
Though not strictly required, SMACSS strongly encourages the use of a CSS preprocessor such as Sass for productivity's sake. Splitting styles across multiple layers naturally leads to multiple files, and a preprocessor makes importing, organizing, and sharing variables across those files easier to maintain.

Abstraction layers:

Base: the default styles for bare HTML elements. Wherever this element appears on the page, it should look like this. No classes or IDs, but only element selectors, resets, and normalize rules.
Layout: styles that hold one or more modules together and define the major structural regions of a page, such as the header, footer, sidebar, or main content area. Layout is concerned with position and dimension, not visual appearance.
Module: the reusable, modular parts of the design such as a product card, a navigation menu, or a search form. Modules are self-contained and should work correctly regardless of which layout region they are placed in.
State: describes how a module looks in a particular condition triggered by user interaction or system context, such as an expanded or collapsed accordion, a success message, or an error input. State styles are always applied on top of a module and override only what needs to change.
Theme: a consistent set of visual styles applied across layouts and modules to define the overall look and feel of the application.

Example for Sass preprocessor:

/* Should live in: base/reset.base.scss */

* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

/* Should live in: layout/footer.layout.scss */

.footer-container {
  display: grid;
  grid-template-columns: auto auto auto;
}

/* Should live in: modules/form-login.module.scss */

.form-login {
  border: 5px solid red;
}

/* Should live in: state/dropdown.state.scss */

.dropdown__button-expanded {
  font-weight: bold;
}

.dropdown__button-collapsed {
  font-weight: normal;
}

/* Should live in: theme/dark.theme.scss */

@import '../base/colors.base.scss';

:root .dark {
  background-color: $black-color;
  color: $white-color;
}

:root .white {
  background-color: $white-color;
  color: $black-color;
}

Learning resources:

http://smacss.com/

CSS Specificity and CSS Architecture

Specificity is the rule the browser uses to decide which CSS declaration wins when two or more rules target the same element. It is not about order in the file, but about weight. Every selector carries a score, and the declaration with the highest score is the one that gets applied.

The score is calculated across three tiers. IDs carry the most weight, followed by classes, attributes, and pseudo-classes, and finally element selectors and pseudo-elements. Inline styles sit above all of them, and !important overrides everything.

A rough way to read it is as three numbers (IDs, classes, elements):

a (0, 0, 1 element).
.nav a (0 IDs, 1 class, 1 element): beats the one above.
#header .nav a (1 ID, 1 class, 1 element): beats the two above.
<a style="...">: inline, beats all of the above.
color: red !important: overrides everything.

The problem arises when specificity grows uncontrolled. A developer adds a rule that does not apply, so they make the selector more specific to force it through. Another developer encounters the same problem and goes one level higher. Over time the codebase accumulates deeply nested selectors and scattered !important declarations. At that point, the only way to override anything is to keep escalating, which makes the CSS increasingly fragile and unpredictable.

This is exactly where CSS architecture becomes essential. Methodologies like BEM deliberately keep all styles at the class level without nesting, which means every rule carries the same low specificity score of (0, 1, 0). Then, there are no ~~surprises~~ side effects. ITCSS takes a structural approach to the same problem: by ordering layers from lowest to highest specificity, it ensures that a utility class at the bottom of the triangle will always override a base element style at the top.

In short, unmanaged specificity is one of the most common reasons CSS becomes painful to maintain at scale. CSS Architecture brings specificity under deliberate control.

Learning resources:

Recommendations for various kinds of Frontend projects

CSS libraries and frameworks

When building a CSS library or framework, the audience is other developers, which means clarity, predictability, and ease of use are non-negotiable. The architecture must be easy to learn, contribute to, and to maintain over time as the library evolves and grows.

Two concerns are especially important here:

Maintenance of the library itself: as new components are added and existing ones are updated, the architecture must prevent regressions and keep specificity under control. Styles should never collide with each other, and contributors should always know exactly where a new rule belongs.
Ease of use for other developers: a library with a predictable naming convention and a clear structure is significantly easier to adopt, extend, and override. Developers consuming the library should be able to look at a class name and immediately understand what it does and where it comes from.

Because we rarely know how large a library or framework will grow, it is important to choose an architecture that scales gracefully from the start rather than one that needs to be restructured later:

ITCSS or SMACSS are recommended as the overall organizational structure. Both provide a layered approach that accommodates growth without collapsing under its own complexity, and both keep specificity intentional and ordered.
BEM is recommended for naming the classes of individual components within those layers. It makes the relationship between a block, its elements, and its modifiers explicit in the class name itself.
OOCSS: since a library is essentially a collection of reusable objects, the OOCSS mindset of separating structure from visual design fits naturally.
Utility layer (ACSS): most mature libraries like Bootstrap and Tailwind expose a utility layer alongside their components. Even if the library is not fully atomic, offering a set of single-purpose utility classes gives consumers flexibility for one-off adjustments without overriding component styles directly.

HTML-CSS-JS projects

Projects with a limited or small scope

When a project has a clearly defined and limited scope, e.g., a landing page, a promotional site, or a prototype that is not expected to grow significantly, we can afford a lightweight approach. In these cases, BEM alone is a suitable option. It brings enough structure to keep class names meaningful and styles predictable without introducing the overhead of a full layered system. The goal here is clarity and speed, not long-term scalability.

Large or long-lived projects

When the project is expected to grow, be maintained over time, or be worked on by multiple developers, a more robust architecture becomes necessary. BEM alone may not be sufficient, as the absence of a clear layer structure makes it increasingly difficult to know where new styles belong and how they relate to existing ones.

In these cases, the same formula is recommended: ITCSS or SMACSS as the organizational backbone, OOCSS as the guiding mindset when designing components, and BEM for naming classes within them.

Web components library or design systems

Web components are built around a fundamental philosophy: each component owns its styles entirely. A button, an input, or a modal ships with its own CSS encapsulated inside it, i.e., no styles leak in from the outside, and no styles leak out. This is enforced by the Shadow DOM, which creates a hard boundary between a component's internal styles and the rest of the page.

This encapsulation changes how architecture is applied, but it does not eliminate the need for it. A few important considerations:

Encapsulation does not mean isolation from a system, as components still need to feel cohesive across the library. ITCSS or SMACSS can still provide the organizational backbone at the system level, not for writing styles directly but for managing the design tokens and variables that components consume. This allows the library to remain consistent and themeable without breaking encapsulation.
CSS custom properties are the bridge. As CSS variables pierce the Shadow DOM boundary, they are the primary mechanism for making components customizable and for applying themes across the entire library. A well-architected token layer that exposes variables like --color-primary or --spacing-md gives consumers the ability to skin the whole library by overriding a handful of values, without touching any component internals.
Exposed attributes for style variants: components can expose HTML attributes or CSS parts that allow consumers to trigger specific styles from the outside. This is the idiomatic way to handle variants and states in a web components context, keeping the API surface clean and intentional.
BEM for complex components: while simple components like a button or a badge may not need a formal naming convention internally, more complex components such as a date picker, a data table, or a photo gallery can grow significantly in internal complexity. Applying BEM within those components brings the same benefits it does anywhere else: clear relationships between parts, predictable specificity, and easier maintenance as the component evolves.
Design tokens as the foundation. They are not optional in a design system context. They are the contract between design and development. Defining tokens at the system level and having every component reference them ensures that a single change propagates consistently across the entire library, which is the core promise of a design system.

JS-framework projects: Angular, Lit, React, etc.

Teams working with component-based frameworks often develop their own internal agreements about how to organize CSS, and those conventions vary significantly from project to project.

Although teams working with these technologies may organize CSS differently from the approaches seen in this post, the same formula is still recommended: ITCSS or SMACSS as the organizational backbone, OOCSS as the guiding mindset when designing components, and BEM for naming classes within them.

In addition, it is crucial to style at the correct layer of abstraction to avoid CSS side effects. One of the most common pitfalls is solving a layout problem in the wrong place, e.g., adding margin to a product card component in order to fix the spacing in a product list. The component is now making assumptions about its context, which breaks its reusability. Layout concerns belong in the layout layer, and component concerns belong in the component layer. Keeping that boundary clean is what prevents side effects from accumulating over time.

Another relevant point stems from the fact that frameworks like Angular, React and Lit automatically ensure that the styles you write inside a component only apply to that component. A common misconception is that scoping solves the architecture problem. It does not. Here is why: Scoping answers the question "will my styles affect something outside this component?" The answer is no. But it does not answer "are the styles inside this component well organised, predictable, and easy to maintain?". That is entirely up to the developer. This is why BEM and OOCSS still matter inside scoped styles. The scope handles the boundary with the outside world, but the architecture handles the quality and predictability of what lives inside that boundary. Both are needed.

Final thoughts

Purpose: caring about CSS reduces side effects and improves maintainability

A deliberate approach to CSS architecture reduces the surface area for side effects, makes styles easier to reason about, and significantly lowers the effort required to change, extend, or debug the UI as the project grows. The methods covered in this post are an investment in the long-term health of the codebase.

Flexibility

None of the architectures and methodologies covered here should be applied dogmatically. They are tools, not laws. In practice, the most effective approach is rarely a single methodology applied in its pure form, but a combination tailored to the specific needs of the project and the team.

This flexibility manifests in several ways:

Combining methodologies: ITCSS for layer structure, BEM for component CSS classes naming, and OOCSS as the guiding mindset is a common and effective combination, as seen throughout this post.
Adding abstraction layers: if your project has recurring patterns that do not fit neatly into an existing layer, adding a new one is entirely valid. The goal is clarity, not compliance.
Removing unnecessary layers (YAGNI): if a layer does not serve a purpose in your project, do not include it. A small project does not need all seven ITCSS layers. Start with what you need and add layers only when the complexity justifies them.

Real life decisions are harder than theory

The gap between understanding a methodology and applying it confidently in a real codebase is significant.

Two questions come up repeatedly in practice:

Separating container from content sounds straightforward until you encounter a project with multiple container types that share some styles but not others, or content that behaves differently depending on where it is placed. The line between the two is rarely as clean in practice as it is in a diagram.
Deciding what constitutes a block versus an element in BEM puzzles even experienced developers. Given a navigation list, is the list a block and the items its elements, or is each item its own block? There is no single correct answer. Context, team convention, and reusability requirements all factor in. The important thing is to make a deliberate decision and apply it consistently.

These ambiguities are not flaws in the methodologies, but a reminder that architecture requires judgment, not just knowledge.

Others' solutions do not replace architectural thinking

Modern JS frameworks and libraries offer powerful built-in mechanisms for managing styles. These tools solve real problems and are worth using. However, none of them prevent poorly written CSS. Scoping contains the damage; it does not eliminate it. A scoped component with tangled selectors, uncontrolled specificity, and mixed concerns is still a maintenance problem.

Regardless of the tools in use, the OOCSS mindset and the principle of dividing styles into deliberate layers of abstraction remain relevant. The framework handles the boundaries; the architecture handles the quality of what lives inside them.

DEV Community: Eduardo de la Cruz Palacios

CSS Architecture

Definition and purpose

Abstraction layers in UI

Methodologies to implement CSS Architecture

Object-Oriented CSS (OOCSS)​

Atomic / Functional CSS (ACSS)​

Block Element Modifier (BEM)​

Inverted Triangle CSS (ITCSS)​

Scalable and Modular Architecture for CSS (SMACSS)​

CSS Specificity and CSS Architecture

Recommendations for various kinds of Frontend projects

CSS libraries and frameworks

HTML-CSS-JS projects

Projects with a limited or small scope

Large or long-lived projects

Web components library​ or design systems

JS-framework projects: Angular, Lit, React, etc.

Final thoughts

Purpose: caring about CSS reduces side effects and improves maintainability

Flexibility

Real life decisions are harder than theory

Others' solutions do not replace architectural thinking

Object-Oriented CSS (OOCSS)

Atomic / Functional CSS (ACSS)

Block Element Modifier (BEM)

Inverted Triangle CSS (ITCSS)

Scalable and Modular Architecture for CSS (SMACSS)

Web components library or design systems