Illustration by

CSS Audits: Taking Stock of Your Code

Most people aren’t excited at the prospect of auditing code, but it’s become one of my favorite types of projects. A CSS audit is really detective work. You start with a site’s code and dig deeper: you look at how many stylesheets are being called, how that affects site performance, and how the CSS itself is written. Your goal is to look for ways to improve on what’s there—to sleuth out fixes to make your codebase better and your site faster.

Article Continues Below

I’ll share tips on how to approach your own audit, along with the advantages of taking a full inventory of your CSS and various tools.

Benefits of an audit#section2

An audit helps you to organize your code and eliminate repetition. You don’t write any code during an audit; you simply take stock of what’s there and document recommendations to pass off to a client or discuss with your team. These recommendations ensure new code won’t repeat past mistakes. Let’s take a closer look at other benefits:

  • Reduce file sizes. A complete overview of the CSS lets you take the time to find ways to refactor the code: to clean it up and perhaps cut down on the number of properties. You can also hunt for any odds and ends, such as outdated versions of browser prefixes, that aren’t in use anymore. Getting rid of unused or unnecessary code trims down the file people have to download when they visit your site.
  • Ensure consistency with guidelines. As you audit, create documentation regarding your styles and what’s happening with the site or application. You could make a formal style guide, or you could just write out recommendations to note how different pieces of your code are used. Whatever form your documentation takes, it’ll save anyone coming onto your team a lot of time and trouble, as they can easily familiarize themselves with your site’s CSS and architecture.
  • Standardize your code. Code organization—which certainly attracts differing opinions—is essential to keeping your codebase more maintainable into the future. For instance, if you choose to alphabetize your properties, you can readily spot duplicates, because you’d end up with two sets of margin properties right next to each other. Or you may prefer to group properties according to their function: positioning, box model-related, etc. Having a system in place helps you guard against repetition.
  • Increase performance. I’ve saved the best for last. Auditing code, along with combining and zipping up stylesheets, leads to markedly faster site speeds. For example, Harry Roberts, a front-end architect in the UK who conducts regular audits, told me about a site he recently worked on:

    I rebuilt with a view to improving its performance; it went from 27 separate stylesheets for a single-page site (mainly UI toolkits like Bootstrap, etc.) down to just one stylesheet (which is actually minified and inlined, to save on the HTTP request), which weighs in at just 5.4 kB post-gzip.

    This is a huge win, especially for people on slower connections—but everyone gains when sites load quickly.

How to audit: take inventory#section3

Now that audits have won you over, how do you go about doing one? I like to start with a few tools that provide an overview of the site’s current codebase. You may approach your own audit differently, based on your site’s problem areas or your philosophy of how you write code (whether OOCSS or BEM). The important thing is to keep in mind what will be most useful to you and your own site.

Once I’ve diagnosed my code through tools, I examine it line by line.


The first tool I reach for is Nicole Sullivan’s invaluable Type-o-matic, an add-on for Firebug that generates a JSON report of all the type styles in use across a site. As an added bonus, Type-o-matic creates a visual report as it runs. By looking at both reports, you know at a glance when to combine type styles that are too similar, eliminating unnecessary styles. I’ve found that the detail of the JSON report makes it easy to see how to create a more reusable type system.

In addition to Type-o-matic, I run CSS Lint, an extremely flexible tool that flags a wide range of potential bugs from missing fallback colors to shorthand properties for better performance. To use CSS Lint, click the arrow next to the word “Lint” and choose the options you want. I like to check for repeated properties or too many font sizes, so I always run Maintainability & Duplication along with Performance. CSS Lint then returns recommendations for changes; some may be related to known issues that will break in older browsers and others may be best practices (as the tool sees them). CSS Lint isn’t perfect. If you run it leaving every option checked, you are bound to see things in the end report that you may not agree with, like warnings for IE6. That said, this is a quick way to get a handle on the overall state of your CSS.

Next, I search through the CSS to review how often I repeat common properties, like float or margin. (If you’re comfortable with the command line, type grep along with instructions and plug in something like grep "float" styles/styles.scss to find all instances of "float".) Note any properties you may cut or bundle into other modules. Trimming your properties is a balancing act: to reduce the number of repeated properties, you may need to add more classes to your HTML, so that’s something you’ll need to gauge according to your project.

