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.

  • _reset.scss or _normalize.scss
  • _typography.scss

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).

  • _variables.scss
  • _mixins.scss
  • _functions.scss
  • _placeholders.scss (frequently named _helpers.scss)

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.

  • _grid.scss
  • _header.scss
  • _footer.scss
  • _sidebar.scss
  • _forms.scss

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.

  • _media.scss
  • _carousel.scss
  • _thumbnails.scss

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.

  • _home.scss
  • _contact.scss

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.

  • _theme.scss
  • _admin.scss

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:

  • bootstrap.scss
  • jquery-ui.scss
  • select2.scss

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

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • http://www.indrashishghosh.com Indrashish Ghosh

    Hey Hugo, it’s always good to observe how other people create their directory structure for Sass. Incidentally, I follow an almost exact folder structure for my projects. Just 3 differences:

    1) I usually name the ‘layout’ folder as ‘modules’ which in most cases are limited to just the header, footer and sidebar. Mostly the major repeating sections on a site. I prefer keeping the styles for forms in the components folder, as I feel it’s not exactly a major repeating element on a site.

    2) Also, I personally like to keep the ‘grid’ partial within the ‘base’ folder. The way I see it, the two most essential files within the base directory are the ‘typography’ and ‘grid’. Apart from the `reset` of course. Mostly these are the bare minimum files required to start giving shape to the site.

    3) Lastly, I sometimes like having an additional folder called ‘config’, which contains just a single partial, named ‘_config.scss’. This file contains just variables, which essentially dictate the outcome of the site. l normally include stuff like colours, fonts, paths etc. If done properly, its amazing how fast you can make drastic changes to the site by just changing a few variables in the config file!

    Thanks for sharing! Great reading your write-ups as usual.

  • Dave Allen

    Very thoughtful and helpful. One thought: do variables need to imported first in the main style sheet?

    A–Z sorting of the import list produces compilation errors:

    @import “base/h5bp”;
    @import “base/modules”;
    @import “base/normalize”;
    @import “base/typography”;
    @import “helpers/helper”;
    @import “helpers/variables”;
    @import “layout/grid”;
    @import “layout/layout”;
    @import “layout/navigation”;

    But this, with _variables.scss first, compiles OK:

    @import “helpers/variables”;
    @import “base/h5bp”;
    @import “base/modules”;
    @import “base/normalize”;
    @import “base/typography”;
    @import “helpers/helper”;
    @import “layout/grid”;
    @import “layout/layout”;
    @import “layout/navigation”;

    Which is a shame because the A–Z is more readable. Or am I in error myself?

    • http://hugogiraudel.com/ Hugo Giraudel

      Variables often influence most of the other imports, so they always should come first. That’s actually their main purpose: coming first and dictating how components behave.

      As far as I’m concerned I don’t like A-Z sorting for imports. I feel like it doesn’t make much sense in the end.

  • Aurelio De Rosa

    Hi Hugo Giraudel, I really liked your article. I’ve a question for you about your discussion on specific pages’ style. You say “Depending on your deployment process…we include this file only on the home page.” Would you please expand on this process? I guess you make these files not partial so they will be compiled as standalone css files and then you include the main CSS and the specific page CSS in the markup of your pages. So, you’ll end with something like:

    **index.html**

    **projects.html**

    Am I right?

    • http://hugogiraudel.com/ Hugo Giraudel

      Hey Aurelio!

      Well, you got the idea however you miss one piece of the puzzle to understand how we’re doing it at work: we have Assetic merging our stylesheets all together.

      So basically, when we make our home page template include both the `main.scss` and the `home.scss` files, all we end up with is a unique CSS file with some weird name like `49e2310.css`.

      • Aurelio De Rosa

        @HugoGiraudel:disqus thank you so much for the answer. This solution to avoid the additional HTTP request is very cleaver. On this regard, I’ve an additional question (then I promise to stop boring you): because the css for index.html is (like) 49e2310.css, and the one for projects.html is (like) 53ab981.css, isn’t this solution avoiding the chance to cache common.css? I’m sure I’m missing another piece/you have a workaround for this issue, that’s why I’m asking.

        • http://hugogiraudel.com/ Hugo Giraudel

          To be perfectly honest, I’m not sure how we handle caching in such a case.

          • Aurelio De Rosa

            Don’t worry. Thanks anyway for the answers. I was trying to figure it out how to take advantage of your approach and to take advantage of the users’ cache as much as possible.

          • sic1

            To be perfectly honest, this right here is one of the most heavily overlooked and not talked about things in large multi-page sites – how to minimize requests, but not have to download the same content twice.

            I mean, you can’t, unless you allow for multiple css files per page. I’d be very curious for you to dig a bit deeper on this to see if your team does something extra special – or just literally have each page with unique styles reload all of the common/global styles with it.

            IMO, it seems worth it to just make it 2 on pages with unique styles. The one global that is loaded on every page, and can be cached, and the unique styles for the page.

            Thoughts?

            Great article, thanks.

  • Savio VH

    Funny enough I use a very similar approach for smaller projects which I commeted here http://www.vanseodesign.com/css/variable-organization-in-sass/ or if you want to jump straight into the example: https://gist.github.com/saviomuc/8cb7a45db2803d9cdaec

  • Savio VH

    Vertical Rythm and stuff =)

  • http://hugogiraudel.com/ Hugo Giraudel

    Default font-size, default line-height, heading font-size, vertical rythm related rules and stuff. :)

  • http://jonassebastianohlsson.com/ Jonas Ohlsson

    Great post – thanks for sharing!

  • Ant

    Thanks Hugo, nice to see how you organise there sass files. I do wonder how you would orangise responsive styles. There would need to be multiple main files to load the correct of stylesheets. Instead of loading all styles for all screen sizes into one file containing media queries.

    For example, main-small.scss, main-medium.scss and main-large.scss. In the root that load there versions of each layouts, component styles. Which are loaded in the markup with media queries.

    My first thought is nested folders. What you think?

    Thanks,
    Ant.

    • http://hugogiraudel.com/ Hugo Giraudel

      I’ll be perfectly honest with you: I load all styles for all screen sizes everytime. There is what I consider a valid reason behind this: I like to think my application as a collection of components. See this article on topic: http://www.sitepoint.com/sass-component-10-minutes/.

      Thus, I handle media queries from within components, not in external files. A component is a standalone piece of code that works by itself. Its behaviour for each breakpoint is described in its core, not anywhere else. Think of it at some kind of Class (OOP).

      Hope it answers the question. )

  • http://hugogiraudel.com/ Hugo Giraudel

    I have been wondering about this and have settle down to this: if the placeholder is very specific to the current case, I leave it in the current file. If it’s a global helper, I move it to a helpers.scss file.

  • http://ariona.net Rian Ariona

    This post is enlightening :), but I was curious with this “to prevent those rules from being loaded on every page, we include this file only on the home page”. So how did you do that? should I create different files for different pages or can we achieve this dynamically?

    • http://hugogiraudel.com/ Hugo Giraudel

      We are running our project on Symfony 2, which comes with Assetic, an asset manager. Assetic makes it very easy to do such a thing.

      • Catherine Nguyen

        I’m working with Symfony 2′s Assetic as well and was wondering how you deal with IE conditionals? Curiour to know if Assetic help or do we need to manually add the IE conditionals in the head?

        • http://hugogiraudel.com/ Hugo Giraudel

          We are running them manually.

  • friendshatehim

    Hi Hugo,

    I can’t thank you enough for this article. It is by far the best I have found. You are so right in that SASS is getting pretty complicated and with everybody using their own terminology in how they structure their projects, it really just makes it hard to get your head around it all. You structure, I think, is the best and makes the most sense.

    Cheers