Adding Custom UI Themes to WordPress Admin Using Sass

With the release of WordPress 3.8 we now have a new feature for Admin UI themes. This means that every user can change the color scheme of his admin regardless of the the theme that’s being used on the front-end. To change the color scheme of your admin, go to Users > Your Profile.

Here you’ll see eight predefined themes that you can select from. Select any theme from these themes and you’ll see the changes immediately. When you are done with selecting the theme, hit the “Update Profile” button.

But that’s not it - what if you want to add your own custom color scheme to the admin? We will look at that in this tutorial.

Note: You need to have Ruby and Sass installed on your system to follow this tutorial. You can find more instructions on how to install Ruby and Sass here.

Basic File Structure:

We will make our own plugin in order to add more color schemes to the admin UI. This way, we will be conforming with the WordPress standards to not to mix the presentation with the functionality.

So let’s get to our plugins folder and make a new directory called “admin-color-themes”. In that directory, make three more directories for our styles, images and javascript. We will also create an wordpress-admin-themes.php file and add the following code:

<?php
/**
 * Plugin Name: WordPress Admin Themes
 * Plugin URI: http://imbilal.com
 * Description: A little plugin to add your own color schemes to WordPress.
 * Version: 1.0
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 * License: GPL2
 */

Now that we have built the necessary file structure, we will start adding styles for our new UI schemes.

Copying Necessary Files:

There are two steps involving when preparing custom color schemes to add in your admin:

Making the stylesheet of the color scheme
Registering it with WordPress so it appears on your User Profile page

WordPress 3.8 uses Sass files to manage the color schemes. These Sass files are located in wp-admin > css > colors. Going in this directory, you will find three Sass files:

_variables.scss
_mixins.scss
_admin.scss

You will also notice that the predefined color schemes also reside in the same directory.

These Sass files contain necessary mixins and variables that we can reuse to define our own styles. So copy over these three files to plugins > admin-color-themes > css.

We also need some base styles that WordPress uses for its admin. We can find these styles in wp-admin > css naming colors.css and colors-rtl.css. As the name implies, the later one is for Right-to-Left languages. Copy these two files into plugins > admin-color-themes > css.

Now that we have copied the necessary files, we are ready to customize them to add custom UI themes to the admin.

Customizing Sass Files:

Go to your plugins > admin-color-themes > css folder and open the following Sass files using your code editor:

_variables.scss
_mixins.scss
_admin.scss

Here’s what each of these files do:

_variables.scss contains Sass variables for various properties like text color, base color, highlight color and notification color etc. We can modify these properties here by changing the values of their respective variables.
_mixins.scss contains a mixin for creating 3d button effect based on the base-color we define in our _variables.scss file.
_admin.scss contains styles for various elements and their interaction states. It also imports _variables.scss and _mixin.scss files. It’s here that all those styles are applied to the elements that we defined in our variables and mixins files.

We need to create two more files named color-scheme.scss and color-scheme-rtl.scss in the css folder. In the color-scheme.scss add the following code:

@import 'colors.css';
@import 'admin';

While in color-scheme-rtl.scss, we will include styles for rtl support:

@import 'colors-rtl.css';
@import 'admin';

Note that we don’t need to specify the extension of the `.scss` file. Also, we have referenced the file using admin instead of _admin because it’s a partial. If you need to learn more about Sass `@import` and partials, you can read about each of them in the Sass documentation.

So, as you can see, we will generate two files for any color scheme. One will serve for Left-to-Right languages while the other will serve the other if Right-to-Left locale is detected.

Now open up _variable.scss and start replacing the variable values. The variable names are quite self descriptive so we won’t have any problem customizing them. Change the values as shown below:

$text-color: #fff !default;
$base-color: #314029 !default;
$highlight-color: #CCBC39 !default;
$notification-color: #4D5C2E !default;
$link: #8F9137 !default;

In the console, navigate to the css folder inside admin-color-themes and type the following command:

sass color-scheme.scss forest-afternoon.css

sass color-scheme-rtl.scss forest-afternoon-rtl.css

Here, we have generated two css files named forest-afternoon.css and forest-afternoon-rtl.css. We can open these files and see that Sass have merged _variables.scss, _mixins.scss and _admin.scss into one file. These newly generated css files are using the normal css @import rule for importing the colors.css and colors-rtl.css files.

Now, w need to register these stylesheets with WordPress so they appear as an option on the User Profile page.

Registering Stylesheets with WordPress

In the index.php we will first define a constant for path:

define( 'PATH', plugins_url( '', __FILE__ ) );

Now we will define a function that will execute every time a user access the admin:

function add_custom_admin_themes() {
}
add_action( 'admin_init', 'add_custom_admin_themes' );

Inside the add_custom_admin_themes function, we will register our newly generated styles using the wp_admin_css_color function:

wp_admin_css_color(
	'forest-afternoon',
	__( 'Forest Afternoon' ),
	PATH . "/css/forest-afternoon.css",
	array( '#421F22', '#FFC042', '#114F3F' )
);

The `wp_admin_css_color` accepts five parameters for key, name, URL, colors and icon colors. The first three of them are required and the other two are optional.

These parameters are defined below:

A key is the unique key of the theme. No two themes can have the same key.
The name is what appears on the profile page/
The URL is the path to the stylesheet.
Colors refers to an array of color hex values. It’s used to give users a feel about the theme.

We also need to take in account the support for RTL. So on the top of the function declaration add the following code:

$suffix = is_rtl() ? '-rtl' : '';

And change the path parameter in the wp_admin_css_color function call to the following:

PATH . "/css/forest-afternoon$suffix.css",

This bit will check if the current locale is a right-to-left language. If so, the stylesheet with –rtl suffix will be loaded.

The final code should be something like this:

define( 'PATH', plugins_url( '', __FILE__ ) );

function add_custom_admin_themes() {
	$suffix = is_rtl() ? '-rtl' : '';

	wp_admin_css_color(
	    'forest-afternoon',
	    __( 'Forest Afternoon' ),
	    PATH . "/css/forest-afternoon$suffix.css",
	    array( '#421F22', '#FFC042', '#114F3F' )
	);
}
add_action( 'admin_init', 'add_custom_admin_themes' );

At this point, we have successfully registered the new admin style, we can check it by going to Users > Your Profile (be sure to activate the plugin first):

Activate the new style by selecting it and hitting the Update Profile button.

You can create as many styles as you want by just altering the values in the _variables.scss file and then registering them in your index.php. You can quickly grab some great color schemes using Adobe Kuler. The theme we used in this tutorial is Forest Afternoon.

You can download the completed plugin here.

Conclusion

In this tutorial we looked at how we can create and add some more color schemes to the WordPress admin using Sass preprocessor.

If you want to learn more about Sass, below are the resources:

HIGHLIGHTS OF THE DAY