CSS Dig: It’s Time to Refactor
On many sites CSS is like a neglected garage: you toss stuff in it for years always planning to get organized. Who knows what lurks in those corners? You might even be afraid to look. Multiple developers working with different designers, combined with a lack of standards, invariably lead to inconsistent and difficult to maintain code. Refactoring is your only hope.
But how do you start to identify the problem areas? Inspired by Nicolle Sullivan’s advice to “grep your styles”, CSS Dig is a Python script that runs locally to unearth properties and values from almost any website — from both linked CSS files as well as any code found in
style blocks — to help you analyze, refactor, standardize and maintain your CSS.
Figure 1 shows the three panels of a CSS Dig report. In the left panel all the properties that were found at the URL provided are listed. Those properties can be toggled, revealing and hiding data in the center panel. Details about the report appear in this center panel followed by counts and groupings of the declarations found. Each declaration can be clicked to reveal its origin in the combined CSS found in the third panel.
Here are a few examples. Note that you can run a report on any web page, not just the homepage.
- Report for nytimes.com
- Report for nytimes.com/pages/world/
- Report for msn.com
- Report for aol.com
- Report for apple.com
Colors, Colors and More Colors
A good place to start your analysis is to identify the colors declared on your site. Having too many is often an indicator that the rest of your code could use refactoring. Do you really need 10 similar shades of blue or is this more likely the result of developers and designers grabbing the wrong color?
For example, in Figure 2 below, this CSS Dig report on huffingtonpost.com reveals the CSS files contain 264 different color values (though some evaluate to the same color, for example,
Results like these indicate you probably need a style guide. Consolidate your blues and grays and reds into a simplified palette and make it easy for developers to pick the right one. If you’re using a CSS pre-processor (you are, right?) create variables and stick to them. After the refactor run the report again to see if anyone has strayed from the One True Path.
Apply this same process to consolidating font sizes, margins and paddings, and any other red flags that might be causing maintenance issues and ballooning CSS files. For example, note a few of the 22 unique z-index values found on msn.com.
... z-index: 10; z-index: 100; z-index: 100000; z-index: 100000000; ...
100 million! Can’t go any higher than that, right?
Coding Style & Standardization
Another area to look at is the consistency of your code. On many sites you’ll find color declarations like this:
color: #ccc; color: #cccccc; color: #CCC; color: #CCCCCC;
All four are equivalent and will render the same but why not be consistent? CSS Dig will expose this problem. Make a decision as a team what style you want to use and stick to it. The same kind of standardization should be applied to many different properties.
- Are you using pixels, ems, rems in your font-sizes, widths, heights?
- Are your font stacks consistent?
- Are you using hex colors, uppercase or lowercase?
- Do you use single quotes or double quotes?
- Do you have spaces after commas?
Rules like these can seem like nit-picking — and they are — but if you’re working on a large code base they all serve a larger purpose: If your code looks as though one developer produced it you’ll simplify maintenance and help new contributors get up to speed.
Don’t Stop Now
After a close examination of your CSS you’ll likely realize that that fixing a few color variables and font sizes only scratches the surface. What you really need to do is refactor your HTML along with your CSS.
This is a harder problem, beyond the scope of this post and the CSS Dig tool, but to help get started Nicolle Sullivan recently release the slides of her presentation on refactoring Trulia. Here are a few of her suggestions along with a few of my own.
- Audit your site’s design elements by taking screenshots of as many examples as you can find. Too many buttons styles is a common problem.
- Use svg icon fonts to replace your png sprites and be high-resolution ready.
- Try to move away from “page” or “view”-specific styles. Abstract your code into reusable patterns as much as possible.
- Create a living style guide so that your styles and documentation are one in the same.
- Consider adopting a CSS approach like OOCSS, BEM, SMACSS to give your class names and HTML more meaning.
- If using a pre-processor avoid nesting more than 3-levels deep.
- If you need to add hacky or questionable code add it to a separate “shame” file so it can be reviewed by the team, fixed or refactored.
A few other resources:
- Github’s style guide.
- CSS Tricks guide to starting a huge new web project.
- If using a pre-processor think about how best to organize your code: Typeplate, Bootstrap, and inuitcss are just three of many examples.
Make Reports & Contribute
If you run into any issues please create an issue. Your feedback is appreciated!
Special thanks to @nedrockson for his help and advice.