How to structure your SASS code

By already worked on different companies, with different sizes and codebases, I've seen multiple codebase structures and helped created some of them from the ground up.

Working with a small team (two or three devs) is one thing, working +10 is another and it's very important to define a good structure from the beginning to help us scale the team and keeping the same level of productivity and good code.

From my experience and by following the pattern by Hugo Giraudel, the 7-1 Pattern, with a personal twist on almost all of the projects I've worked, I've found the right structure that until today, it's working fine with all good practices in place.

Of course today, you are probably using styled-components/Emotion on your React or Vue project but there are a lot of projects that only needs CSS or SASS. Let's proceed...

I think SASS, specially the .scss file extension, gives important features that don't exist yet in CSS, like nesting selectors, mixins, functions, variables (although css has now custom properties but they have differences), that increases our productivity.

Using the 7-1 pattern as a baseline, you have all your sass partials in 7 different folders and a single file at root level that imports all folders. This is used to later compile everything to a single CSS stylesheet.

base/
components/
layout/
pages/
themes/
abstracts/
vendors/
main.scss 

This has been our go-to architecture, since then we're following almost all recommendations.
There are some nuances in this pattern that over time made us refactor and create our own architecture to fit small to big projects.

main.scss with all the imports

We didn't like the idea of having a file importing every sass file on the project. To create pages that only import the CSS that it needs, this approach doesn't help.

Example: you have a simple sign-in page, should this page import all the CSS of your website? Off course not, right?

Our solution:

There are only two folders that we need to import on any page, the abstracts and the base folder.

For these folders, we've created a _global.scss file where we're importing all files inside.

/abstracts
    _functions.scss
    _variables.scss
    _mixins.scss
    _global.scss
/base
    _general.scss
    _fonts.scss
    _global.scss

On each _global we're importing:

// abstracts/_global.scss
@import 'variables';
@import 'functions';
@import 'mixins';

// base/_global.scss
@import '../abstracts/global';
@import 'general';
@import 'fonts';

Since we need all files of the abstracts folder on any scss file to be able to use the mixins, variables or functions, we can save some time and import the _global.scss of the abstracts folder in the _global.scss of the base folder. Without doing this, we had to import the abstracts _global.scss on every page .

To create a specific CSS file for each page and importing only what it needs, you can use webpack or parcel to generate multi entries and outputs. You can find more info on how to use webpack with SASS here.
With the solution above, we can create a sign-in.scss file in the page folder that will import all the defaults and specific components to be rendered on the page.

// sign-in.scss
// scss/ is an alias

@import 'scss/base/global';
@import 'scss/layout/header';
@import 'scss/layout/form';
@import 'scss/components/buttons';
@import 'scss/components/auth';
@import 'scss/components/loaders';

Using less folders

We've started following the folder structure that the 7-1 pattern suggests, but on all projects that we've worked with, none of them had to use all the folders.

I believe this suggestion below works for most cases, for small and big projects.
As it happens with small or big projects, you need to start defining your default Sass code like colors, font-sizes, resets, etc and then pages and components.

Here, there's no difference between a small and big project, only the number of files.

/abstracts
    _functions.scss
    _global.scss
    _mixins.scss
    _variables.scss
/base
    _fonts.scss
    _general.scss
    _global.scss
    _typography.scss
/components
    _header.scss
    _form.scss
    _buttons.scss
    ...
/vendor
    _bootstrap.scss
    _normalize.scss
/pages
    auth.scss
    homepage.scss
    ...

Abstracts

The /abstracts folder contains all the sass helpers you can create to help you out on your project. This is all about sass tools, variables, mixins, functions, placeholders, etc.

We're using the _global.scss to import all files so we don't bloat another file with these imports.

Base

The /base folder contains all the boilerplate of the project. It's where we set the default styles, import custom fonts, set the default style for the headings, paragraphs, hyperlinks.

Components

Following the thought process when using a Javascript framework like React, everything is a component. These are independent, reusable pieces of the UI and you can think of components like a navbar, a header or a button.

That's why instead of using a layout folder for elements like a Footer or an Header, we create pages that are composed by components.

Vendor

The /vendor folder contains all the third party files that the application needs. It can be a reset css file, bootstrap, anything you could think of.

If these files should be included in any page of the website, we import in /base/general.scss.

Pages

The /pages folder should contain the specific styles for each page with the filename being the name of the page. In our use case, we use webpack to create specific CSS files for each page and import all the default styles and the components that I need for each page. You can find more information how we do this here.

This approach allow us to import only the code that the page needs and reduce the size of the file.

An example could be something like this:

// billing.scss
@import 'scss/base/global';
@import 'scss/components/header';
@import 'scss/components/footer';
@import 'scss/components/form';

.billing {
  max-width: 640px;
  margin-top: pixelToRem(90px);

  &-section {
    margin-bottom: pixelToRem(60px);

    p {
      margin-top: pixelToRem(5px);
    }
  }
}

If you're not using something like webpack to bundle and convert your javascript and sass/less files and you have a main.scss where you import everything, this approach allows you having a _global.scss file per folder importing all the other files and import these globals to your main file.

// main.scss
@import 'scss/abstracts/global';
@import 'scss/base/global';
@import 'scss/components/global';
@import 'scss/pages/global';
@import 'scss/vendor/global';

I hope you find this article helpful.

The 7-1 pattern helped us with the foundation and we tweaked a bit to fit our needs. This approach, where everything is a component and pages are composed by independent, reusable pieces help us creating smaller CSS files shipped to the user and have a more modular Sass structure to scale when the project and team grows.