Architecture for a Sass Project

Remember when we used to do everything with nothing more than plain old CSS? All we had was a single CSS file, longer than a sleepless night. Yay! Thousands and thousands of lines — usually poorly written — of CSS where we were struggling to find the one value we had to change to fix some obscure and frustrating IE bug.

Well those days are behind us, folks. Dealing with CSS has become more interesting and more complicated. Probably the latter because of the former. And now that we have CSS preprocessors, responsive web design, progressive enhancement, graceful degradation, and all the other things cool kids talk about, CSS has become more powerful than ever.

“CSS has become more interesting and complicated.”
— Me.

So because we have a lot to deal with, it is important that we stay organized. And we can probably all agree that it isn’t always easy to be. So I thought in this post I could help you to understand how you should think (rather than how you should do; I’ll leave that up to you).

Drawing Your Architecture

One of the main benefits of using a CSS preprocessor is having the ability to split your code into several files without impacting performance. Thanks to Sass’s @import directive you can have as many files as you want in your developement environment and this will compile to a single file in production.

“Multiple files in dev, a single file in prod.”
— Bruce Lee

Being organized starts with correctly splitting your CSS across several files and folders. As one of my teachers used to say “everything has its right place, every place has its right thing”. Well here is how I like to do it!

Folders are cool, use them

Folders are essential. At home, you don’t drop every sheet of paper into the same box. You probably have folders. One for the house/flat, one for the bank, one for bills, and so on.

What if I told you, you don't have to put all your Sass files in the same folder?

When planning your CSS architecture, it is the exact same thing: you don’t just drop every Sass file into the same folder, you categorize them.

Here’s how we might organize our files:

