Posted in Design, Development

My road map to refactoring CSS in large code bases

For any organisation working on a large code base over a long period of time there will eventually be a point where the code has become unwieldy and it’s time to do a clean up.

In the last few years we’ve seen CSS3 standards roll out, some great tools and preprocessors such as SASS, the Rails Asset Pipeline (sprockets), and new standards for images such as SVGs. We’ve also seen how necessary responsive layouts are for the (ever growing) mobile user-base. We’ve all seen how CSS files can quickly get unwieldy and the cringe moment of finding code comments that say things such as /* Temp fix */ and it’s still there four years later.

Let’s think about the timescale of front end technology…I imagine it being like aging in DOG YEARS. So that makes a seven year old code base like 40-50 human years. By this age people tend to have accumulated a lot of stuff. It’s time to clean out that garage (filled to the brink with tools you no longer use, or remember how they got there).

* note – i’m coming at this from a background of working on a code base with 75 CSS files, some of which have been around for 6 years and a code base that used to support IE 5, 6, 7 and 8.

I’m sure my cataloguing and arranging made sense at one point…but do others know where to find things?

Photo credit: Jay Wennington from



So how does a web team that is busy doing-other-important-things (such as new features for customers) move a large code base into the Latest Way of Doing Everything?

I have some ideas…

Improving this is a long process that involves:

  1. Creating a road map (have a big picture view as well as an MVP view)
  2. Developing a framework and common language for your team (agreeing how you are going to split things up, look at frameworks, naming conventions etc)
  3. Utilising tools to help analyse your existing code
  4. Creating a pattern library (living style guide)
  5. Using iterative design and iterative releases
  6. Having designers and developers working closely together

1. Create a road map

Photo credit: Fritz Bielmeier from

It helps to have someone who is doing the future thinking and someone working for the current priorities. These two paths will need to meet at some point. I do not believe in pixel perfect design (for the web) nor do I believe that a design is ever finished or static. We are in a field where change happens regularly, for the customer, the business and also for the technology involved and the devices used to engage with your product.

You need the big picture thinker to be able to lay a pathway for people to work towards but you also need to work with someone who knows how things work now and can visualise how things will integrate. That person needs to design and develop in a structure that allows for the codebase to scale.

Knowing what is coming up in the road map will help everyone even if the details are not finalised. Know the rough destination…your paths will change along the way.

2. Develop a framework and common language for your team

  • Read SMACSS and the Atomic design guide. Familiarise yourselves with the concepts of OOCSS.
  • Have an internal debate/discussion. What works for you? Pros and Cons of each way?
  • Full folder restructure, refactor and clean up!
  • Check for repeated code, unused code and things that can be turned into SCSS variables and mixins
  • Discuss frameworks (Bourbon Neat, Bootstrap etc). Do you want to roll your own? Do you need a whole framework?

Note on SMACSS and Atomic – These principles are really great, but each site/product and team should still do things that work for their situation. After some internal debate we’ve gone with a mashup of both of these ideas.


3. Utilize tools to help analyse your existing code

Here are a few tools that might help you see where you can clean things up

  • CSS Dig – Chrome extension
  • CSSCSS – Redundancy analyser
  • Helium – A tool for discovering unused CSS across many pages on a web site. The tool is javascript-based and runs from the browser

4. Create a pattern library (ideally a living style guide)


This is the best thing. A consistent interface. A source of truth for the styling. Happy developers. Happy designers. Happy customers.

It’s really useful because as you refactor your code base you can come here and see how all your main components are looking. It makes it way easier to see if you have broken something.

Your pattern library should be using the compiled CSS that your main code base is using so that it is exactly the same (remember…one source of truth!).

You’ll have nice re-usable code! We follow DRY practices for other areas but CSS often gets left behind. Using modular and reusable components makes things easier to maintain, to test and to mockup new pages because the parts are mostly built.

Examples of pattern libraries:



5. Use iterative design & iterative releases

This links back to the road map. Understand that early on you might have to compromise design details and features to make an MVP but you should be able to design in a way that allows for progressive enhancement. Get stuff out there early, get feedback and iterate on it.

6. Designers and developers working closely together

I’m a strong believer in cross functional teams and pairing. Try having designers and developers pair on something. This way when issues crop up (technical, design, usability) you can problem solve together.



Have a look at visual regression testing – there are automated testing tools out there that will run your site in a browser and check screen shots against each other and create DIFFs like you might be familiar with in git. This is useful if you need to be absolutely sure that nothing has broken somewhere.

Visual Regression Tools


Huxley & node-Huxley