12/09/2019 8 Minutes read Tech 

How to organize your CSS ?

As a front-end developer, arriving on a project, who has not found himself thinking, “Damn, where does this class comes from? Where is it used, am I going to break the UI modifying it? Maybe I should just use an extra class. Oh, but that will add more complexity”

Hello brainteaser, nice to meet you again.

If you consider yourself more a JavaScript developer than a CSS developer, those issues are even more of a nightmare.

Moreover, these have always been and still are a great deal of debate amongst developers (sometimes intense).

This post does not aim to give a universal response, but to present some existing methods on how to organize your CSS code and name your classes.*

1. BEM (Block Element Modifier)

Definition: simple naming convention that aims to make your front-end code easier to read and understand.

Block: standalone entity that is meaningful on its own (menu, header)
Element: part of a block that has no standalone meaning and is semantically tied to its block (menu item, header title)
Modifier: a flag on a block or element. Use them to change appearance or behavior (disabled, fixed)

.block {}
.block__element {}
.block--modifier {}
.block__element--modifier {}

Why should you use BEM convention? Pros & cons

it’s a convention, so it gives a common ground (declarative syntax) for developers working/arriving in the project

easy to use: no dependance or code of any sort (just apply the naming rules)

modular: independent blocks and CSS selectors

flexible: it will not pick a fight with any other architecture but complete it

lookin at the markup only, be able to quickly get an idea of which element depends on another

easy maintainability

avoid too much nesting but can for the same reason be too restrictive. In practice nothing really forbids from bending the rules a little and add some nesting levels (.blockelementelement but with a limit), be careful though not to end up with endless class names

depending on which level/context/component you apply your class, it can sometime be difficult to come up with relevant block names

Learn the best way to organize CSS stylesheets with BEM methodology

Note please that in the following points I am talking about architectures and not frameworks.

2. SMACSS (Scalable and Modular Architecture for CSS)

Definition: SMACSS is a style guide, it is a way to examine your design process and to attempt to document a consistent approach when using CSS.

SMACSS is about categorization, identifying repeating visual patterns so you can define better practices around each of these patterns.

The idea is to divide styles into 5 categories: base, layout, modules, states and theme. Each category is defined by its own guidelines, they are then supposed to be coded into flexible/reusable modules (independent from the context or content).

