Creating a Custom UIkit Theme with Gulp and Less

Everyone wants to be unique. I guess you won’t be super happy if in your surroundings there are many people looking just like you, right? This holds true for the other people too. Your friends also won’t be happy to see clones of you everywhere. The same is true for our websites.

Nowadays, building a website with a front-end framework is common. The problem though is that many people blame such frameworks for making all websites “look the same”. But the tool isn’t to blame if developers aren’t willing to make the necessary customizations.

For those of you who want the websites you build to stand out from the crowd, I’ll demonstrate how you can use UIkit’s Customizer to create different themes and theme variations (styles). The process is straightforward, but you need a proper workflow to do it with a minimum amount of headache.

Setting Up Customization

Let’s say that you want to create a dark theme for your website with orange as an accent color. Also, you want two more variations of that theme with blue and green accent colors. Let’s see how we can do it. (Note: For the sake of brevity, I’ll use only buttons to demonstrate the process).

We’ll need to start with ensuring the following steps are complete:

• Download or clone the UIkit repository.
• Install Node and Gulp, if you don’t have them already.
• Install UIkit’s development dependencies. You can do this by navigating to the UIkit root directory and running npm install from the terminal.

When all of this is set up correctly, we can start creating our theme.

Creating our Theme

Still in the root directory, create a folder called “custom”. In that folder, create another one called “dark” and inside it create a file called uikit.less. Open the file and add the following:

@import "../../src/less/uikit.less";
@import "button.less";

The first line will get all Less files from the core framework and the second line will import the file you’re going to use to modify the default UIkit buttons. Save and close the file and create the aforementioned button.less file in the same directory.

Before making any further customizations, you need to make your theme available locally in the Customizer. To do so, in the UIkit root directory, run the following in the terminal:

gulp indexthemes

Now launch your local copy of the UIkit website (the one you installed) and click “Customizer” in the navigation bar. When you open the “Select a theme” drop-down list you should see “Dark” at the end of it. At this point, when you select it, you’ll see that there is no styling. Why not? Let’s see.

One thing not mentioned in UIkit’s documentation and which can cost you a lot of headache, is that your theme needs a file called uikit-customizer.less. Create the file and add the following line:

@import "uikit.less"

You must put that file, with the above line, in the theme’s root directory (inside the “dark” folder, in our case). If this file is not present, you can’t use the Customizer properly – the theme’s name will appear in the list, but the styles will be missing.

Note: As a rule of thumb, the uikit-customizer.less file should import all files that your theme uses. In our example, importing uikit.less meets this requirement because it includes both the default UIkit styles and your custom button styles.

After adding the uikit-customizer.less file, you will see that this time all components are properly styled. So, we’re ready to move on.

In the component’s drop-down list, placed at the top left corner of the panel on the right side of the Customizer, switch to “Button”. This way you’ll be able to see all available button styles. Now we can open the button.less file and start adding our modifications:

@button-color: #f90;
@button-hover-color: fade(@button-color, 75%);
@button-active-color: @button-color;

@button-background: #000;
@button-hover-background: lighten(@button-background, 20%);
@button-active-background: @button-hover-background;

In the above code we’ve modified the variables for the default button’s text and background colors in their normal, hovered, and active states. For other specific buttons, we need to change those variables too:

@button-primary-color: darken(@button-primary-background, 20%);
@button-success-color: darken(@button-success-background, 20%);
@button-danger-color: darken(@button-danger-background, 20%);

@button-primary-hover-color: fade(@button-primary-color, 75%);
@button-success-hover-color: fade(@button-success-color, 75%);
@button-danger-hover-color: fade(@button-danger-color, 75%);

@button-primary-active-color: lighten(@button-primary-color, 35%);
@button-success-active-color: lighten(@button-success-color, 35%);
@button-danger-active-color: lighten(@button-danger-color, 35%);

Using Hooks in UIkit

Modifying UIkit’s variables is the easiest way to change the appearance of the framework’s components when dealing with simple modifications. But for more complex customizations, such as adding new rules and/or changing the existing ones without breaking the core, UIkit provides a special mechanism. It uses hooks to safely append your changes. Let’s see this in action. Put the following code below the variables, inside the button.less file:

.hook-button() {
  border-radius: 5px 15px; 
  box-shadow: 2px 2px;
}

Here, the hook for the button component is used to add a border radius and a drop-shadow effect.