sass/ 
| 
|– base/ 
|   |– _reset.scss       # Reset/normalize 
|   |– _typography.scss  # Typography rules 
|   ...                  # Etc… 
| 
|– components/ 
|   |– _buttons.scss     # Buttons 
|   |– _carousel.scss    # Carousel 
|   |– _cover.scss       # Cover 
|   |– _dropdown.scss    # Dropdown 
|   |– _navigation.scss  # Navigation 
|   ...                  # Etc… 
| 
|– helpers/ 
|   |– _variables.scss   # Sass Variables 
|   |– _functions.scss   # Sass Functions 
|   |– _mixins.scss      # Sass Mixins 
|   |– _helpers.scss     # Class & placeholders helpers 
|   ...                  # Etc… 
| 
|– layout/ 
|   |– _grid.scss        # Grid system 
|   |– _header.scss      # Header 
|   |– _footer.scss      # Footer 
|   |– _sidebar.scss     # Sidebar 
|   |– _forms.scss       # Forms 
|   ...                  # Etc… 
| 
|– pages/ 
|   |– _home.scss        # Home specific styles 
|   |– _contact.scss     # Contact specific styles 
|   ...                  # Etc… 
| 
|– themes/ 
|   |– _theme.scss       # Default theme 
|   |– _admin.scss       # Admin theme 
|   ...                  # Etc… 
| 
|– vendors/ 
|   |– _bootstrap.scss   # Bootstrap 
|   |– _jquery-ui.scss   # jQuery UI 
|   ...                  # Etc… 
| 
| 
`– main.scss             # primary Sass file

As you can see, there is only one Sass file at the root level: main.scss. All the other files are divided into appropriate folders and prefixed with an underscore (_) to tell Sass they are partial .scss files that shouldn’t be compiled to .css files. Indeed, it is the base file’s role to import and merge all of those.

“One file to rule them all,
One file to find them,
One file to bring them all,
And in the Sass way merge them.”
— J.R.R. Tolkien

Let’s now look at each of the folders in our architecture.

Base

The base/ folder holds what we might call the boilerplate stuff for your project. In there, you might find the reset (or Normalize.css, or whatever), probably some stuff dealing with typography, and, depending on the project, maybe some other files.

Helpers

The helpers/ folder (sometimes called utils/) gathers all Sass tools and helpers we’ll use across the project. Got a function? A mixin? Put it in there. This folder also contains a _variables.scss file (sometimes _config.scss) which holds all global variables for the project (for typography, color schemes, and so on).

Layout

The layout/ directory (sometimes called partials/) usually contains a number of files, each of them setting some styles for the main sections of the layout (header, footer, and so on). It also contains the _grid file which is the grid system used to build the layout.

Having the navigation file (_navigation.scss) in this folder could make sense although I use to put it in components/ (see next section). I think it would be better in the /layout folder but I’ll let you decide.

Components

For smaller components, there is the components/ folder (frequently called modules/). While layout/ is kind of macro (defining the global wireframe), components/ is more micro. It can contain all kinds of specific modules like a slider, a loader, a widget, or anything along those lines. There are usually a lot of files in components/ since your site is should be mostly composed of tiny modules.

Pages

If you have page-specific styles, I think it’s cool to put them in a pages/ folder and in a file named after the page. For example, it’s not uncommon to have very specific styles for the home page, so you’d have a _home.scss file in pages/ dealing with this.

Depending on your deployment process, those files could be called on their own to avoid merging them with the others in the resulting stylesheet. It is really up to you. Where I work, we decided to make them not-partials in order to include them only on pages requiring them. For example, our home page has a very specific layout, compiling to about 200 lines of CSS. To prevent those rules from being loaded on every page, we include this file only on the home page.

Themes

If you are working on a large site with multiple themes like I do, having a themes/ folder can make sense. You can stuff all your theme/design related styles in there. This is definitely project-specific so be sure to include it only if you feel the need.

Vendors

And last but not least, you will probably have a vendors/ folder containing all the CSS files from external libraries and frameworks – Bootstrap, jQueryUI, FancyCarouselSliderjQueryPowered, and so on. Putting those aside in the same folder is a good way to tell “Hey, this is not from me, not my code, not my responsibility”.

Example:

On a side note, where I work we also have a vendors-extensions/ folder where we store files overriding some tiny bits from vendors. For example, we have a _bootstrap.scss file in there that we can use to change some components in Bootstrap. This is to avoid editing the vendor files themselves, which is generally not a good idea.

That’s pretty much it. This architecture is likely to vary according to the project but I’m sure you get the concept. On nesting folders in folders, I wouldn’t always advise against it but I don’t prefer that. I’ve found that in most cases, a single level of architecture is more than enough to keep things clean and organized without adding too much complexity. But if you think your project deserves a deeper structure, feel free to do so.

Pro tip: if you feel like your architecture isn’t obvious to anyone opening up the scss folder, you might consider adding a README.md file at the root level (side by side with main.scss) explaining everything.

Files are cool too!

A question I get asked frequently is “how many files is too many files?” and to that I’d reply: There are never too many files. Splitting your work across several files aims at helping you organizing your code. If you feel like something deserves to be divided into many files, feel free to go nuts! As Chris Coyier says in his Sass Style Guide:

“Break into as many small files as makes sense.”
— Chris Coyier

Yet I’d advise against exploding a single component into several files unless you have very good reason to do so. Usually I tend to have one module per file — not more, not less — with a clean name like the name of the module it stands for. This way I can do a quick “go to” in Sublime text when I’m looking for something.

In Summary

All the suggestions in this article are based on my personal experience working as the sole front-end developer in the web-based branch of Crédit Agricole, a huge banking group in France. Your own circumstances and experiences might warrant a different approach.

If we could pick a Golden Rule for architecting a Sass project, it might be something as simple as: Pick something that makes sense. If you are working as a team on the front-end, make sure everyone feels comfortable with the chosen structure, else release documentation somewhere so that everybody can understand what’s going on.

Do you have any thoughts or suggestions on Sass architecture? We’d love to hear your comments.

“With great power comes great responsibility.”
— Aquaman