Learn About What Goes into a Theme

This applies to Kilimanjaro, but can also be applicable to older versions as long as you account for changes to module and file names. It is good advice for SuiteCommerce Advanced users, but a number of these suggestions are inappropriate for SuiteCommerce Standard users.

When it comes to designing or redesigning your site, we don't typically give a lot of advice on how to do this. This might be curious but in truth I have typically felt like there isn't much for us to say. After all, how your site looks is down to you and what Sass and templating changes you make is your business. We're here to tell you how to make your changes, not what changes to make.

Similarly, I've often considered the look-and-feel of a site to be the least nuanced aspect of building a SuiteCommerce Advanced site; in other words, it's arguably the part that is most like building a site on any other platform. What can we say about that?

However, after looking into the work that our development team are doing, preparing themes for the SMTs in SuiteCommerce Standard, I've learnt that there is indeed nuance to this, and there is information that we can share with you.

What is a Theme?

A theme is like the look and feel of a website: it's what people see when they visit. Changing your site's theme usually involves changing fonts, colors, spacing, positioning, sizing, etc. Themes typically avoid behavioral changes to functionality or the interface; that is, you avoid changes to JavaScript or SuiteScript unless absolutely necessary.

In some ways, a theme is different to simply redesigning your site: in a more nuanced sense, a theme represents something that can be transported from one site to another with minimal interoperability issues.

We include a base theme in the SuiteCommerce Advanced bundle. It's simple and clean so you would be forgiven for thinking that this is our 'unstyled' site version. Moving on from it, though, can be a daunting task: where do you start? What should you change? Well, they're some of the questions that I hope to answer in this post.

Key Areas of the Site

You can, of course, change any part of your site, but there are certain parts of it that typically require significant attention if you want to make them look your own:

  • BaseSassStyles — the core of your site's Sass, includes important variables for colors, fonts, sizes, etc
  • Header — the top of the page (header and navigation)
  • Footer — the bottom of the page
  • Home — the homepage
  • ProductDetails — the product detail page
  • Facets — the search results page
  • SiteSearch — the search box

Naturally, you may want to expand into other sections but you should start here.

I'm not going to take you through the entire process of creating a theme as this is a very labor-intensive process.

Module Prep

Naturally, you shouldn't edit our source files to make your changes. For Sass changes, the recommended approach is to override whole files: take the original file, copy it to a new directory, and then create an override for it.

Which 'new' directory you put it in is up to you, we typically recommend that you group all of your customization modules together in one parent directory. However, when it comes to your site's theme, you may want to keep that separate outside of this folder for easy access and for the fact that it'll likely contain multiple levels of sub-directories.

I'm going to start with some customization files I made as part of my blog post on the new automated style guide. If you don't already have them, here's a rundown.

  • Create Modules > custom_theme > CustomStyles@1.0.0 > Sass
  • In Sass, create _custom-colors.scss and then paste in the contents of suitecommerce > BaseSassStyles > Sass > variables > _colors.scss
  • In CustomStyles, create ns.package.json
  • Update distro.json:
    • Add "custom_theme/CustomStyles": "1.0.0" to the modules directory
    • Add CustomStyles to the dependencies arrays of shopping.css, myaccount.css, checkout.css