For even more specific changes, UIkit provides miscellaneous hooks. Each component has such a hook. This is useful for creating new selectors or modifying the ones that have neither a variable nor a hook available for customization. Let’s demonstrate this by adding the following code:

.hook-button-misc() {
  .uk-button:active:not(:disabled) { 
    box-shadow: none; 
  }
  .uk-button-link:hover,
  .uk-button-link:focus,
  .uk-button-link:active,
  .uk-button-link.uk-active {
    text-decoration: none;
  }
  .uk-button-link:focus { 
    outline: none; 
    border: 1px solid @button-link-hover-color;
  }
}

Here we remove the drop-shadow for every active button that is not disabled. Then we remove the underline of links in all states. Finally, we remove the outline of the button link and instead add a nice border, shown when the link is focused. Save the button.less file.

Note: You can see all available hooks for a particular component by looking at the very end of its corresponding .less file. Here is an example for the button component.

// Hooks

.hook-button-misc;

.hook-button() {}
.hook-button-hover() {}
.hook-button-active() {}
.hook-button-primary() {}
.hook-button-primary-hover() {}
.hook-button-primary-active() {}
.hook-button-success() {}
.hook-button-success-hover() {}
.hook-button-success-active() {}
.hook-button-danger() {}
.hook-button-danger-hover() {}
.hook-button-danger-active() {}
.hook-button-disable() {}
.hook-button-link() {}
.hook-button-large() {}
.hook-button-misc() {}

So now the main theme is ready and you can check it out in the Customizer. Just reload the page and enjoy.

Creating Styles for our Theme

Now we’re ready to create the theme’s styles. In our dark theme’s directory, we’ll create a new folder called “styles” and inside that we’ll create another one called “blue”. In that folder create a blank style.less file. Copy the first three lines of code from your button.less file and paste them into the file, then change the value of @button-color to #09f and save the file. The contents of the file will look like this:

@button-color: #09f;
@button-hover-color: fade(@button-color, 75%);
@button-active-color: @button-color;

Run gulp indexthemes in the terminal again to include the newly created style, then go back to the Customizer and refresh the page. Now at the end of the themes list you should see a “Dark-blue” option. Select it and you’ll see that now the buttons appear with a nice blue accent. For the green style, repeat the same procedure but instead use a color value of #9c0.

When you’re satisfied with your theme you can build it by running this task:

gulp dist -t dark

This will build the dark theme and will put it in a “dist” folder in the UIkit root directory. Then, in the “css” folder you’ll find uikit.dark.css and uikit.dark.min.css files. Unfortunately, these files contain only styles from your main theme. The blue and green styles are not included. But you can get the CSS files for those too by using the GUI Customizer, as I’ll explain next.

Using the GUI Customizer

I showed you how to create a theme manually, because it’s always good to know the underlying mechanism of a particular process. But if you don’t need complex modifications, you can use the GUI Customizer directly. Let’s explore the needed steps.

• Go to Customizer and select the theme you want to customize.
• Use the left panel to modify the variables. Usually, only the global variables are shown. For the components’ variables to be visible you need to activate the “Advanced Mode” option. By default, a variable whose values are defined through another variable are hidden. In advanced mode you can see a “(more)” button next to groups that include these kinds of variables.
• Make the changes you want and hit the “Get CSS” button. This will give you the final CSS file for your theme. You can use this button to get the CSS files for your blue and green styles. Just select “Dark-blue” or “Dark-green” and click the button.
  
  • If you want a minified version, check the “Minify CSS” option
  • If you use left-to-right languages, check “RTL Mode” and the whole theme will convert automatically.
• If you hit the “Get Less” button instead of the “Get CSS” button, the output file will contain only the changed variables. In this way you can create styles automatically when you create theme variations.

Every theme uses a customizer.json file defining which variables are displayed by default or only in advanced mode. By modifying this file, you can control the visibility and availability of the variables in the Customizer’s left panel. For more details on this, see the Customizer.json page.

Note: When you run the indexthemes task, if your theme doesn’t have its own customizer.json file (which is the case when you create a new theme), UIkit uses the file from the default theme (/themes/default/customizer.json). If you plan to customize this file, you need to copy and paste it in your theme’s root directory and run gulp indexthemes again to update the theme.

Conclusion

You saw that customizing a particular front-end framework is not as hard a task as it may seem at first. With some knowledge of Gulp and some extra effort you can make your websites unique enough to stand out from the crowd without being labeled as having been built with a specific framework.

Frequently Asked Questions on Custom UIkit Theme with Gulp & Less