Clean New Sass Architecture – Modular Development

I came up with a solution that helps me craft projects a lot faster and neater. The code is very easy to navigate throw, and it’s all documented.

I’m making a Super Flexible Framework(SSF), that is built on Susy layout system and Sass, the CSS pre-processor.  I use tools like gulp to automate my tasks, as well as I, use bower for my 3rd end libraries to keep the project neat – not only that, it’s fast and easy to use. I use methodologies such as BEM, SMACSS and OOCSS, perhaps there is some ATOMIC design pattern to it. The purpose of the project, the framework, is to make the development a lot easier for us to start, and it will save us many hours of upfront work that we always do when starting a new project.

DISCLAMER: Everything that you read, is ONE way of doing things. These are just guidelines that helps me to do the projects – don’t follow them as a religion or be political correct about them. There is a saying in the internet that Sass should have 5folders. That’s just guidelines. Sometimes, when I have to, I have 8 folder, perhaps even 9! On other projects I might have just two folders! These are just all guidelines, ultimately you want to gain a skill that you will be able to assess what’s needed, and how to do it. Later on these articles will be for you to get some new ideas and help you master your way of thinking, not others!

The beginning

When I was learning about front-end architecture, It was very hard to keep a project that is neat and maintainable. The idea is fascinating, but the reality is brutal! It was a challenge with the namings and the structure of the project. It was very frustrating at first, but the more I read and the more I thought about ways to do it, the more ideas I got, and the more ideas I had given to me from other developers in the field.

This is my personal preference of the project structure, you will find that each agency/company, people, projects have a different architecture, most of the times. I like to think about my framework as bootstrap and Susy on steroids.

The framework is very new, and needs a lot of changes, editing’s and improvement, by the time I’m writing this, the version is (0.0.1/2).

I use Susy and I think is a great layout tool, because it’s flexible and you can have as many different layouts as you want. It has a slightly steeper learning curve than bootstrap, but it’s nothing hard if you put in the time and practice.


File Structure

When developing the project, I took an extra time to think about the file structure(it still can be improved – however, this is the beginning).

I wanted something that is dynamic, like bootstrap, but flexible like Susy.

Have a look at the file structure:

|-scss |—–0-lib |—–1-helpers |—–2-variables |—–3-base |—–4-layouts |—–5-objects |—–6-modules |—–app.scss

Ultimately you can find the project on Github( )  – It will probably change in future on where are the files, and what those files are, but I will share the general concept in this article.

Note, the folders are structured the way as they need to be compiled. I added a prefix , like 0-, 1-,2- etc… to order those folders, and when you’re developing the project in your editor or IDE, you will quickly recall where is what, that’s because you as a developer, know how the folder is compiling, so you will look at the right place straight away.



The 0-lib folder is made to keep our 3rd parties code, be it font-awesome, jQuery of Susy, perhaps a jQuery plugin or anything that’s outside the project developed by someone else.

I use bower to manage my 3rd parties libraries, however if you’re not comfortable with bower, you can always do it manually – nerveless you should probably just learn it, because it’s nothing hard and in web development technologies move fast, so it’s good if you learn on how to learn quickly by practicing to learn new things and develop new ways to do so!

When you go in the folder, you will find a _lib.scss file, when you go there you will see imports. That is because I use bower to keep my 3rd parties code, to keep things simple – you should also never edit 3rd parties code, and this is a good practice to do, in case you ever think to go and edit the original code.

The code looks like this:

@import “./bower_components/susy/sass/_susy”;

I’m telling to look in the same folder, the same directory with the dot, and look in the bower_components folder. Bower will have many components, it depends how many you install. You look for the component you want to include, in this case its Susy, you go there, and you look at the right file to include, which in this case is _susy. Note, you don’t have to put the .scss extension at the end, the compiler is smart to know what you’re doing.



The 1-helpers folder is a place where you write code that will help you the development process. Mixins, yes, remember those? Of course you do! We all love Sass Mixins, we can write the code a lot faster with Mixins, and it saves us a lot of times to define prefixes for browser combability.

Some example you want you might want to include in the Helpers folder is: typography mixins, mixins, flexbox mixins!, shapes, anything that will help you with the development.



2-Variables. There is a lot to say about variables, and I will cover some of the files separately in another article.

