CSS Architecture

I’m attempting to compile a comprehensive list of how developers and front-end engineers structure their CSS using the SMACSS (Scalable and Modular Architecture for CSS) approach.

What is SMACSS?

SMACSS stands for Scalable and Modular Architecture for CSS, and is more a style guide than a CSS framework. On a high level SMACSS aims at changing the way we are turning designs into code. Instead of working in a page mentality where you try to turn a single page design into code, SMACSS aims to identify repeating visual patterns. Those patterns are then supposed to be coded into flexible/re-usable modules, wich should be independent as possible from the individual page context. This is not a revolutionary point-of-view for a programmer, but in the web design world this is indeed a newer way of thinking.”

“The basic concept of SMACSS is to divide styles into 5 categories: base, layout, modules, states and theme. Each category comes with a set of usage rules and naming conventions. The main reason of this categorization is that rulesets should only ever inherit and add to previous ones, never undo.” – Bram Smulders

According to Ben Frain, (Enduring CSS: writing style sheets for rapidly changing, long-lived projects) “it’s a common pattern to split up files in a project by technology type”.

- html/
- js/
- sass/
- css/

He continues to say, “I therefore favour a situation whereby rather than organise by technology type, files are organised and grouped by visual component. So, instead of this:”

- shopping-cart-template.html
- callouts-template.html
- products-template.html

- shopping-cart-template.js
- callouts-template.js
- products-template.js

- shopping-cart-template.css
- callouts-template.css
- products-template.css

“We aim for something like this:”

- shopping-cart.html
- shopping-cart.css
- shopping-cart.js

- callouts.html
- callouts.js
- callouts.css

- products.html
- products.js
- products.css

According to Bram Smulders, (How I improved my workflow with SMACSS & Sass) “in Sass you can easily chop your stylesheet into partials by using the @import rule. This allows us to easily organize and maintain our files similar like this:”

- theme.scss

	- theme/_base.scss
		- theme/base/_reset.scss
		- theme/base/_headings.scss

	- theme/_layout.scss
		- theme/layout/_masthead.scss
		- theme/layout/_main.scss
		- theme/layout/_footer.scss

	- theme/_modules.scss
		- theme/modules/_search.scss
		- theme/modules/_gallery.scss

	- theme/_state.scss
		- theme/state/_mediaqueries.scss

Jonathan Path and Laurent Sutterlity, created Sass + SMACSS which combines Sass with SMACCS.

And here’s an example of the folder structure:

On a very similar approach is Mina Markham’s Sassy starter – HTML / SCSS (SMACSS) and this is an example of the project’s file structure.

+ scss/
 | + base/         # reset, typography, site-wide
 |  |-- _index.scss    # imports for all base styles
 |  |-- _base.scss    # base styles
 |  |-- _normalize.scss  # normalize v3.0.1
 | + layout/        # major components, e.g., header, footer etc.
 |  |-- _index.scss    # imports for all layout styles
 | + modules/       # minor components, e.g., buttons, widgets etc.
 |  |-- _index.scss    # imports for all modules
 | + states/        # js-based classes, alternative states e.g., success or error state
 |  |-- _index.scss    # imports for all state styles
 |  |-- _states.scss   # state rules
 |  |-- _print.scss    # print styles
 |  |-- _touch.scss    # touch styles
 | + themes/        # (optional) separate theme files
 |  |-- beccapurple.scss # rename to appropriate theme name
 | + utilities/      # non-CSS outputs (i.e. mixins, variables) & non-modules
 |  |-- _index.scss    # imports for all mixins + global project variables
 |  |-- _fonts.scss    # @font-face mixins
 |  |-- _functions.scss  # ems to rems conversion, etc.
 |  |-- _global.scss   # global variables
 |  |-- _helpers.scss   # placeholder helper classes
 |  |-- _mixins.scss   # media queries, CSS3, etc.
 |  |-- _lib.scss     # imports for third party styles
 |  |-- + lib/      # third party styles
 |    | _pesticide.scss # CSS pesticide
 |    | ...
 |  + ie.scss       # IE specific Sass file
 |  + styles.scss     # primary Sass file
 |  + _shame.scss     # because hacks happen
 + .htaccess        # Apache server configs
 + config.rb        # Compass configuration file
 + crossdomain.xml     # cross-domain requests
 + docs/          # SassDoc generated documentation
 + deploy.rb        # Capistrano configuration file
 + Gruntfile.js      # Grunt configuration & tasks
 + package.json      # Grunt metadata & dependencies

