Customizing the UI

Custom Branding and UI Design

Tags: 396 views 1

How to change the branding and UI design of the Atomia User Panel.

Overview

The Atomia User Panel markup and styles are architected to make it easy to do as many branding and design changes as possible by customizing and extending the default CSS. The reference guide for the Atomia User Panel styles is the Atomia Pattern Library. It is available at patternlibrary.atomia.com. This is a so called living pattern library, which means that the stylesheet that renders the reference site is the same that renders the Atomia User Panel NewDefault theme in a production installation of Atomia.

The styles are built on top of a component architecture similar to the popular BEM methodology, but with class naming conventions from SUIT CSS. This means that each component can be styled in isolation and that it is (ideally, and as far as possible) independent of any specific markup hierarchy. It also means that if you work within the established structure and defined components, your theme should be robust and maintainable when updates to the Atomia User Panel are released.

How Styles Are Loaded on the Page

All styles are loaded via two partial views under the <head> tag in the following order:

  1. Shared/_Fonts.ascx
  2. Shared/_Styles.ascx

Shared/_Fonts.ascx

Fonts are loaded in a separate partial view so that they can be changed without changing how the main style sheet is loaded.

Shared/_Styles.ascx

This is where the main style sheet is loaded. Only one style sheet is loaded, and the resolution is as follows:

  • If the current reseller has the CSS url reseller setting set, that style sheet will be used.
  • If the global setting cssMinifier in appConfig.config is set to true the style sheet at Themes/<current-active-theme-name>/Content/css/main.min.css is used.
  • Otherwise the style sheet at Themes/<current-active-theme-name>/Content/css/main.css is used.

Creating an Atomia Pattern Library Custom Theme

The best way of making a theme for the Atomia User Panel is to use the Theme Starter Kit from patternlibrary.atomia.com.

The Theme Starter Kit consist of the following main parts:

  • theme folder. This is where you write and maintain your own styles and style settings as Sass files.
  • .atomia folder with the latest NewDefault theme Sass files that form the basis of your theme. Do not change these files!
  • Gulpfile.js defines tasks you can use to compile and lint your theme CSS:
    • gulp lint checks your custom styles against Atomia’s CSS coding standard. Not mandatory, but useful!
    • gulp assets copies img and font folders from .atomia and .theme to publish/Content.
    • gulp styles compiles the theme Sass and places the unminified main.css and the minified main.min.css in publish/Content/css.
    • gulp clean removes any existing publish/Content.
    • gulp theme (or just gulp without an argument) combines the assets and styles tasks to compile and copy a complete theme style sheet and assets to publish/Content.

To start using the Theme Starter Kit follow the Quickstart guide on patternlibrary.atomia.com, or the following steps:

  1. Unzip your downloaded atomia-themestarter.zip
  2. On the command line cd into atomia-themestarter/themestarter
  3. Run npm install to install all development dependencies that are required to compile your new theme.
  4. Run npm install -g gulp to be able to use the gulp command unqualified. Otherwise you will need to use ./node_modules/.bin/gulp instead.
  5. Run gulp theme to compile the example theme.
  6. The compiled theme will now be available in publish/Content

You should now have a style sheet and related assets that you can use to as the Content folder in your custom theme. Continue to the following sections for instructions on how to make the theme fit your own branding and design needs.

Updating an Atomia Pattern Library Custom Theme

When there is an update released to the Atomia User Panel you might need to re-compile your custom theme to update it with any changes or bug fixes for existing components, or to get any new components included.

  1. Go to patternlibrary.atomia.com and download the latest Theme Starter Kit.
  2. Replace the .atomia folder in the folder where you are working with your custom theme styles with the updated .atomia folder from the download.
  3. Compile your theme following the instructions in Creating an Atomia Pattern Library Custom Theme.

Customization with Atomia Pattern Library Settings

The Theme Starter Kit download from patternlibrary.atomia.com contains the main theme style sheet entry point theme/css/theme.scss. This file is pre-filled with some settings that you can use to quickly customize a theme with logo, colors and fonts for branding.

These are just a few of the available Sass settings in the Atomia Pattern Library. There are many other global and component level settings for you to customize the look and feel of the Atomia User Panel. To change a setting do the following:

  1. Identify the component you want to change, e.g. by inspecting elements in Chrome Developer tools. Components are named according to the SUIT CSS naming convention, and each component is located in its own Sass file.
  2. Copy the component level setting, or if you want to change all uses of e.g. a color, the global setting to your theme/css/theme.scss file and set the value you want.
  3. Re-compile the theme by running gulp theme.

Reference locations of global settings:

  • .atomia/_settings.base.scss
  • .atomia/_settings.colors.scss
  • .atomia/_base.inputs
  • .atomia/_base.layout
  • .atomia/_base.table
  • .atomia/_base.typography

Component level settings are located in the .atomia/_component.*.scss files, one file per component.

Important!

Always copy over settings you want to change to your own theme.scss style sheet. If you change anything in .atomia/*.scss directly your changes will be overwritten when you update the theme with the latest changes from Atomia Pattern Library as described above in Updating an Atomia Pattern Library Custom Theme.

Using a Custom Font

The default Atomia Pattern Library theme uses the Open Sans font from Google Fonts. The custom font is included in the Shared/_Fonts.ascx partial view and then referenced by the $font-main, $font-forms and $font-title settings in the Sass style sheets.

The following is the recommended way of including and using another custom font:

  1. Override the Shared/_Fonts.ascx partial view to include the url of the new font and (if not using) remove the reference to Open Sans. To cover all uses for $font-main$ you should include a font with the 300, 400, and 700 weights.
  2. Set the $font-main, $font-forms, and $font-title variables in your theme/css/theme.scss file. Remember to set some fallback fonts in your font stack as well.

Important!

You will notice that the Theme Starter Kit imports an example font, Roboto, directly in the theme/css/theme.scss file. This is only for demonstration purposes so the theme can be compiled and used without changing any partial views. Importing a font like this will of course work in your custom themes as well, but the drawback is that you will unnecessarily make the user request Open Sans as well, and making the request to get your custom font will be delayed by parsing the main style sheet. So, for production use, always override Shared/_Fonts.ascx instead.

Customization with Selector Overrides

Sometimes you might want to make larger customizations to a component, or the thing you want to customize is not adequately covered by settings (if so, tell us!). Or you need some completely custom component that is not available in the standard Atomia Pattern Library. This is the time to bring out regular CSS selector overrides to get the job done.

Overriding styles via CSS selector overrides is of course a very unrestricted process. However, we recommend that you follow the following guidelines for a maintainable custom theme that takes advantage of and extends the Atomia Pattern Library in the best way possible:

  • Place your custom overrides after the @import ‘atomia’; rule in theme/css/themes.scss. This ensures that you can take advantage of variables and that your overrides are the last applied styles and will not be overridden by the Atomia Pattern Library styles.
  • Split your custom overrides into the same component files as the default styles. E.g. place overrides for atomia/css/_component.button.scss in theme/css/_custom.button.scss. Then @import these files into theme/css/themes.scss.
  • Take advantage of the gulp lint task to find any syntax errors and other problems in your custom Sass.

Was this helpful?

Related Articles