Sass Best Practices

This topic applies to

Applies to

SuiteCommerce | SuiteCommerce Advanced


Commerce themes let you customize the design elements of your web store experience using Sass, or Syntactically Awesome StyleSheets. Sass is a scripting language that is transformed into CSS when you use the theme development tools to compile and deploy your customizations to the application. The SuiteCommerce Designer’s Guide provides more information on customizable Sass styles. See Design Architecture for details.


All Commerce Sass files are named as partials (with a preceding underscore), such as _BaseSassStyles.scss.

Creating Sass Variables

The SuiteCommerce Base Theme SuiteApp includes the BaseSassStyles module. This module contains all Sass variables and metadata (for exposing and organizing variables in SMT). The best practice when creating a theme is to use the Base Theme as a baseline. See SuiteCommerce Base Theme for details on installing this theme.

You can create your own Sass variables. You can introduce variables within new Sass files, as part of a new module, or within the BaseSassStyles module. Observe the following best practices regarding new variables and their metadata:

  • If you are defining a new module as part of a theme, define all new variables and any metadata within that module.

  • If you are defining a variable for a particular module only, define that variable within the associated module. Avoid introducing global definitions within one module.

  • If you are defining a variable that controls multiple properties in different modules (such as a new theme color $sc-color-theme-250), define that variable within the BaseSassStyles module.

  • If you are adding a new Sass file to your theme, you must declare each file in the theme’s manifest.json and the applicable entry point file. See Add a New File to a Theme for details.

  • Always test any new variables in your domain, across all applications. This includes checking to ensure that any exposed variables display as expected in the Site Management Tools Theme Customizer.

Formatting Sass for SMT

Some Sass development practices can affect the Site Management Tools Theme Customizer user experience.

As you build Sass for your theme, you can expose any variables to the SMT Theme Customizer. When an SMT administrator changes an exposed variable, the application compiles any changes and renders them for preview. This action includes two separate compilations. The first compilation occurs on the frontend within 2 seconds. However, after 5 seconds of user idle time, the application triggers a second compilation on the backend.

As a result, the following Sass practices result in variables that are only accessible in the backend. As a best practice, avoid using the following for any Sass variables exposed to SMT:

  • Sass variables that receive user-defined function calls

  • If conditional statements

  • Mixins

User-defined function calls

Avoid user-defined function calls.

For example, consider the following example, assuming that $sc-primary-color is also :

$sc-color-secondary: myfunc($sc-primary-color) /*editable(…)

In this example, you set the result of an exposed variable, such as $sc-color-secondary, to a custom function, myfunc($sc-primary-color). Assuming $sc-primary-color is also declared as editable, when the SMT admin changes the primary color value, the primary color value compiles quickly in the frontend. The problem with this approach is that myfunc($sc-primary-color only exists in the backend and takes a longer time to preview.

If Statements and Mixins

Avoid if constructions using exposed Sass variables. For example:

@if $sc-color-secondary == $12345 { background-color: $sc-color-primary;} @else { background-color: $56789;}

The problem with this example is that the frontend does not know the else condition. Passing values within or grouping variables as mixins causes a similar issue. All of these issues are solved during the backend compilation, but this can take a considerable amount of time.

Sass Entry Points

Every theme relies on an entry point file to load Sass into the correct application (Shopping, My Account, or Checkout). Each entry point declares the Sass files that are part of the application. For example, if a Sass file affects the shopping application only, it needs to load through the shopping.scss entry point. If it affects all three applications, it needs to load through all three entry points.

For an example of how to edit an entry point, see Add a New File to a Theme.


All Sass files must also be declared in the theme’s manifest.json file. See Theme Manifest for more information.

Each theme includes the following Sass entry points:

Application Impacted

Application Sass File



My Account