I like to do this step by hand, as it forces me to walk through the CSS on my own, which in turn helps me better understand what’s going on. But if you’re short on time, or if you’re not yet comfortable with the command line, tools can smooth the way:

  • CSS Dig is an automated script that runs through all of your code to help you see it visually. A similar tool is StyleStats, where you type in a url to survey its CSS.
  • CSS Colorguard is a brand-new tool that runs on Node and outputs a report based on your colors, so you know if any colors are too alike. This helps limit your color palette, making it easier to maintain in the future.
  • Dust-Me Selectors is an add-on for Firebug in Firefox that finds unused selectors.

Line by line#section5

After you run your tools, take the time to read through the CSS; it’s worth it to get a real sense of what’s happening. For instance, comments in the code—that tools miss—may explain why some quirk persists.

One big thing I double-check is the depth of applicability, or how far down an attribute string applies. Does your CSS rely on a lot of specificity? Are you seeing long strings of selectors, either in the style files themselves or in the output from a preprocessor? A high depth of applicability means your code will require a very specific HTML structure for styles to work. If you can scale it back, you’ll get more reusable code and speedier performance.

Review and recommend#section6

Now to the fun part. Once you have all your data, you can figure out how to improve the CSS and make some recommendations.

The recommendation document doesn’t have to be heavily designed or formatted, but it should be easy to read. Splitting it into two parts is a good idea. The first consists of your review, listing the things you’ve found. If you refer to the results of CSS Lint or Type-o-matic, be sure to include either screenshots or the JSON report itself as an attachment. The second half contains your actionable recommendations to improve the code. This can be as simple as a list, with items like “Consolidate type styles that are closely related and create mixins for use sitewide.”

As you analyze all the information you’ve collected, look for areas where you can:

  • Tighten code. Do you have four different sets of styles for a call-out box, several similar link styles, or way too many exceptions to your standard grid? These are great candidates for repeatable modular styles. To make consolidation even easier, you could use a preprocessor like Sass to turn them into mixins or extend, allowing styles to be applied when you call them on a class. (Just check that the outputted code is sensible too.)
  • Keep code consistent. A good audit makes sure the code adheres to its own philosophy. If your CSS is written based on a particular approach, such as BEM or OOCSS, is it consistent? Or do styles veer from time to time, and are there acceptable deviations? Make sure you document these exceptions, so others on your team are aware.

If you’re working with a client, it’s also important to explain the approaches you favor, so they understand where you’re coming from—and what things you may consider as issues with the code. For example, I prefer OOCSS, so I tend to push for more modularity and reusability; a few classes stacked up (if you aren’t using a preprocessor) don’t bother me. Making sure your client understands the context of your work is particularly crucial when you’re not on the implementation team.

Hand off to the client#section7

You did it! Once you’ve written your recommendations (and taken some time to think on them and ensure they’re solid), you can hand them off to the client—be prepared for any questions they may have. If this is for your team, congratulations: get cracking on your list.

But wait—an audit has even more rewards. Now that you’ve got this prime documentation, take it a step further: use it as the springboard to talk about how to maintain your CSS going forward. If the same issues kept popping up throughout your code, document how you solved them, so everyone knows how to proceed in the future when creating new features or sections. You may turn this document into a style guide. Another thing to consider is how often to revisit your audit to ensure your codebase stays squeaky clean. The timing will vary by team and project, but set a realistic, regular schedule—this a key part of the auditing process.

Conducting an audit is a vital first step to keeping your CSS lean and mean. It also helps your documentation stay up to date, allowing your team to have a good handle on how to move forward with new features. When your code is structured well, it’s more performant—and everyone benefits. So find the time, grab your best sleuthing hat, and get started.

About the Author

Susan Robertson