Variables is a very important part of our website. Why? Because we use variables to make our project maintainable, however when done wrong, this can backfire and we can have a total mess.

That’s why I have divided variables into different categories (and still experimenting) so it makes a sense when developing. I like to keep things modular in my projects, and neat.

In the variable folder you will find:

_breakpoints.scss, _colors.scss, _settings.scss, _susy.scss

as of this time.

Now, you might find them all in one file, and that’s fine, but on larger projects, those files alone can be a bit tedious to look at, and hard to navigate.

I will go quickly throw each of them.

Breakpoints file keep all different breakpoints. You know how bootstrap has xs, sm, md and lg? Well, those are very rigid, fixed values, that it’s hard to add new – you can, add new, if you know how.

Now, if your project is very big, the breakpoints , you might have a lot of them. Is this bad? Well, you can think of this as a way of helping to break your project into modules, what if there is a feature you want to display only above tablet size? How about hiding an item below tablet size? There are many variations where the min-max or min or max, queries might be not enough, perhaps… it can, but there are better ways to do things.

In the colour section, you can read my article   on how I structure the colours the way they are, in short, I keep all variables there, and give them a meaning. Projects have a lot of colours, some less some more, so it’s very important to keep the tidy.

The setting files is where I write all the site default styles, and make some math perhaps. You know when you want a new button? You need to define all the values and so on, well, in the setting files you can just add the Y,X coordinate, which means vertical and horizontal and add the high and width. You can also adjust the line height there.

Then in the button.scss file, you write those values in a mixin that will take care of the value and pair. This is a fast process, and a neat one.

Now, this also makes things neat to align out buttons and forms – how you might ask? We add the values from buttons to form, which then we do simple math to get the same button and form height. If we have a small form and button, the height will be always the same. That’s the power of Sass, and I have made this very easy and clean in the settings file.

Now, the Susy file is the global Susy settings, those files perhaps can be put in the settings file, but for now I’ll live them in a separate folder.



3-The base folder, it’s nothing exciting. You add your styles that are global across the website. This means you add your normalize/reset style, and your body styles, as well as styles to your HTML.

The values in the base folder and file, are already defines in the settings file. So you don’t even need to go to base, and just change the properties in settings.

Think about it like this:

Body {                 line-height: ($base-line-height/$base-font-size); }



4-Layouts folder consist of the main elements on the website. This is something like header and footer, these are the most obvious ones. The main navigation is also a part where it will be shown in the entire website, however as I like to keep my project modules, and not overwhelm one files with hundreds of lines, I break it even more and create a new file just for the navigation.

Apart form the main components, I keep there also my main styles such  layouts.scss file. In the file I have classes that will help me in the entire project.

You can call those like helpers,  You have a container, container wide, container fluid, container small, perhaps section small, section big and so on. You might even have a class float right, and have the values to float right.



5-Objects are not components or modules. Objects are simply what I call sub-modules. Every website has buttons, forms and so on. Well, those are objects. When you develop a module or component, you will use objects inside the components, like buttons. From objects you can make bigger components that will have consistent look.

In Objects file I keep my buttons, forms, checkboxes, pagination and so on. Those elements are what makes the page at the end.



6-Modules are usually made of objects, well, not all the time, but if you have a carousel, you will want a button in your carousel, which will come from the object folder.

In modules you have big components like sliders, cards, modals, these is what makes the website at the end, these are the main components the user will interact and see. A modal will pop up, or perhaps a slider will slide!


7-pages, Last but not least, pages. This is straight forward, but just in case you were thinking that you develop a website using just objects and modules, well… that will get very hard and messy. I have developed plenty of websites, that have specific styles to some pages, and umm, where do I put those?

Well, in pages. If you have few components or styles that are related to each other, in terms of the page, article-excerpt, article-single, you want to create an folder like : article-pages or perhaps articles-template, and inside put in those files.

App file

Now, this is pretty obvious, but you need to connect all those files somehow. You can do this by importing them, in order as we discussed above, here.


Do you have any questions or perhaps new suggestions? Comment below!

You can also contribute to the project here:

Happy Structuring!

Meet the author

Meet the author

Aurelian Spodarec

Front-end WordPress developer that blogs about web development. I like using the right tools for the job. In my spare time, I enjoy cooking healthy food and then eating it. Delicious!