Refactoring Sass at Scale

by Miriam Nadler / @antimytheme

If you are planning on refactoring Sass at scale, you are planning on interacting with a beast. You might be staring at a beast that was birthed last month; you might be staring at a beast that was birthed several years ago.

Refactoring eliminates those vestigial bits of your codebase that drag behind, and results in a far more spry creature. Refactoring is cleanliness is next to godliness as a taxidermic device utilized on the living. I have some tips on how to do this to creatures that are far bigger than you.

I have refactored the Sass portions of several large codebases. I have been asked about how I go about doing this. This post serves as my answer.

My recommendations in this post consist largely of assorted tips about the refactoring process writ large. I do not make any recommendations about, for instance, whether to use @mixins or @extends. If you are looking for how to write crisper Sass in general, check out Sass Guidelines instead.


Jacques Lacan, at some point or another, brought up pigeons to make a point about humans. The pigeons were said to only undergo biological sexual differentiation once they had seen another pigeon, or else had seen their own reflection.

Sass is not the skin of a website; that would be CSS. Sass is the innards. So what does it mean, to look at jumbled Sass? To look at the tangled styles of a creature and see yourself? To feel yourself coursing through the intestinal tract of a body politic? To be at once tangibly indigestible and infinitely desired, gnawed on and swallowed up, bodyslammed into colonic walls and spat out ad infinitum? To know that there’s no way out?

It all sounds rather unpleasant! I advise that you do not allow this sexual differentiation to occur in the first place. If it is not too late for you, drape blankets over every mirror in your workplace. This will be easier to do if you work remotely.

After you have done this, admonish yourself for thinking it mattered. Visiblity matters, sure, but you're always looking at yourself, and others are always looking at you. The lights could be off and the windows shuttered; it matters little. Any attempt to not be consumed by society will probably be an inevitable failure.

The first step in inevitable failure is to check for unnecessary synonyms in your Sass. This step alone can get you a long way towards feeling like the codebase is more manageable.

I like to start with colors. Find all of your #FFFFFFs and #ffffffs and #FFFs and #fffs and rgb(255, 255, 255)s, and pick one way to represent them. This will make future synchronization work far easier. Do the same for font sizes, line-heights, and length units in general. Standardize all units wherever possible.

Next, check for inconsistencies in indentation and spacing. .editorconfig can be a great boon here, as can linters like sass-lint. Both allow you to automate the most finicky aspects of this stage. Whatever your standards for syntax are, this is the time to apply them ruthlessly.

The end result of this stage should be that everything that is the same actually looks the same. Any Sass that compiles out to the same CSS should, ideally, come up in the same search query.


This is a suggested methodology which applies to as much of the procedure as you can possibly apply it to.

It does no good to remove too much in one go. Instead, I advocate that you slowly shave and pick and pry away. It’s not like you generally clean yourself vertically, scrubbing bone and muscle and tendon and ligament and skin all at once. No; you scrub the skin, and it flakes off, and it goes down the drain, and that means that at least some part of you is definitionally trash.

It is only once the skin has been washed away that you can apply soap to the organs.

Let’s say that you have about forty files in your body. Five to ten may already be pattern files, and pertain to reusable components. One or two are for different sorts of variables. The rest are likely styles that apply only to particular pages, views, or unique components.

You could go through each unique component file one-by-one, completely cleansing each from top to bottom. This is certainly tempting, as it provides a more pleasing benchmark for completed work. You get to say to yourself: hey, I refactored five files today! However, by synchronizing literals (colors, lengths, etc) everywhere, and then denesting everywhere, and so on, patterns will naturally emerge. You will probably notice that certain chunks of code that were previously being compiled into identical CSS now also have identical Sass. You might not have noticed these similarities if you were working piecemeal.

When discovered, these should be marked for later review, and, hopefully, patternization. By ‘marked’, I mean anything from a todo plugin in a build tool to simply searching for the string ‘TODO:’ in your codebase.


Remember that your body is the enemy. Remember that you are here to win. Information is the best tool at your disposal in your pursuit of victory.

You probably already have a system of colors and patterns and shapes and semantic affiliations. List them out somewhere. Find every last thing that is emergent or undefined about yourself, and package it under some semantic hierarchy. If you find anything that is simply undefinable, mark it for deletion.

I use a combination of screenshots and a spreadsheet app to keep track. For example, being able to look at every input type side-by-side is invaluable; it becomes much easier to spot gaps in your visual / semantic logic. At the same time, it’s good to actually have it written down somewhere that you completely forgot about range inputs.


Try to look at the world as with the eyes of an infant. Please make note of the word ‘as’ in the previous sentence. Whenever anyone mentions a social structure in your presence while you are refactoring, exclaim, “but it’s just a pile of bricks!,” and consider using a tool like PhantomCSS to make the task easier. You will be able to excise with more confidence, knowing that you have a visual regression tool doing the looking for you.

The more complicated the site you are refactoring, the more useful these tools are. If you are very careful, you might manage to forgo visual regression testing while refactoring and still not cause any breaks in style. You also might attain beatitude. PhantomFlow is a more recent addition to the visual regression testing world, and it’s become infinitely more useful with PhantomJS 2 support. Being able to write decision trees for front-end user flows is a tantalizing prospect. I’d suggest looking up SlimerJS, NightmareJS, and CasperJS.

You could ask yourself why so many visual regression and automated testing tools have ghost metaphors for names.

Perhaps the authors of these tools have felt distant from themselves for long enough that they began to embody that distance, or are now possessed by their own longing to close that distance.

Perhaps they simply like the idea of a second computer, inside of your computer, haunting it, navigating the internet while you sit there and wait for the task to finish, listlessly present.