Susan Robertson is a front end developer working with Fictive Kin who focuses on CSS, style guides, responsive, and accessibility. In the past, she has worked with clients such as FiftyThree, Imprint, Cloud Four, and worked for Editorially, The Nerdery, and Cambia Health. When not actually writing code, she can be found writing about a wide variety of topics on her own site as well as contributing to A List Apart and The Pastry Box. When not staring at a screen, she reads comics and novels, cooks lots of yummy food, and enjoys her Portland neighborhood.

11 Reader Comments

  1. Thanks Susan! This is just the article I’ve been looking for. In the tools category, running an audit in Chrome Dev Tools will also create a list of unused CSS rules.

  2. Hi Susan,

    Your introduction paragraph is brilliant. It caught my attention and began to read this Blog post. I totally agree with you that a CSS audit is quite a bit like detective work. When doing an audit, one has to be able to visualize what the coder wants to do then perhaps with a little thinking out of the box find a way of reducing the rules declared in multiple IDs and Classes to achieve the same thing.

    This is especially true of younger perhaps inexperienced programmer / designer. I’ve often noticed that they declare new classes when with just a bit of rationalization / tweaking a class already defined can be used.

    You so rightly point out that simply tweaking a lot of the older Browser prefixes that are outdated today can reduce the CSS file size which results in a reduction in the page load time. How very true that. When working with CSS files I’ve often noticed a reduction of between 15% to 35% (Extreme cases) after a proper CSS audit.

    I really like your logical approach to CSS auditing. During the first pass of the CSS audit, create a document about the IDs / Classes and what they do for the webpage. Then handle the application of CSS coding standards to the CSS codespec based on this document.

    This approach guarantees a reduction in file size and standardization means ease of maintenance.

    The truth be told I did not know anything about the CSS audit tools you’ve detailed. I’m going to start using them immediately. I’m sure they will make me a ton more productive.

    Thank you for sharing a brilliant and detailed Blog post. I found it educated me and reinforced many of my beliefs.


    Ivan Bayross

  3. re: “you may turn this document into a style guide. Another thing to consider is how often to revisit your audit to ensure your codebase stays squeaky clean. ”

    I really enjoyed the article and found it quite helpful. Thanks. That said, an audit, by definition, is reactive. Again, great stuff here but putting out fires isn’t as effective as preventing fires That is, it would be great to hear more about being proactive.

    For example, yes a style guide is great to have, but having one and getting a team to buy in, use it, and evolve it, are two very different things. In short, speaking for myself, I think it would help to hear more about identifying and solving the organizational issues that directly and indirectly impact code / product quality.

  4. Thanks so much for the comments, I appreciate them.

    @MF Simchock: you are right that an audit is reactive, you usually do it because you realize there are already problems. But I would argue that the audit can help you put in place documentation that will prevent the fires in the future. So as you audit, you write up how you would write styles in the future and hopefully make a system that you can then check back in on periodically to make sure it’s working. As I talk about towards the end, documenting what you’ve found, by getting the documentation up to speed as part of the process, hopefully you will prevent the fires in the future.

    I would also argue that the audit doesn’t have to be reactive to bad fires, it could also just be something you do to check in, on a regular basis, on the styles and your documentation to make sure it’s all still working for you.

  5. Multi-stage projects, developers inheriting work from previous developers, time crunches to get new features added … despite one’s best forward-looking intentions, the de-optimization creep still happens. One has to keep both proactive and reactive measures in place to avoid it.

  6. Great article – thanks for that.

    You mentioned audit tools. I searched high and low for something that would give me a report of all the classes used on an entire site (and the URLs where they appear). I couldn’t find one so I wrote one myself.

    This article inspired me to tidy it up a little and update the repo, if it’s useful to anyone else:

    It’s still in beta, really, but it crawls a website from any given URL and builds two JSON files. The first lists all the URLs found on the site and then lists all the classes found at each URL, while the second lists all the classes found during the crawl and then lists all the URLs where that class appears.

    Just thought I’d share.

    Thanks again.

  7. Great article!. It also helps to have some way to automatically test your code when you are changing it, it liberates you from having to check every layout ‘by eye’, I’m talking about tools like Wraith or Diffux they compare screenshots and let you know when things change.

    It is similar to running tests when refactoring code.

Got something to say?

We have turned off comments, but you can see what folks had to say before we did so.

More from ALA