Architecture for a Sass Project

Share this article

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

This article is also available in Korean on Web Actually.

Frequently Asked Questions (FAQs) about SASS Project Architecture

What is the importance of SASS in web development?

SASS, which stands for Syntactically Awesome Stylesheets, is a CSS preprocessor that helps to make the process of designing web pages more efficient. It introduces features like variables, nesting, mixins, inheritance, and more, which are not available in traditional CSS. These features make it easier to write and maintain CSS code, leading to cleaner and more organized stylesheets. SASS also helps in creating reusable styles and codes, reducing the amount of CSS you have to write and making your stylesheets easier to maintain.

How does SASS architecture improve the efficiency of a project?

SASS architecture plays a crucial role in improving the efficiency of a project. It helps in organizing your stylesheets, making them easier to navigate and maintain. A well-structured SASS project allows you to know exactly where to find specific styles, which can save a lot of time when making changes or debugging. It also makes it easier to collaborate with other developers, as they can quickly understand the structure of your stylesheets.

What are the key components of a SASS project architecture?

A typical SASS project architecture consists of several key components. These include the base, layout, modules, state, and themes. The base contains the foundational styles for the project. The layout defines the structure of the web pages. Modules are reusable components that can be used across different parts of the project. The state describes how modules or layouts will look in different states. Themes are used to define different appearances for the same layout or module.

How can I effectively use variables in SASS?

Variables in SASS are a powerful feature that allows you to store values that you want to reuse throughout your stylesheet. You can store things like colors, font stacks, or any CSS value you think you’ll want to reuse. To use a variable, you simply declare it with a dollar sign ($) and then use it by calling its name. This can greatly improve the maintainability of your stylesheets, as you only need to update a value in one place if it changes.

What are mixins in SASS and how can they be used?

Mixins in SASS are a way of reusing a group of CSS declarations multiple times. They are similar to functions in programming languages. You can pass in values to make your mixin more flexible. A good use of a mixin is for vendor prefixes. For example, you can write a mixin for the transform property, which has different syntaxes in different browsers. This can greatly reduce the amount of code you have to write and make your stylesheets more maintainable.

How can I use nesting in SASS?

Nesting in SASS allows you to nest your CSS selectors in a way that follows the same visual hierarchy of your HTML. Be aware, though, that excessive nesting can lead to more complex and less readable code. As a rule of thumb, avoid nesting more than three levels deep and always remember that the goal is to make the code more readable and maintainable.

What is the role of inheritance in SASS?

Inheritance is a feature in SASS that allows you to share a set of CSS properties from one selector to another. It helps you to eliminate redundant code, making your stylesheets more maintainable and your output more streamlined. You can use the @extend directive to inherit the properties of one selector into another.

How can I create a responsive design using SASS?

SASS can greatly simplify the process of creating a responsive design. You can use variables to store breakpoints and then use these variables in media queries. You can also use mixins to generate repetitive responsive styles. This can make your stylesheets more organized and easier to maintain.

How can I debug a SASS file?

Debugging a SASS file can be done using source maps. A source map is a file that maps the compiled CSS to the original SASS file, allowing you to see where a style is defined in the SASS file when inspecting an element in the browser. This can be extremely helpful when debugging a large project.

How can I optimize my SASS for better performance?

There are several ways to optimize your SASS for better performance. One way is to reduce the amount of nesting, as excessive nesting can lead to more complex and less efficient CSS. Another way is to use the @extend directive wisely, as misuse can lead to unnecessary code duplication. You should also avoid using expensive CSS properties in mixins, as they can slow down the rendering of your page.

Kitty GiraudelKitty Giraudel
View Author

Non-binary trans accessibility & diversity advocate, frontend developer, author. Real life cat. She/they.

preprocessorsasssass architecture
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week