Adam Johnston

My CSS Architecture

I have been a big fan of modularised code since I read about it’s benefits and I began to learn how to code better Javascript. It’s always something I aim to do when writing any sort of code. It allows you to better maintain complex applications by splitting the code out into smaller, clearly focused pieces of code that can be reused throughout the app.

With Sass, we have the ability to do the same and split up large, complex CSS into manageable, maintainable and focused styles and we are able to separate our Sass functions and mixins that can be reused across our framework and used in websites and web apps, big or small.

The following architecture I am about to outline also takes advantages of the BEM naming convention, useful for structuring modules, OOCSS is great for keeping the overall size (in MB) of the framework small and is inspired by SMACSS which gave me the idea of how to compartmentalise styles into folders and separate, smaller files so they can be better maintained.


BEM stands for Block, Element and Modifier and was termed by YANDEX. It’s not specific to CSS but it’s useful for building the structure of a CSS module (I prefer to call objects modules). It can help explain how to apply said structure of the module to a developer in the HTML without too much documentation since they can simply follow the convention. A quick example of module structure with BEM:

.module {
.module__element {
.module__element--modifier {
.module__element__sub-element {
.module--modifier {
.module-block {
  &__element {
    &--modifier {

    &__sub-element {

  &--modifier {
<div class="”module-block”">
  <div class="”module__element”">
    <span class="”module__element__sub-element”"></span>

You can read more about BEM and you can read Harry Robert’s excellant post on the subject.


OOCSS (Object Oriented CSS) is an ideology from Nicole Sullivan and it’s proponent is to break down styles into small reusable objects or modules. They should be able to be used in different places in an application by having their own concerns and therefore are not reliant on other styles or markup. Nicole Sullivan also has a post which includes a very useful example.


Jonathan Snook’s SMACSS (Scalable Modular Architecture for CSS) is an ideology of how to organise and compartmentalise our styles to make managing them easier. My architecture does differ somewhat to Jonathan’s but without SMACCS I don’t believe I would use the architecture I am outlining here.

I thought I would take the time to write about how I modularise my CSS and explain my reasons for certain choices and what the benefits of this approach are. Everything I speak about can be viewed in my framework Freshly Squeezed on GitHub, which I am currently developing.

Folder structure

Here you can see the current folder structure that I follow. I use this approach as I believe it follows a good separation of concerns and is quite clear to a developer where specific styles will be.

┌ Utilities
  ┌ Variables
  ├ Functions
  ├ Mixins
  └ Third-Party
├ Generic
├ Modules
├ Singletons
├ Patterns
├ Themes
└ manifest.scss


Utilities contains a group of sub folders in which our framework can take advantage of. Firstly we have a Variables folder which contains all of our variables that we define. Following that we have our Functions folder which houses any custom Sass functions that may have been defined. We then have a mixins folder which has any custom Sass mixins and finally we have a Third Party folder which has any third party CSS or Sass partials, for example including Normalize or another CSS reset.


Modules are larger collections of styles that apply to several elements that can easily be grouped for a single purpose. These use the BEM naming convention.


Singletons are small pieces of styling that do a single specific job. These tend to be used more widely across an app and are meant to be grouped with other singletons. However if you find that you are using several on several elements, this may mean you should create a new module.


If you’re using a version of Sass that supports placeholders then this folder holds your placeholder partials. placeholders or what I prefer to call patterns contain blocks of styling that do not get output into your generated .css files but these single use blocks of styling can be @extended all across a framework.


The use of themes is to put groups of styling that may need to very specific. It wouldn’t necessarily fit into the rest of your framework. I like to think of them as custom styles that can take advantage of your framework’s variables, functions, mixins and patterns.

For larger projects that may require several changes, it is sometimes useful to use something of a mini architecture.


I hope this has given a good look into my choices and the reasons for them when deciding how to approach my own CSS architecture. I believe the above allows to write great CSS, file sizes low, keep bloat out and make maintenance easy.