I love comments in code. There’s probably nothing I hate more than looking through a WordPress theme/plugin and not being able to figure out what’s going on. When it comes to CSS, having loads of comments is problematic because it’s best to keep these files lightweight to speed up page load time.

I want the best of both worlds though.

WordPress has a built-in way to handle development files vs. production files for core. However, this is not extended to theme development. But, we can use the same technique to handle our theme’s style.css file.

I know there are plugins that compress CSS and do all kinds of nifty things to speed up page load times. But, as theme developers, we shouldn’t tell users to go use another plugin. Let’s provide a solution that works out of the box and educate them. This solution is also extremely child theme friendly. If your users aren’t using child themes, they’re probably going to be confused when editing a compressed style.css file.

Turning on stylesheet debugging

To use this method, you must turn script debugging on in your WordPress install. Don’t do this on your live site. It’s only for your development install.

Open your wp-config.php file and add this line of code:

define( 'SCRIPT_DEBUG', true );

Adding the stylesheet filter

To make use of a development stylesheet, you have to add a filter to stylesheet_uri. Add this PHP code to your theme’s functions.php file:

add_filter( 'stylesheet_uri', 'my_debug_stylesheet', 10, 2 );

function my_debug_stylesheet( $stylesheet_uri, $stylesheet_dir_uri ) {

	if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) {
		$stylesheet = str_replace( trailingslashit( $stylesheet_dir_uri ), '', $stylesheet_uri );
		$stylesheet = str_replace( '.css', '.dev.css', $stylesheet );

		if ( file_exists( trailingslashit( STYLESHEETPATH ) . $stylesheet ) )
			$stylesheet_uri = trailingslashit( $stylesheet_dir_uri ) . $stylesheet;
	}

	return $stylesheet_uri;
}

This code will check if SCRIPT_DEBUG is turned on and if a style.dev.css file exists in your theme. If the file does exist, it will be loaded instead of your style.css file.

Creating development stylesheets

Now, that you’ve set up your theme, it’s time to take advantage of development stylesheets. All WordPress themes come packaged with a style.css file. This system comes with two:

• style.css: For live use on the site.
• style.dev.css: For use in development environments.

Rather than building our theme design inside of the normal style.css file, we’re going to do it all in the style.dev.css file. This will allow us to leave plenty of notes and comments. This file could even be as large as 50kb because it won’t be used live.

So, the first step in using this is copy over all your normal style.css code into your style.dev.css file. Do all of your code work in this file.

When it’s time to package the work up for public download, copy the contents of the style.dev.css file and transfer it over to style.css. Then, compress the contents of style.css, leaving the normal theme information untouched. The final code would look something like the below.

/**
 * Theme Name: Example
 * Theme URI: http://example.com
 * Description: A description of your theme.
 * Version: 0.1
 * Author: Your Name
 * Author URI: http://example.com
 * Tags: theme-options, threaded-comments
 */

html,body,div,span,object,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,samp,small,strong,sub,sup,tt,var,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;vertical-align:baseline;outline:none;font-size:100%;background:transparent;border:none;text-decoration:none}

CSS compression tools

You don’t have to worry about compressing CSS files manually. There are tools around the Web that do this for you. Here’s a list of some compressors:

• CSS Drive: CSS Compressor (my favorite)
• CSS Compressor
• Clean CSS

Feel free to link to or let us know in the comments if you have any CSS compression tools that you like in particular.

What makes this child-theme friendly?

A theme’s style.css file is typically the first thing a user will hack to bits. That’s just the way it goes. This would be a major problem if users wanted to do this and the style.css file was compressed. Telling them about SCRIPT_DEBUG might also be an issue.

You, as a theme developer, should be promoting the use of child themes.

Rather than having your users editing the parent theme’s style.css file, they should be importing it into their child theme’s style.css like so:

@import( '../parent-theme/style.css' );

From there, they can overwrite any style rules they want.

Rather than calling this “child-theme friendly,” I should probably say that it’s a way to educate users on the benefits of using a child theme. So, the first time a user asks why their child theme’s style.css is unreadable, you can point them to one of the great tutorials around the Web on how to use child themes.