Customize Design System
Learn how to enable the alt theme (dark mode), customize the current theme, and to create a new theme entirely

Objectives

In this guide we will cover the following:

  • Understand the library structure
  • Changing the default theme
  • Activating the alt theme (dark mode)
  • Customizing the existing theme
  • Create a new theme entirely

Library Structure

The concept that is followed within Nile Dashboard is simple, all modifications are made through sass variables, below we will list files and directories related to customizing Nile Dashboard in terms of theming.

  • folder acme-dashboard
    • folder library
      • folder extend
        • folder components
        • folder themes
          • description _dark-cerulean.scss
          • description _light-cerulean.scss
          • description _themes.scss
        • description _bootstrap.scss
        • description _globals.js
        • description _palette.scss
        • description _theme.scss
        • description _utilities.scss
      • folder sass
        • folder config
          • folder themes
            • description _dark-cerulean.scss
            • description _light-cerulean.scss
            • description _themes.scss
          • description _bootstrap.scss
          • description _globals.scss
          • description _palette.scss
          • description _theme.scss
          • description _utilities.scss

In the previous structure, the directory colored green extend is the only valid place to add customizations, whereas the directory colored red sass, is the actual source of truth (defaults) of Nile Dashboard, which can be used as a reference for the available variables that can be customized.

lets look at an example, if you want to customize an option within the _utilities.scss file, first you will write your modifications at /library/extend/_utilities.scss, that file by default looks like this:

@forward "@library/sass/config/utilities"

It forwards the default values from the actual source of truth, the new Sass Modules System allows us to customize the defaults as follows:

@forward "@library/sass/config/utilities" with (
  $dx-init-theme-colors: true
)

That concept will be used for customizing the entire theme, except for bootstrap because bootstrap is not yet updated to work with the new Sass Modules system.

Change default theme

Nile Dashboard comes with two themes light-cerulean and dark-cerulean, the default configuration is that the light theme is the primary (default) theme, whereas the dark theme is the alternative theme (alt).

In this section of the guide, we will change the default theme to be dark-cerulean instead of light-cerulean. The place we should be editing is /library/extend/_theme.scss, by default it looks like this:

// @library/extend/_theme.scss
@forward "@library/sass/config/theme"

If we look at the contents of the forwarded file, we will see a variable called $themes, that is of type map, and defines each, the default and alt themes, like so:

// @library/sass/config/_theme.scss
$themes: (
    default: 'light-cerulean',
    alt: 'dark-cerulean',
) !default;

That means we can modify that variable in our _theme.scss within the extend directory, as follows:

// @library/extend/_theme.scss
@forward "@library/sass/config/theme" with (
  $themes: (
    default: 'dark-cerulean'
  )
);

We have defined the default theme to be dark-cerulean, saving that file and looking at the result of the browser, your dark theme should now be the default.

Activate dark mode

Dark mode in Nile Dashboard is refereed to as the alt theme, In the previous section, we mentioned how to make the dark theme as the default, in this section, instead of doing that, we will leave the default themes as it was, and we will modify our @library/extend/_theme.scss with the following variable:

// @library/extend/_theme.scss
@forward "@library/sass/config/theme" with (
  $init-alt-theme: true
);

The $init-alt-theme variable when set to true, will add to the final CSS bundle all related coloring of the alt theme, so that now switching between the default and alt themes is as easy as adding a class named alt to our html tag.

Customize existing theme

Nile Dashboard follows a design system, that system outlines certain rules to follow in terms of text colors, shades, shadows and so on, each theme made within Nile Dashboard should configure these options to be considered a valid theme.

Lets take a look on how to change the primary color of the theme, since we know that light-cerulean is the default theme, then the target file we should edit will be @library/extend/themes/_light-cerulean.scss, by default that file contains the following:

// @library/extend/themes/_light-cerulean.scss
@forward "@library/sass/config/themes/light-cerulean" with (
  $overwrite: (),
  $extend: ()
);

Before we start adding our own options, lets first explain the difference between the $overwrite and $extend variables, basically, if we want to overwrite an existing variable within the theme config, for example, if we wanted to entirely replace the variants map, we can use the $overwrite as follows:

