diff --git a/README.md b/README.md index 09e7116..5c99aa4 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,98 @@ # CSS Audit -This project contains an automated audit of the core WordPress CSS, including the number of distinct colors used, most specific selectors, how many properties use `!important`, and more. [View the audit report here.](https://wordpress.github.io/css-audit/public/wp-admin) This report is regenerated every day at 09:00 UTC, and runs over the latest CSS in [WordPress/wordpress-develop](https://github.com/WordPress/wordpress-develop/). +An automated auditing tool specifically designed for **WordPress Core CSS**. It tracks design consistency, code quality, and performance metrics across `wp-admin` and `wp-includes`, helping the Core CSS team, designers, and contributors manage technical debt. -To generate this report, there is a tool `css-audit`, which runs a set of [audits](./src/audits). +This tool powers the [daily automated audit report](https://wordpress.github.io/css-audit/public/wp-admin) for `wp-admin`, which runs against the latest code in `trunk` from [WordPress/wordpress-develop](https://github.com/WordPress/wordpress-develop/). -## Local Environment +## 🎯 Purpose +WordPress has a large and long-lived CSS codebase that has evolved over nearly two decades. This tool helps to support: -To run the audits yourself, download or clone this repo, then install the dependencies. You will need [node & npm](https://nodejs.org/en/) installed. +* **Tracking CSS Evolution**: Monitoring how WordPress Core CSS metrics change between versions. +* **Managing Regressions**: Identifying potential spikes in `!important` usage, color definition proliferation, or selector specificity in `wp-admin` and `wp-includes`. +* **Design Consistency**: Promoting visual cohesion in the admin interface as new features are added. +* **Performance & Health**: Highlighting hidden styles (`display: none`), excessive selector nesting, and opportunities to refactor legacy CSS. +## 👥 Who This Tool Is For + +* **WordPress Core Contributors**: To check if new CSS changes introduce regressions or unnecessary complexity. +* **Design & Accessibility Teams**: To evaluate the usage of colors, font sizes, and layout properties, which supports evaluation related to accessibility and the WordPress Design System. +* **Release Leads**: To review CSS statistics. + + +## 🛠️ Installation + +To run the audits locally, clone this repository and install dependencies. You will need [Node.js](https://nodejs.org/en/) and `npm`. + +```bash +git clone git@github.com:wordpress/css-audit.git +cd css-audit +npm install ``` -$ git clone git@github.com:wordpress/css-audit.git -$ cd css-audit -$ npm install -$ npm run css-audit -- + +## 📥 Fetching WordPress Core CSS + +Before running an audit, you need CSS files to analyze. You can download these directly from the official WordPress Subversion (SVN) repository. + +> **Note:** WordPress 6.4 is used as an example below. Check [wordpress.org/download/releases](https://wordpress.org/download/releases/) for available versions. + +### Option A: Audit a Specific Version (e.g., WordPress 6.4) +Use this to audit a released version or specific branch. + +```bash +mkdir wp-6.4 +# Download wp-admin CSS +svn export https://develop.svn.wordpress.org/branches/6.4/src/wp-admin/css --depth files wp-6.4/admin +# Download wp-includes CSS +svn export https://develop.svn.wordpress.org/branches/6.4/src/wp-includes/css --depth files wp-6.4/includes +``` + +### Option B: Audit `trunk` (Development) +Use this to audit the latest code currently in development. + +```bash +mkdir trunk +# Download wp-admin CSS from trunk +svn export https://develop.svn.wordpress.org/trunk/src/wp-admin/css --depth files trunk/admin +# Download wp-includes CSS from trunk +svn export https://develop.svn.wordpress.org/trunk/src/wp-includes/css --depth files trunk/includes ``` -If you want to work on the audits yourself, [fork this repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) to your account first. You can submit issues or PRs. +> **Note:** WordPress splits CSS into `wp-admin` (Dashboard, editor) and `wp-includes` (frontend blocks, admin bar). We recommend downloading both for a complete audit. + +## 🚀 Running Audits -## Running Audits +Once you have the CSS files, you can run the audit tool. -To run the audits, you need a list of CSS files, and to indicate which audits you want to run. `yarn` and `npm` both automatically expand globs (`folder/*`), so you can use that, or pass in a list of CSS files. The audits are described below, and can be run via the following CLI args, or via configuration file (described in the next section). +```bash +# General usage +npm run css-audit -- [options] +# Example: Audit the downloaded 6.4 files +npm run css-audit -- wp-6.4/**/* --recommended ``` -$ npm run css-audit -- [options] -Usage: css-audit -- [options] +### Options +``` --colors Run colors audit. --important Run !important audit. --display-none Run display: none audit. --selectors Run selectors audit. --media-queries Run media queries audit. +--typography Run typography audit. --property-values Run audit for a given set of property values, comma-separated. --recommended Run recommended audits (colors, important, selectors). Default: true. ---all Run all audits (except property values, as it requires a value). ---format Format to use for displaying report. ---filename If using a format that outputs to a file, specify the file name. +--all Run all audits (except property values). +--format Format to use for displaying report (json, html). +--filename Specify the output filename. --help Show this message. ``` - ### Configuration File -The program will prioritize configuration from CLI arguments, and will fallback to configuration stored in a file called `css-audit.config.js`. +The tool prioritizes CLI arguments but falls back to `css-audit.config.js` if present. -``` +```javascript module.exports = { format: 'json', audits: [ @@ -59,41 +107,16 @@ module.exports = { }; ``` -## Generating HTML Reports +## 📊 Generating HTML Reports -To generate an HTML report, use the `--format=html` option and specify a name for the file with the `--filename=name` option. This will output a `{name}.html` file in public/ that is viewable on Github Pages. +To generate a visual HTML report (like the one hosted on GitHub Pages), use the `--format=html` option. -For example, generating a report for wp-admin using the below strategy for pulling down CSS files from SVN: - -``` -npm run css-audit -- v5.5/**/* --format=html --all --filename=wp-admin +```bash +# Generate report for wp-admin from trunk +npm run css-audit -- trunk/admin/* --format=html --all --filename=wp-admin-report ``` -In the configuration file, the argument `filename` can be added as a simple property: value combination, the same as `format` in the example. See the [default `css-audit.config.js`](./css-audit.config.js). - -## Getting core CSS files - -You can download the source files of CSS (not minified or RTL'd) from the svn repository. The following code will create a new directory, `v5.5`, and download just the files from each `css` folder. - -``` -mkdir v5.5 -svn export https://develop.svn.wordpress.org/branches/5.5/src/wp-admin/css --depth files v5.5/admin -svn export https://develop.svn.wordpress.org/branches/5.5/src/wp-includes/css --depth files v5.5/includes -``` - -If you want to run this on trunk (code currently in development), you can swap out `branches/5.5` for `trunk`. You could also swap the `5.5` for `5.4`, etc. Example: - -``` -mkdir trunk -svn export https://develop.svn.wordpress.org/trunk/src/wp-admin/css --depth files trunk/admin -svn export https://develop.svn.wordpress.org/trunk/src/wp-includes/css --depth files trunk/includes -``` - -Now you can run the audits: - -``` -npm run css-audit -- v5.5/**/* --recommended -``` +This will output a `wp-admin-report.html` file in the `public/` directory. ## Available Audits @@ -120,7 +143,41 @@ npm run css-audit -- v5.5/**/* --recommended - Number of times `display: none` is used - Places where `display: none` is used - `typography` - - A collection of information about various typography-related properties + - Number of unique font sizes + - Number of unique font families + - Number of unique font weights + - Number of unique line heights + - Top 10 most-used font sizes + - Top 10 most-used font families + - Top 10 most-used font weights + - Top 10 most-used line heights + +## Contributing + +This project follows WordPress coding standards and contribution guidelines. We welcome contributions from the community! + +### Getting Started + +Please refer to the [WordPress Developer Resources](https://developer.wordpress.org/) and [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/). +You can also join the [#core-css channel](https://wordpress.slack.com/archives/C02RP4T41) on [WordPress Slack](https://make.wordpress.org/chat/). + +### Development + +1. Fork and clone the repository. +2. Run `npm install`. +3. Run `npm test` to execute tests. +4. Run `npm run lint:js` and `npm run format:js` to check and format code. + +If you find a bug, please [open an issue](https://github.com/WordPress/css-audit/issues) on GitHub. + +## WordPress Resources + +- [WordPress Core Repository](https://github.com/WordPress/wordpress-develop/) +- [WordPress Core Handbook](https://make.wordpress.org/core/handbook/) +- [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/) +- [WordPress Design Handbook](https://make.wordpress.org/design/handbook/) +- [WordPress Core CSS Trac](https://core.trac.wordpress.org/query?component=CSS) - Track CSS-related tickets +- [Make WordPress Core Blog](https://make.wordpress.org/core/) - Stay updated on WordPress development ## Technical details @@ -129,3 +186,9 @@ This tool parses each CSS file and creates an AST, which the audits traverse to - [PostCSS API documentation](https://postcss.org/api/) - [csstree documentation](https://github.com/csstree/csstree/tree/master/docs) - [AST Explorer](https://astexplorer.net/) — great tool for identifying how the CSS is parsed. + +## License + +This project is licensed under GPL-2.0-or-later, consistent with WordPress core licensing. + +