The ns.package.json file needs the following:

    "sass": ["Sass/**/*.scss"]
  "overrides": {
    "suitecommerce/BaseSassStyles@3.0.0/Sass/variables/_colors.scss": "Sass/_custom-colors.scss"

Save and deploy.

Changing Colors

Before we start, I should probably say I'm not an expert designer. The truth is, if you want a good looking site and you're not a designer, you're probably going to want to hire someone to take a look at it for you. However, with that said, let's take a look at color customizations.

We've already set up an override for the base colors file. We typically include two main colors: the primary color and the secondary color. The primary color is the primary accent for your site, used to highlight primary actions (eg add to cart buttons) and other important information. The secondary color is for less important actions and, with the way we have set up our Sass, we use it as the basis for your theme's color scheme.

With Sass, we are able to use variable names which means that drastic changes can be made quite quickly and consistently throughout the site. You can see this in _custom-colors.scss:

$sc-color-primary: #e23200;
$sc-color-secondary: #15607b;
$sc-color-theme-base: $sc-color-secondary;
$sc-color-theme-900: $sc-color-theme-base;
$sc-color-theme-400: desaturate(lighten($sc-color-theme-base, 45), 18);
$sc-color-theme-300: desaturate(lighten($sc-color-theme-base, 60), 22);
$sc-color-theme-200: desaturate(lighten($sc-color-theme-base, 68), 22);
$sc-color-theme-border: $sc-color-theme-400;
$sc-color-theme-border-light: $sc-color-theme-300;
$sc-color-theme-background: $sc-color-theme-200;

To see the effects of these variables in action, change the values of the primary and secondary colors. For example, if I change those to purple and yellow colors then the whole site look will change:

Note not only the changes to the obvious uses, such as the buttons, but note how the background hues towards purple. You can see that this is because we're using two features of the Sass language, desaturate and lighten, to change the colors' appearances.

Thus, choosing two important colors to run through your site is vitally important. As a business, you'll like already have a color scheme and so it becomes a process of simply plugging them in. If you don't, or if you want to differentiate your site, then there are plenty of tools out there that will help you find colors that work well together. For example, I had a lot of fun on Paletton.com.

To see how these colors are used throughout your site (that is, without just browsing) you can dive into some Sass files. For example, _buttons.scss is where we determine how the buttons on your site look. You'll notice the primary button uses the primary color variable for its background, and then uses some more fancy Sass to set the hover effects:

.button-primary {
    background: $sc-color-button-primary;
    border: 1px solid $sc-color-button-primary;

    &:hover {
        background: $sc-color-button-primary-hover;

$sc-color-button-primary-hover is a new variable and is set above this declaration in the file, along with all the other color variables we're going to use for the buttons. You can see that when it comes to setting the colors for it, we start by using the primary color variable and from then on we use the variable we just set. This not only makes it semantically more relevant, but it also means that if you ever want to disconnect the site's primary color from the color of primary buttons, then you only need to change one variable.

Another method to get to grips as to where your colors are being used is to grep for them. If you're using MacOS or Linux then you can change directory to your SCA folder and then do something like this:

grep -rnli "sc-color-primary" Modules

This will find every file that uses this variable. You can then look up functionality, eg the order history details page, and see how your change will affect the site. If you're using Windows then there's an equivalent CLI command for PowerShell, Select-String, although I can't advise on how to use it.


We have two Sass files named _typography.scss in BaseSassStyles: one in variables and the other in atoms. The former defines the sizes of fonts and the latter implements the variables (eg defining heading sizes).

If you take a look at the variables file, you'll see that in Kilimanjaro we moved over to using rem units to determine the size of text. After setting a base font size (eg 15px) you then use rem to determine various other font sizes relative to that base size.

We previously used em units, but they have a bit of an issue. When you produce complex functionality and styles to match, the relative nature of em units mean that their relativity cascades down, which means that getting the size you want can be tricky. While we want to maintain this relative nature, we wanted something that was more consistent.

By using rem units the relative nature of the units is determined by a base element in HTML, which is usually the html element. In our case, it is the html element and you can see this declaration in _reset.scss. Therefore, we essentially get the best of both worlds: non-static font sizes that are deterministic.

So, you can see the font size variables have been given descriptive names. Starting at a medium size, which is 1rem, we then have a few levels above and below it which take the base size (15px/1rem) and then compute a new value, eg an extra large size which is 1.2rem, or 15px * 1.2 or 18px.

To see this in action, inspect an h1 or h2 element on your site.

And, then, if you click on the Computed tab, you can see the actual font size, which, in this case, is 25.95px. In this example — the main heading on the PDP — this actually a non-standard size. You'll see that the standard size for h1s is 1.47rem, and this is 1.73rem. This isn't out of the question: if your new functionality requires a specific size that's not included then you can just set a rem unit specification in your declaration, but the point of doing something in the base Sass is so its reusable and consistent within the rest of the site.

As for the font itself, I've already talked about how to add a custom web font and despite its age, it's still good. However, I would add that I would generally avoid custom fonts; personally speaking, I find them jarring and it is only in rare cases that they improve user experience. For example, if there is a particular font that has become synonymous with your brand, then you could consider using it for titles and headings, but there aren't many companies for whom this is true.

Customizing the Base Theme vs Creating a New Theme

Changing the Sass enables you to make superficial changes to things like colors and sizes but, to make changes to the layout and presentation of elements, you will need to make template changes. But as you'll know, you never make change to existing templates: you have to override existing ones (or use JavaScript to inject a child view).

Creating a theme is a pretty drastic change. You're effectively completely separating the data side of the site from the current look-and-feel. Remember, the templates and Sass we include by default are effectively our 'default' theme. Creating a unique look for your site will probably require you, therefore, to replace (override) quite a few files.

In other words, when you approach what to do with a site's theme, you need to consider the two approaches:

  1. Make modifications to our base theme
  2. Override the base theme

In truth, these aren't two mutually exclusive approaches — they essentially exist as two ends of a spectrum. Creating a truly custom theme would mean to strip away all of the Sass and templates that we have provided in the base SCA bundle and that would be a lot of work.

To illustrate this, let's take a look at a modification I want to make to my site's code. In my scenario, I want to get rid of the subheader to make the entire header a bit more compact like this:

What I would do is this:

  1. Create a CustomHeader module
  2. Set it up with folders for template and Sass files, an ns.package.json file, and update the distro.json file
  3. Look at the templates that I want to modify and create overrides for them
  4. Use copies of the existing files as the basis for my changes
  5. Put any Sass changes into a one Sass file in the module

That is, in fact, what I did with the change you can see above. You can see the code here: CustomHeader@1.0.0.zip. (I should point out, this was put together quickly for the sake of the tutorial and isn't necessarily best practice.)

Now, while this is fine for making this customization to my company's site, it's problematic for creating a theme. For starters, I've confined all of my Sass changes to a single file that overwrites style declaractions in other Sass files. However, if I were to plug this module into another site then there's little guarantee that it would work at all — perhaps the site has already overwritten some of the styles themselves or they may have implemented styles with more specific selectors.

Instead, for theme builders, we would recommend going through the Sass files and finding the styles that you want to change; if there are any existing ones that need changing, override the whole file and then make your changes to that. This is much cleaner.

For the sake of comparison, take a look at the all the header-related files our professional services team override in one of their themes:

"overrides": {
  "suitecommerce/Header@1.3.0/Templates/header.tpl": "Templates/qs_header.tpl",
  "suitecommerce/Header@1.3.0/Templates/header_menu.tpl": "Templates/qs_header_menu.tpl",
  "suitecommerce/Header@1.3.0/Templates/header_profile.tpl": "Templates/qs_header_profile.tpl",
  "suitecommerce/Header@1.3.0/Templates/header_mini_cart.tpl": "Templates/qs_header_mini_cart.tpl",

  "suitecommerce/Header@1.3.0/Sass/_header.scss": "Sass/_qs-header.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-menu.scss": "Sass/_qs-header-menu.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-profile.scss": "Sass/_qs-header-profile.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-sidebar.scss": "Sass/_qs-header-sidebar.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-logo.scss": "Sass/_qs-header-logo.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-mini-cart.scss": "Sass/_qs-header-mini-cart.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-mini-cart-item-cell.scss": "Sass/_qs-header-mini-cart-item-cell.scss",
  "suitecommerce/Header@1.3.0/Sass/_header-simplified.scss": "Sass/_qs-header-simplified.scss"

This is the contents of the overrides parent folder, which contains overrides for each of the modules they're overriding. There's also a separate folder which contains the additions that go along with the themed header. While their change will be different to mine, you can see the stark difference: while not every file in the header module has been overriden, a significant number of them have been. Their module also includes small modification to the JS files, but they don't override any of them and instead extend the JS files' objects to return additional values. We consider this to be the best way to do it.

Overriding JavaScript is a drastic change to your site. Like overriding a Sass file, you're saying to the system that you want to disregard and entire file and replace it with another. This could cause issues when it comes to migrating to newer versions or transporting your theme to another site. It can also introduce operability issues, should you introduce other functionality that either override that same file or injects code into it.

Overrides should be reserved for when your required modifications cannot be made through normal customization methods. Remember, some of the things you can do without overrides:

  • Add a child view (ie more content) to a template
  • Add to the context object
  • Add or overwrite a method in a JavaScript or SuiteScript file
  • Add or modify options to the configuration schema
  • Modify the configuration object

Final Thoughts

It's kinda hard to write about theming, so I hope you weren't disappointed. We've received some feedback about this area, so I wanted to write about it. However, approaching it I felt like that there wasn't, perhaps, much I could write about.

I hope to have framed how creating a theme is different from merely customizing your site. If you are building up the look and feel then it's OK to approach your SCA site like you would any other web site, but if you're going for something which is transferrable then you will need to adopt a more modular approach: take a step back and look at what files you want to affect and then override them.

The other approach is simply to create a single Sass file for the entire module and then override the styles rather than the files. However, then you're not really building your own theme so much as customizing our reference theme.

As mentioned, there are about six 'big' areas of the site, plus the base styles, that should form the basis of your theme. Of course you'll obviously want to see what changes need to be made to your account and checkout areas too, and possibly to smaller things like the breadcrumbs or error messaging.

Finally, we're looking at theming ourselves (outside of our professional services team, that is) as we look forward to SuiteCommerce Standard. As we've made changes to the extensibility layer and the refreshing of our base Sass, we hope that those benefits are able to be realized by you too.