// @library/extend/themes/_light-cerulean.scss
@use "@library/sass/modules/palette";
@use "@library/extend/palette" as palette-config;

@forward "@library/sass/config/themes/light-cerulean" with (
    $overwrite: (
        variants: (
            success: palette.get-level(palette-config.$dx-green, 600),
            warning: palette.get-level(palette-config.$dx-amber, 800)
        ),
    ),
    $extend: ()
);

The previous configuration will replace all variants with just success and warning, so the danger variant for example is not available anymore, whereas, if we wanted to merge/add a new variant with the existing variants, we could then use the $extend variable as follows:

// @library/extend/themes/_light-cerulean.scss
@use "@library/sass/modules/palette";
@use "@library/extend/palette" as palette-config;

@forward "@library/sass/config/themes/light-cerulean" with (
    $overwrite: (),
    $extend: (
        variants: (
            custom: palette.get-level(palette-config.$dx-brown, 500),
        ),
    )
);

With the previous configuration, we now have added a brand new variant named custom to our theme, that way, we can now use it everywhere, for example with buttons <button class="btn btn-custom">.

Now, for our primary task for this section, we wanted to change the primary color, along with that, we also want to change background color, we can do so as follows:

// @library/extend/themes/_light-cerulean.scss
@use "@library/sass/modules/palette";
@use "@library/extend/palette" as palette-config;

@forward "@library/sass/config/themes/light-cerulean" with (
    $overwrite: (
        primary: palette.get-with-contrasts(palette-config.$dx-red, 500),
    ),
    $extend: (
        properties: (
            main-background-color: #EFEFEF,
        )
    )
);

The previous configuration, will change the primary color to red-500 instead of cerulean-500 as well as the background color.

You can always refer to the forwarded configuration file, which is @library/sass/config/themes/_light-cerulean.scss for a full reference of the available options and maps, that you can customize in order to make the dashboard truly unique to your project.

Be cautious, when extending the existing theme, as you have to follow the same behaviour, in terms of the functions used, for example, in order to access the palette system, you will have to use the palette module as seen in the previous examples, that module exposes functions such as palette.get-with-contrasts($palette) or palette.get-level($palette, 500).

Create a new theme

In this section of the guide, we will walk through the steps needed in order to create a new theme, the steps are as follows:

  • Create a new configuration file named _custom.scss for our new theme at @library/extend/themes.
  • Copy the configuration of one of the existing themes for reference from @library/sass/config/themes.
  • Override the themes map by registering our newly added theme within the themes configuration file at @library/extend/themes/_themes.scss.
  • Activate our new theme as the default theme.

Below is how our custom theme configuration should look like (omitted for brevity)

// @library/extend/themes/_custom.scss
@use "sass:map";
@use "@library/sass/modules/palette";
@use "@library/extend/palette" as palette-config;

$overwrite: () !default;
$extend: () !default;
$config: (
  primary: palette.get-with-contrasts(palette-config.$dx-red, 500),
  variants: ( ... ),
  colors: ( ... ),
  color-tunings: ( ... ),
  properties: ( ... ),
) !default;

Once you have configured the entire theme configuration with your own colors and options, its time to register the theme, this can be done by overwriting the themes map within @library/extend/themes/_themes.scss, that file, by default, looks as follows:

// @library/extend/themes/_themes.scss
@forward "@library/sass/config/themes/themes";

Take a copy of the contents of the forwarded file, and replace light-cerulean and dark-cerulean with our new custom theme:

// @library/extend/themes/_themes.scss
@use '@library/sass/modules/map';
@use '@library/extend/themes/custom';

@forward "@library/sass/config/themes/themes" with (
  $presets: (
    custom: map.overwrite-and-merge(custom.$config, custom.$overwrite, custom.$extend)
  )
);

The highlighted custom property key, is the name of our theme, now to the final step, activating the custom theme as the default, as mentioned previously, we can do that by configuring @library/extend/_theme.scss with the following:

// @library/extend/_theme.scss
@forward "@library/sass/config/theme" with (
  $themes: (
    default: 'custom'
  )
);

Our new custom theme will now be the default theme!

Next Up

Learn how to customize components using sass variables
Learn how to customize bootstrap by adding unique utility classes or changing the default breakpoints

{title}