Building things on the internet

Converting your CSS project to Sass

Over the past year I have spent a lot of my focus learning and leveling up on my Sass knowledge. Talking with others, I think the most common concern when switching over to a CSS preprocessor is this:

I don't know where to start when converting my CSS project over to Sass.

There is plenty of documentation and know-how going around with starting new projects with Sass and Compass, but taking the time to convert an existing project over could use some help. Here's a step-by-step guide:

Photo credit to Bermon Painter.

1. Rename your .css files to .scss

It's kind of a running joke in the Sass community that all you need to do to start using Sass on an existing project is change the syntax from .css to .scss. But it's true, that alone will get you started much like changing your doctype to <!DOCTYPE html> will get you started with using HTML5. All of your existing CSS rules will work under the Sass syntax.

2. Install Sass and Compass locally

You will need to fire up Terminal and install a ruby gem from the command line (all you have to do is type the line below).
gem install sass

If you get an error, you can use sudo to install:
sudo gem install sass

While you are in Terminal, you should install Compass, a seriously helpful CSS authoring framework:
gem install compass

Same goes for Compass, if you get an error, use sudo.

Now, working from the command line will scare off some designers, but there are plenty of apps that will do the same thing for you. If that's you, I would recommend trying out:

  • Codekit - $28, This app basically installs Sass for you and runs the command needed to watch and compile changes (compass watch). It has a lot of extras as well, like working with CoffeeScript, image optimization, minification, etc.
  • LiveReload - $9.99, A stripped down version of Codekit, primary focus of the app is style injection or automatically refreshing the browser when you make code changes, but it will also compile Sass for you.

3. Set-up a config.rb file

Compass's docs are awesome but can be a bit overwhelming if you are going to the site as a new user. This page is focused on all of the configuration options in the config.rb file.

Here's what you really need to get set-up:

http_path = "/"
css_dir = "css"
sass_dir = "scss"
images_dir = "img"
javascripts_dir = "js"
output_style = :expanded
relative_assets = true
line_comments = true

This will specify all of the nescessary directories, output style, assets and comments settings. Remember to change output_style to compact or compressed and line_comments to false when going to production.

Any Compass plug-ins you want to use, for example, Susy for responsive grids, is loaded with require, by calling:
require susy

At the top of the config.rb file.

OK, now for the meat and potatoes.

There are some useful CSS to Sass convertors out there, I would recommend using them to get a better idea of how to restructure CSS as Sass. And equally important to grasp the subject, how Sass compiles to CSS.

  • CSS2Sass - Copy and paste chunks of your project in Sass to see how it would be written in Sass. I wouldn't recommend re-factoring your entire project this way, but try it out with a few sections and once you get a feel for the most conveinent Sass features, including nesting, you can rewrite your stylesheet rules by hand.
  • Sassmeister - This is basically Codepen for Sass. Its newest release introduced an HTML component so you can visualize your changes. Extremely helpful, not only for learning but for trying out popular Compass extensions.

Re-structuring your CSS project

One of the biggest advantages of working in Sass is thinking and maintaining your project with a modular approach. The @import directives, when using partials are all piped into the same stylesheet and only require one HTTP request. A partial is a .scss file with an underscore in front of it that is imported into another file instead of compiled as a separate CSS file, i.e. _header.scss.

Here's one example Sass directory structure, loosely based on SMACSS, really the best methodology to follow is the one you are most comfortable with, use more specific and conditional stylesheets as needed:

Use your custom Sass file as a table of contents to import all of your necessary partials and comment your work. It's also important that if you are using Compass, you import that, @import "compass", as well. Keep in mind, you don't have to import the whole Compass library, you can pick your spots, like @import "compass/css3", etc. More here.

Here's one way to restructure, this the root folder with three directories: base, components and layout.


I know sometimes you are starting with a 5,000 line CSS file with no direction or discernible organization. You probably won't rework your gargantuan CSS file into a modular structure in one sitting. The best approach you can take is to just start and keep organizing as you go. It's OK that some of your .scss files will only have CSS styles in them for the time being, soon enough you will be able to use variables, mixins, extends and nesting to speed up your workflow.

My advice for taking this on is to do so in small chunks and continually make progress as you go. You can start by renaming your stylesheets to the Sass syntax and setting up your new folder structure. Then, pick one section, i.e. buttons, and start to move your styles in there. Keep in mind this is will have the greatest benefit for a project you are heavily involved with on a daily basis, not one you occasionally maintain.

As you get started, check out David Walsh's post on CSS-Tricks, Redesigning with Sass to make sure you don't make those beginner mistakes, like bloating and specificity issues.

As a little extra incentive, check out Team Sass on Github, for some really impressive tools you can add to your workflow:

  • Breakpoint - Simple media queries
  • Modular Scale- Automatically alculate all of your ratios
  • SassyLists- A wide range of function for re-ordering lists.
  • Singularity - Create your own grids for responsive design
  • Toolkit - A bunch of helpful pieces for responsive design and progressive enhancement

Get a free chapter from my upcoming book Design & Conquer: Modern Web Design in the Post-PSD Era and an early access discount when it launches later this year.

* indicates required