According to Hugo Giraudel, (Architecture for a Sass Project), he likes to structure his Sass files as:

|– 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

According to Cathy Dutton, (8 Tips to Help You Get the Best out of Sass) “getting your site structure correct from the beginning is vital for any new Sass project. Using partials allows you to break the CSS up into smaller more manageable blocks of code that are easier to maintain and develop.”

“Partial files are created using an underscore and are not output as separate CSS files. Each partial should be imported using a master Sass file (global.scss) in the root of the Sass folder.”

|-- _variables.scss
|-- _mixins.scss
|-- _placeholders.scss

According to John W. Long, (How to structure a Sass project) “one of the most useful features of Sass is being able to separate your stylesheets into separate files. You can then use the @import directive to include the source of your individual files into one master stylesheet.”

“But how should you structure your Sass projects? Is there a standard way of separating out your CSS files?”

“I like to layout my Sass projects like this:”

|-- modules/              # Common modules
|   |-- _all.scss         # Include to get all modules
|   |-- _utility.scss     # Module name
|   |-- _colors.scss      # Etc...
|   ...
|-- partials/             # Partials
|   |-- _base.sass        # imports for all mixins + global project variables
|   |-- _buttons.scss     # buttons
|   |-- _figures.scss     # figures
|   |-- _grids.scss       # grids
|   |-- _typography.scss  # typography
|   |-- _reset.scss       # reset
|   ...
|-- vendor/               # CSS or Sass from other projects
|   |-- _colorpicker.scss
|   |-- _jquery.ui.core.scss
|   ...
`-- main.scss            # primary Sass file

“This allows me to keep my primary Sass file extremely clean:”

// Modules and Variables
@import "partials/base";

// Partials
@import "partials/reset";
@import "partials/typography";
@import "partials/buttons";
@import "partials/figures";
@import "partials/grids";
// ...

// Third-party
@import "vendor/colorpicker";
@import "vendor/jquery.ui.core";

How do you structure your CSS/Sass files?

Based on the findings, it looks like incorporating Sass/Scss files into your folder set up is the best way to start your project. Of course, assuming that you’re using Sass (and if you haven’t starting using Sass, why not?!)

There are plenty of resources to get your projects set up the right way but of course, everyone has different ways of approaching a file structure. So no matter how small or large your site will be, I hope these examples can help you look at CSS architecture differently for your next project.


Further Reading

Using Bourbon, Neat, Bitters & Refills

So why am I contemplating using Thoughtbot products when Bootstrap is so popular and much widely used in the web community?

  • Bourbon – “A simple and lightweight mixin library for Sass.”
  • Neat – “A lightweight semantic grid framework for Sass and Bourbon.”
  • Bitters – “Scaffold styles, variables and structure for Bourbon projects.”
  • Refills – “…prepackaged patterns and components, built on top of Bourbon, Bitters, and Neat.”

The idea of using clean and semantic markup that is based entirely on Sass mixins was pretty much the key factor which attracted me to try out Bourbon, Neat, Bitters and Refills.

But don’t get me wrong, I’m not about to bash Bootstrap as I enjoy using it to flesh out projects that require quick turn-around times and I’ve also written a previous post on how to use semantic classes in Bootstrap.

As one of the co-creator’s of Neat, Reda Lemeden writes in his post Introducing Bourbon Neat, a Sass-based responsive grid framework, he states that:

We built Neat with the aim of promoting clean and semantic markup; it relies entirely on Sass mixins and does not pollute the HTML with presentation classes and extra wrapping divs. It is less explicit—as in requires fewer mixins—than most other Sass-based frameworks and comes with built-in table-cell layout support.

The main motivation behind Neat is allowing anyone to build fluid, entirely semantic grid layouts without having to wade through hundreds of lines of documentation. We also believe that giving designers the ability to override the default behavior without hassle is key.

For the simple fact that it’s lightweight in size and is based on Sass mixins was enough for me to experiment with this framework. It also means none of the bloated and unused code of the framework will weigh down the loading time of your site as only the mixins you’re using gets compiled (to get your final CSS output). This is definitely a huge plus.

However there are caveats of using Bourbon and Neat that should be kept in mind. In this post Create responsive grid layouts with Bourbon Neat, by Derek Blank, he states that “IE7+ support is possible when Bourbon is used with Selectivizr for CSS3 selectors and Respond.js for media queries.”

Experiences with Bourbon, Neat, Bitters and Refills

After watching the series on Awesome CSS with Bourbon, Neat, Bitters & Refills! by PHP Academy, I installed Bourbon, Neat and Bitters.

When I wanted to use refills (and after compiling), the following error message appeared:

"Error: $large-screen (refills) variable not defined"

In Part 6 of the series, I noticed that other people had similar issues to me when following this video tutorial.

So to overcome this error, I did the following:

  1. Doing a Google search I found this post

    But instead of uncommenting line #4 in bitters.scss, it’s now uncomment line #8 in the base.scss file.

  2. Then within the base folder, find grid-settings.scss and comment out:

    @import 'neat-helpers';

    and use:


    I’m making the assumption that you’re developing in a non-rails environment.

  3. And finally, the order of your @imports in your styles.scss need to be listed in this order:


    Another assumption is that you’re using Neat.

Newbie Error

I wanted to include Normalize to my project but I made the mistake of naming: @import “normalize.css” in my main styles.scss file.

Instead I should re-name “normalize.css” to “_normalize.scss” as a partial file and therefore within my styles.scss file, the name of the normalize import should be:

@import "normalize"; 

The benefit of this is to reduce the number of http requests if you are linking directly to the normalize CSS file.


Start using Sass

I really wanted to point out the reasons why web developers should start using Sass and I came across the Clean out your Sass junk drawer slides by Dale Sande. It shows just how much the thought process of well structured CSS has changed over the years. So if you still work with fellow front-end web developer/engineers who aren’t using any CSS Preprocessor, point them to these slides.

CSS3 Background-Image

While creating a prototype for a project (using Bootstrap), I added the Jumbotron component which is described as: “a lightweight, flexible component that can optionally extend the entire viewport to showcase key content on your site” and found that my background image wasn’t responsive at all.

After searching on Stack Overflow, I found that using “background-size: cover” to the Jumbotron class works to make the background image responsive. For example, see below:

    background: #efefef url(image.png) no-repeat center center fixed;
        -webkit-background-size: cover;
	-moz-background-size: cover;
	-o-background-size: cover;
	background-size: cover;

So here’s a more in depth look at using “Responsive Full Background Image Using CSS” by Jacob Gube.

“The CSS background-size property can have the value of cover. The cover value tells the browser to automatically and proportionally scale the background image’s width and height so that they are always equal to, or greater than, the viewport’s width/height.” – Jacob Gube

Jacob continues to say that “to enhance the page load speed on small screens, we’ll use a media query to serve a scaled-down version of the background image file.” He further states the reason to use media queries is that “it’s a huge payload just for a background photo” which is never a good thing and that “it’s exceptionally bad on mobile internet connections”. Adding that “the image dimension is excessive on small-screen devices”.

Jacob wraps up his tutorial by stating, “if I can say just one cautionary thing about this technique, it’s this: Please use it with care because large files can severely affect UX, especially when our user is not on a fast or reliable Internet connection. This is also the reason why you should set a good default background color so the user can read the content while the background image is loading.”

So this is all well and good for the majority of browsers, except for IE8. If you look at Can I Use you will see that IE8 doesn’t support this CSS3 feature.

To overcome this issue, I found an article on “How to Enable Background Size in Internet Explorer” by Thoriq Firdaus.

Thoriq demonstrates how the CSS3 Background Size property can be used in Internet Explorer. He states that “unfortunately, this feature does not fallback nicely in Internet Explorer 8 and below. If you attach a very large image, it may overflow the container.”

So Thoriq mentions to use the Background Size Polyfill developed by Louis-Rémi. This polyfill “replicates the same behaviour of background-size property with cover and contain values. This polyfill comes in the form of an HTC file named backgroundsize.htc, and an .htaccess file, which is required when the page is served from Apache server to send the .htc mime-type.”

He goes on to provide the following instructions, “to use it, include the HTC file through the Internet Explorer behavior property, as follows.”

.background-size {  
        width: 500px;  
        height: 320px;  
        background-image: url('img/image.jpg');  
        background-size: cover;  
        -ms-behavior: url('http://example.com/js/backgroundsize.htc');  

I’ve noticed in the code example above, that it’s probably not a good idea to give your class and CSS selector the same name eg. background-size.

He goes on further to instruct “…if you are using Apache server, place the .htaccess in the root folder of server or, simply add this line to the existing .htacces file, if available.”

AddType text/x-component .htc  


Semantic classes in Bootstrap

According to Bootstrap, “you can modify the variables to your own custom values, or just use the mixins with their default values.”

Using @extend

An example of writing semantic code using Bootstrap is using @extend:

As written by Brad Borrow in the article Using Sass To Semantically @extend Bootstrap, he says that Bootstrap “makes it incredibly easy to write cluttered, non-semantic and non-reusable markup that will render correctly across all browsers.”

He goes on to explain what writing semantically means, “HTML documents are intended to be descriptive of their contents from an information hierarchy perspective. One should be able to read them and know what they are about, not how they will look.”

So to use Bootstrap semantically, Brad further states that we can “leverage the power of Sass’s @extend functionality to solve this problem. From Sass’s documentation: @extend works by inserting the extending selector anywhere in the stylesheet that the extended selector appears. This means we can use our semantic selectors and extend Bootstrap’s selectors to get all of its goodness.”

Using @mixins

Another example of writing semantic code using Bootstrap is by using mixins:

In this “Bootstrap and Sass” video (by Easy Dev Tuts) it shows us how to use Bootstrap’s mixins for Sass. You can also download the repository of this tutorial.

So instead of writing:

  <div class="container">

From this example we include the mixin container-fixed to apply the container. In this example, it’s applied to the body tag:

	@include container-fixed();

So instead of writing the following built-in Bootstrap classes in our HTML:

    <div class="row">
        <div class="col-sm-3"></div>
        <div class="col-sm-9"></div>

We can create our own (of course, trying to be semantic as possible) such as the below, which will give the same results as using the above Bootstrap classes.

		@include make-row(); // adds a row
			@include make-sm-column(3); // adds a column
			@include make-sm-column(9); // adds a column

Brett Jankford wrote an in-depth article about his thoughts on semantic HTML class names and maintainability.

While indicating the clear benefits of using Bootstrap and built-in classes, “frameworks like Twitter Bootstrap which use visual (presentational) class names are widely popular. Back-end developers that I’ve talked to that have used Twitter Bootstrap seem to really like it. They love the plugin-in-play ability with adding visual class names to elements. They don’t have to get in and mess around with the CSS, they can just add and remove classes as needed.”

There is a need to think about future maintainability of classes, “with individual role based classes, this flexibility is tricky. If we class the sections of the page individually, based on their role, with little thought to reusability, the CSS and the corresponding HTML classes offer little ease of maintenance and extensibility. If new sections are added, we need to add new role based classes along with additional CSS that corresponds to these new classes.”

To summarise

I’ve described various methods on how to use semantic classes using Bootstrap. It gets complicated when trying to come up with new semantic classes to replace Boostrap’s existing classes especially for components such as; the navbar, jumbotron and carousel to name a few.

So in the real world, can we really afford the time to completely re-structure classes to be semantic? It’s really up to your individual needs and the size of your project. You might only need to use semantic classes on the responsive grid structure but when it comes to using components, that will be challenging! And another thing to consider is, do you really need the extra bloat of a CSS framework or is it the responsive grid that you only need? (and there are a plethora of grid only frameworks).

To be semantic or not to be?


Further reading

Grunt build error behind proxy

While working on a project, I used the Yeoman webapp generator and selected; Bootstrap Sass, jQuery and Modernizr. Everything has worked well, the ‘grunt serve’ and ‘grunt test’ commands, however when I want to run the ‘grunt build’ command to upload the contents of my ‘dist’ folder to a web server, I get prompted with the following error:

Looking for Modernizr references in dist/styles/main.css >> svg
Downloading source files
A server error occurred attempting to download a file: 
Fatal error: connect ETIMEDOUT

I’m not sure if it’s something to do with my bower components or the proxy that I’m sitting behind?

At the moment, the workaround I’m using is to manually add the scripts (jQuery, Modernizr and Bootstrap) to the scripts folder then to link it to my html files. But surely there is a better way to do this?!

CSS3 Grayscale Filter

So I stumbled upon a quick video on YouTube on how to use the CSS3 grayscale filter upon hovering on an image.

The results can be seen below:

See the Pen hcBCJ by Adeline (@adelineyaw) on CodePen.

Click on the CSS tab in the Codepen example above to see how this filter effect can be implemented in your CSS.

Unfortunately this effect can’t be seen on Firefox as it’s not supported so please refer to “Can I Use” to find out if your browser supports this CSS3 filter.

“Method of applying filter effects (like blur, grayscale, brightness, contrast and hue) to elements, previously only possible by using SVG.” – Can I Use

“It’s worth noting that right now, CSS Filter Effects are an unoffical specification – however, the editors of the spec include representatives from Adobe, Apple and Opera, and we have already got implementations in Chrome, Safari and iOS 6.” – CSS3 Filters


Preprocessing is for Everybody

Preprocessing is for Everybody by Chris Coyier

“You’ve heard about CSS preprocessors. If you have yet to take the dive or have only dipped your toes in, let Chris Coyier (CSS-Tricks, Codepen) convince you that you won’t regret it. Have you met resistance? Let’s try and convince your boss and colleagues. There may be some misconceptions going around that we need to nip in the bud. Then we’ll look at how preprocessors fit into the modern web development workflow, the evolving best practices for using them, and how to squeeze out all the benefit we can get from them.” – An Event Apart Video

Responsive Images

The following video is from the post Responsive Images using <picture> and srcset/sizes – by Matt Steele

Big heavy images are responsible for most of the bloat on a responsive website, but it doesn’t have to be that way. Here’s the latest HTML elements you can use to keep your images small, and your site lean & fast. – Matt Steele

Reference: Srcset and sizes

Features of Compass

“Compass is an open-source CSS Authoring Framework.” – Compass

“Compass can do some really handy tasks like measuring images from the filesystem and writing them into your stylesheets. Asset URL functions are available that make it easy to move assets around in a project or even switch to a content delivery network (CDN) without having to rewrite your stylesheets. Compass can even combine a directory of images into a single sprite image and do the otherwise tedious task of calculating coordinates and writing the spriting CSS for you.” – Sass and Compass in Action (Manning)

Some of the features of Compass I’ll be covering are:


From my previous blog post, I used an example of a mixin for a box with a border-radius. This time instead of re-writing the prefixes seen below;

-moz-border-radius: 10px;
-webkit-border-radius: 10px;
border-radius: 10px;

We can use the Compass mixin called border-radius.

For example:

Play with this gist on SassMeister.

And we can define the 10px in the parentheses when you include the mixin.

Image Sprites

Instead of having to use your preferred image editor to create your image sprite, Compass can do this for you. Simply throw in your icons into a specific folder and let the Compass Sprite utility, create the sprite and calculate the CSS positions for you. Another feature is that Compass also recognizes the hover state of your image by simply saving your image, eg. facebook_hover.png

The following excerpt is from the Spriting with Compass reference page

Basic Usage

**Note: The use of social is only for this example, “social” represents the folder name that contains your sprites.

The simplest way to use these icon sprites is to let compass give you a class for each sprite:

In your SCSS file, add the following:

@import "compass/utilities/sprites"; 
@import "social/*.png";
@include all-social-sprites;

And you’ll get the following CSS output:

.social-youtube {
background-image: url('../img/social-sf14878b932.png'); 

// the name of your generated sprite image will be different

background-repeat: no-repeat;

.social-facebook {
background-position: 0 0;

.social-facebook:hover, .social-facebook.facebook-hover { 
background-position: 0 -80px;

.social-linkedin {
background-position: 0 -160px;

.social-linkedin:hover, .social-linkedin.linkedin-hover {
background-position: 0 -240px;

.social-twitter { 
background-position: 0 -320px;

.social-twitter:hover, .social-twitter.twitter-hover {
background-position: 0 -400px;

.social-youtube {
background-position: 0 -480px;

.social-youtube:hover, .social-youtube.youtube-hover {
background-position: 0 -560px;

This results in one single sprite image:

Compass Sprite example

You can now apply the social-your-class-name to your HTML as needed.

As stated earlier, the Sprite utility also recognizes if your icon requires a hover state. So add your hover state icons in the social folder (within your images folder).

Be sure to add in your “config.rb file” the location of your main images (root) folder.

Once you save the changes, the new sprite image will re-generate to include the hover state icons and thus your output CSS will also be updated. It is pretty amazing!

Font Face

The Compass Font Face provides a mixin to support @font-face. See CSS3 spec: @font-face.

This file can be imported using: @import “compass/css3/font-face”

Use the mixin font-face($name, $font-files, $eot, $weight, $style)


  • $name is required, arbitrary, and what you will use in font stacks.
  • $font-files is required using font-files(‘relative/location’, ‘format’). for best results use this order: woff, opentype/truetype, svg
  • $eot is required by IE, and is a relative location of the eot file.

See the Compass reference page for more details on this mixin and the use of $weight and $style.

For this example, I’m using the font called “TeXGyreHerosCnBold”.

In your SCSS file, add the following:

@include font-face("TeXGyreHerosCnBold", 

Then assign your font, eg. h1, h2:

h1, h2 {
font-family: "TeXGyreHerosCnBold", Helvetica, sans-serif;

Add your fonts to the fonts folder and define the location of your fonts in the config.rb file, fonts_dir = “fonts”. This is the directory where the font files are kept. Standalone projects will default to “css_dir/fonts”. Rails projects will default to “public/fonts”.

Extending Compass

There are quite a number of Sass and Compass resources but I want to mention, Sache. As the site says “Find the perfect tool for your next Sass or Compass project. Discover Sass & Compass Extensions”. There are plenty of Sass and Compass extensions/plugins listed on the site and I’ll be writing a future blog post about using Susy (a semantic grid framework) as well as Breakpoint Sass (a plugin for media queries).

So hopefully I’ve convinced you to use or at least try out Compass with your next Sass project!