Introducing the WordPress CSS Audit Tool

The CSSCSS Cascading Style Sheets. Audit Tool generates an HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. representation of audit data. View it live.

What it is

An automated tool for generating reports on the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. CSS files. The reports are made up of one or more audits, each of which provides statistical information on a particular aspect of the CSS, for example “Top 10 selectors by length” and “Number of unique colors”. 

The CSS Audit tool is here on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. It can be installed locally to generate reports on any collection of CSS files.

The online repo tracks commits to wp-adminadmin (and super admin) CSS each day, regenerating the report if anything has changed. The most recent report can be seen at

Why we made it

There are many possibilities for reducing complexity in the wp-admin CSS codebase. The CSS Audit tool provides a big-picture view of those areas in need.

Each audit generally addresses a particular aspect where improvements could be made, for example “Number of times `!important` is used” and “Top 10 selectors with the highest specificity” allowing the health of the CSS code-base to be tracked over time. 

Audits can also expose CSS values which deviate from standards established by design, a feature used recently to limit core CSS color values to the official WordPress core color palette. The result was a >50% reduction in the number of individually defined colors!

This improvement was directly informed by the results of the CSS Audit. The same approach can be used to reduce complexity in other CSS rules, for example font-size which currently has 404 unique values specified.

Getting complexity under control and minimizing redundancy will pave the way for streamlining  and modernizing the CSS architecture, for example: using custom properties for theming.

How it works

The CSS Audit tool is a command line Node.js tool. Internally it uses PostCSS to analyze a set of CSS files and output the results in a user-configured format.

Reports can be generated as human-friendly HTML, machine-friendly JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., or tables printed to the command line output. 

For full instructions see the README file.

Thanks to @ryelle, @danfarrow, @notlaura, and @isabel_brison for their work on devising and implementing the CSS Audit Tool, and for reviewing and contributing to this post!

#core-css, #css-audit