Base: default styling rules (reset, body…) mainly single element selectors
html, body, form { margin: 0; padding: 0; }
a { color: #039; }
Layout: divide the page into sections (header, footer, navigation, main content…) and style them using id selectors

#header, #article, #footer {
  width: 960px;
  margin: auto;
.l-flipped #article {
  float: right;
<div id="header"></div>

Modules: reusable, modular elements (sidebar, product lists), independent of its context. Avoid using IDs and element selectors, stick only to class names
State: how our modules/layouts will look when in a particular state (active, hovered, small/big screen…)
Theme: how our modules/layouts might look when in a particular state (usually needed for websites/pages that require theming : use of different charts in different contexts)
Naming rules: use prefix l- layout- for Layouts, is- like is-hidden for States, use .module with the name of the module itself for Modules

Why should you use SMACSS style guide? Pros & cons

create standalone, portable, reusable components (reusable patterns)

can help structure your CSS/SCSS files

developers “just” have to follow a precise sets of rules which is then the common way to write CSS code on this project (easier to maintain and also easier for a newcomer on the project)

in practice, risk having most of the CSS end up in the “modules” sections, especially for large project (fall into the trap of “module all the things”)

depending of the website, choosing between layouts/modules can be a bit of a struggle (things can still be up for interpretation)

How to organize your CSS with SMACSS – related articles

3. Atomic Web Design architecture

Definition: Atomic design is a methodology for creating design systems. The particularity of this design system is that it was inspired from chemistry, interfaces are seen as matter. Matter is composed of combined elements (made of organisms that are made of molecules that are made of atoms).

Atoms: HTML tags (form label, input, button) or elements that cannot be broken down any further
Molecules: groups of atoms that fulfill a common purpose (multiple inputs combined as a form)
Organisms: groups of molecules joined together to form a relatively complex, distinct section of an interface (can be composed of other organisms too)
Templates (end of chemistry): groups of organisms stitched together to form pages, it provides context to relatively abstract molecules and organisms
Pages: specific instances of templates with real content, it’s what the user will see and interact with

Atomic Web Design Architecture Pros & Cons

create standalone, portable, reusable components (reusable patterns)

can help structure your CSS/SCSS files

”do one thing and do it well” mentality

components can be developed separately from the application, tested, then easily imported into a more realistic context

testability: easy to implement with story book

compared to SMACSS (they are both modular approaches), the different layers give less room to interpretation and dividing your components is less tricky, but still in practice there can be sometimes hesitations when choosing between organisms and molecules

be careful about patterns, this method encourages the re-use of a pattern that isn’t fit for purpose instead of building a new component from scratch (for example if you start having many “if” conditions regarding this component, it might be wiser to split it into different components)

A clarification about SCMASS and Atomic design:

Modular architectures can be problematic depending on how you’re building your application with JavaScript. It can be really handy if you’re developing an application with html files and JavaScript injected here and there. If your application is component-based, the way you want to organize your JavaScript components may be completely different from this methodology. How to make them work altogether ?

Additional resources for a clean CSS with Atomic Web Design architecture:

4. Atomic/Functional CSS architecture

Definition: Atomic CSS is the approach to CSS architecture that favors small, single-purpose classes with names based on visual function. It’s a pretty straightforward and simple methodology:

CSS is written regardless of context or content
a separate class is created for each reusable property
utility classes : a class does small little one-off things (styling is done via markups by adding those utility classes)
immutable classes : they can not be modified

.bg-blue { background-color: #357edd; }
.f1 { font-size: 3rem; }
.relative { position: relative; }
.mt10 { margin-top: 10px; }
.pb10 { padding-bottom: 10px; }

: Atomic CSS is different from inline-styling in terms of scalability and verbosity, you are still working with classes.

Atomic/Functional CSS Pros & Cons

minimize amount of CSS code (no heavy files in production)

share styles easily between projects

at some point, style sheets stop growing and become immutable (cache-friendly)

classes are predictable and reliable

naming classes is simple

can be applied to any development methodology (component-based, ‘pages’ model or any other)

markup can be polluted with many classes instead of the stylesheet, it is actually exactly what this method intends but it can be a problem for some developers

manual labour when it comes to updating the style of several instances which are using a common utility classes : changing styles is easier in a CSS file than in multiple markups (since you can not write .border4px {border-width:2px;} you have to create a class .border2px and replace .border4px in all the markups that need to be updated).

This methodology can be nice for large scale project with a mixed-ability team.

Related frameworks: Atomizer, Tachyons

Read these articles to better understand Atomic/Functional CSS

5. ITCSS (Inverted Triangle CSS)

Definition: ITCSS is a fully managed architecture that aims to provide a level of formality and structure to the way we write our CSS.

ITCSS works by ordering your entire CSS project by three key metrics :

Generic to explicit: moving through the project, start with the most generic styles then progress to more explicit and specific rules
Low specificity to high specificity: moving through the project, specificity is steadily increasing (avoid conflicts)
Far-reaching to localised: moving through the project, write rules that affect progressively less and less the DOM (reset everything at the beginning, style every type of element, then style every element specifically with its own class)

ITCSS is a methodology that involves visualising your entire CSS project as a layered, upside-down triangle.


Settings: holds any global settings for your project (fonts, color palettes)
Tools: globally used mixins and functions
It’s important not to output any CSS in the first 2 layers
Generic: houses very high-level, far reaching styles (reset and/or normalize styles, box-sizing definition, etc). Updates a lot the DOM
Elements: styling for bare HTML elements using selectors (h1, a)
Objects: first layer with class-based selectors, styling non-cosmetic design patterns (layout, wrapper)
Components: style recognisable pieces of UI, still using classes (majority of the work happens here after initial project set-up)
Trumps: override anything at all that has gone before it (utility and helper classes, hacks and overrides)
Files structure: each layer contains a series of partials as small and granular as possible (..scss, for example: _settings.colors.scss, _elements.headings.scss, _components.tabs.scss)

ITCSS methodology Pros & Cons

instead of splitting project up into thematic groups, order CSS in a way that best utilises, tames or takes advantage of the cascade, inheritance or specificity (we write CSS in a logical and progressive order)

greater extensibility and less redundancy (so small file sizes in production)

know where each type of rule will live and where to put any new styles

share global and far-reaching styles easily between projects

no time wasted undoing or overriding overly CSS that was written earlier on

”instead of splitting project up into thematic groups…” (check first point) : also means that style is uncorrelated from your UI components (no standalone, portable, reusable components)

partially proprietary (prevents its wider adoption, maybe intended)

This methodology was initially created to answer to need of large scale projects but can be applied to any projects.

Check out these articles on how to reorganize CSS with ITCSS

How to organize your CSS: Conclusions

This is not all that exists out there in the wild, there are many more CSS architectures such as OOCSS, SUITCSS, MCSS with their own advantages/disadvantages.

I also want to point that lately component-based development has become more and more popular with frameworks such as React or Angular, and like I already said, many CSS architectures have trouble blending in with this new JavaScript architecture.

In response to this new issue, a library styled-components was developed (for react developers). Using tagged template literals (a recent addition to JavaScript) and the power of CSS, styled-components allows you to write actual CSS code to style your components (style is defined in the JavaScript file). It removes the mapping between components and styles.

*Finding the right CSS architecture for your project is not an easy thing to do, and finding the right one, which is also compatible with your JavaScript architecture, is even more complicated.

I believe, I am not mistaken, when I say that each developer studies the different “officials” existing architectures and usually makes its own custom architecture by picking some ideas here and there.

There is no “wrong answer”, there are of course good practices but the right architecture will depend on each project and its needs.

It will also depend on the developer; there is a subjective aspect to development:

A developer will prefer one method compared to another just because it is his preferred way to write code.

Some people will see advantages and drawbacks in those methods that I have not seen myself and/or even simply disagree with, even if I tried to be as objective as possible.

The best advice I can give is, whatever your choice is, communicate about it, so that every developer apply to it and things does not get out of hands.

Anyway, I hope that this article gave you a glance at the realm of the many possibilities to construct an awesome CSS architecture, for your awesome projects!

Bye bye <3*