Sass: Directory Structures That Help You Maintain Your Code

Posted: 02 Feb 2016 05:30 AM PST

As projects grows larger, the need to modularize directory and file structure increases. This is particularly true if you want to create code that can be used in other projects, in components and patterns across one or more projects, or in templates you share with others.

Hexanol Structure — Structure of a 2-Hexanol molecule

Last week I talked about the @import directive and how you could use it to create a more maintainable file and folder structure. I showed you one simple structure I learned and I promised to show you some other structures I've come across.

I have a few to share and I'll talk about some of the commonalities between them to help you choose one or develop a structure that works for you.

Simple Structure

I hope you don't mind if I start with the simple directory structure I mentioned last week. Here it is as a reminder.

modules/
- _color.scss
- _typography.scss
partials/
- _base.scss
- _navigation.scss
vendor/
- _ico-moon.scss
main.scss

The vendor folder holds 3rd party code. The partials folder is for code you want to include and compile. The modules folder is for code you want to include, but don't want to compile.

Note that this structure allows you to distinguish between your code and 3rd party code and it allows you to distinguish between code you want to compile and code you don't want to compile. That's what this organization does.

The names of the files and folders can be changed to whatever you want. The key is this structure allows you to keep your code separate from 3rd party code and it allows you to separate your code between that which should be compiled into CSS and that which shouldn't be compiled.

The 7–1 Pattern

Another structure I came across is the 7–1 pattern from Hugo Giraudel. Here's how you might set up a directory along with some examples of files that would be in each folder.

base/
- _reset.scss
- _typography.scss
- _color.scss
components/
- _buttons.scss
- _navigation.scss
- _gallery.scss
layout/
- _header.scss
- _grid.scss
- _sidebar.scss
pages/
- _home.scss
- _about.scss
- _contact.scss
themes/
- _theme.scss
- _admin.scss
helpers/ (or utils/)
- _variables.scss
- _functions.scss
- _mixins.scss
vendors/
- _bootstrap.scss
- _jquery-ui.scss
main.scss

The base folder holds boilerplate content. It holds the styles every page of your site should receive.

The components folder holds all your micro layout files. Your styles for buttons and navigation and similar page components.

Your macro layout files go in the layouts folder. Styles for major sections of the layout like a header or footer and styles for a grid system would belong here.

If you have styles specific to individual pages on your site, you can place them in the pages folder. For example it's not uncommon for the home page of your site to require page specific styles that no other page receives.

The themes folder holds files that create project specific themes. For example one section of your site might use a color scheme with primary colors, while another section builds a color scheme based on neutrals and earth tones.

The helpers or utils folder holds Sass tools, helper files, variables, and config files. These files won't be compiled.

Finally the vendors folder holds 3rd party code and the main.scss file uses @import statements to include the other files.

Here are some additional resources for this pattern

SMACSS/BEM Architecture

A number of people have written about setting up directory structures based on either a SMACSS or BEM architecture. I want to present four different, albeit similar, structures that build on each other and also incorporate some ideas from the 7–1 pattern.

Ryan Burgess leveraged some ideas from SMACSS when setting up this simple structure for Evernote. They used four folders, Base, Layout, Modules, and Themes

Base holds vendor code, helpers, mixins, variables, and general selector styles (body, h1, p, a, etc.).
Layout holds macro layout styles.
Modules holds micro layouts styles.
Themes holds any type of page specific styles.

Notice the distinction between micro and macro layout as well as the distinction for page specific styles and a general catchall for files with non-compiled code and general styles.

Tim Hartmann and Bram Smulders shared similar four folder structures.

Base holds vendor code, helpers, mixins, variables, and general selector styles (body, h1, p, a, etc.).
Layout holds macro layout styles.
Modules holds micro layout styles.
State holds state specific code, how buttons look on hover and similar.

Again there's the distinction between macro and micro layout styles as well as a folder that holds non-compiled code and general styles. The difference here is a State folder for state styles instead of a Themes folder for page specific styles.

Matt Staffer shared the organization his company used to help them keep a SMACSS-inspired structure.

_base.scss is for vendor code and styles on base elements (html, body, ul, p, etc.).
_layout.scss is for macro layout styles.
_modules.scss is for micro layout styles.
_other.scss is for whatever doesn't fit in first three.
_shame.scss is for code you feel ashamed of and plan to improve.

It's similar to the previous two structures, though note that these are files and not folders. The _other.scss file is the catchall and there's a _shame.scss file to nag you into improving the code it contains.

One last SMACSS based organization comes from Johannes Dreller. It adds another directory to the ones we've seen so far. Here's Johannes' structure along with some files each might hold.

vendor/
- _bootstrap.scss
- _jquery-ui.scss
base/
- _functions.scss
- _mixins.scss
- _variables.scss
- _base.scss
layout/
- _grid.scss
- _header.scss
- _sidebar.scss
module/
- _navigations.scss
- _buttons.scss
- _forms.scss
state/
- _state.scss
hacks/
- _shame.scss
main.scss

The addition is the vendor folder, which is used to hold 3rd party content. The layout and module folders still distinguish macro and micro layout styles. State changes go in the state folder. Non-compiled code and general styles go in the base folder. The hacks folder takes the shame file and there's a main.scss to @import all the necessary files.

Others

Matthieu Larcher & Fabien Zibi present DoCSSa's four folder organization.

base/
- __base.scss
- _config.scss
- project/
- utils/
components/
- _components.scss
- button/
- tabs/
specifics/
- _specifics.scss
- modal.scss
- navigation.scss
vendor/
- _vendor.scss

This structure is similar to the others I've mentioned. The base folder holds boilerplate styles in the project folder and Sass tools in the utils folder. The files directly in the base folder are for code needed in both subfolders.

Components is for micro layout and specifics is a catchall for most everything else. In both cases the files directly in the folder are for those used in the subfolders. Finally there's a vendor folder for 3rd party code.

The last structure I'll mention comes from Matthew Anderson and it adds some new ideas for organizing the directory.

framework/
modules/
vendor/
sections/
_bootstrap.scss
_section.scss

First the familiar. The vendor folder holds 3rd part code, modules holds partials that contain reusable UI patterns and components. The framework folder holds all project wide and ideally project agnostic code.

The sections folder is similar to the shame or hacks folder. It's not necessarily code you're ashamed of, but it's code you've yet to optimize or refactor or generally improve.

The two files are new. _bootstrap.scss isn't from Twitter's Bootstrap. It's a file that bootstraps the necessary files through @import statements.

_section.scss represents any file will become a compiled CSS stylesheet. These files will import _bootstrap.scss as well as any other project files necessary.

Closing Thoughts

I hope seeing examples of how others organize their Sass files and folders helps you understand some of the ways people modularize their code to keep it organized and maintainable.

What I hope you to take away from the structures I've mentioned is the idea that there's no single way to organize your stylesheets and directories, though there are common themes in the organization others have come up with.

Micro and macro layout styles
Boilerplate (global site) styles
Tools and utility files
Page and site theme specific styles
3rd party code
Shame files

These are some of the common things that others think worth keeping separate. You might decide you don't need to keep macro and micro layout styles separate and prefer to keep them together. You might not use 3rd part code on a project. See these commonalities as suggestions and not anything you absolutely have to use.

You can organize your files and folders however you think best. Just keep in mind that you should organize them in some meaningful way that helps you find and isolate your styles and code in a way that makes sense to you.

Next week I want to talk about another Sass directive, @extend. It allows a selector to inherit styles from other selectors so you can write DRYer code.

Download a free sample from my book Design Fundamentals.

Join me as I share my creative process and journey as a writer.