Sass Best Practices for Themes
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. The SuiteCommerce Designer’s Guide provides more information on customizable Sass styles. See Commerce Sass Style Definitions for details.
All Commerce Sass files are named as partials (with a preceding underscore), such as _BaseSassStyles.scss.
The following best practices describe how to implement Sass in your themes:
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 the Site Management Tools). The best practice when creating a theme is to use the SuiteCommerce Base Theme as a baseline. See Anatomy of the Base Theme for more information about 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 file and in 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 ensuring that any exposed variables display as expected in the Site Management Tools (SMT) Theme Skin Manager.
Formatting Sass for SMT
Some Sass development practices can affect the SMT Theme Skin Manager user experience.
As you build Sass for your theme, you can expose variables to the SMT Theme Skin Manager. 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.
Consequently, the following Sass practices result in variables that are only accessible in the backend. As a best practice, avoid using the following practices 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, 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 administrator 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 longer 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, MyAccount, 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 Edit the Theme Manifest for more information.
Each theme includes the following Sass entry points.
|
Application Impacted |
Application Sass File |
|---|---|
|
Shopping |
Modules/Shopping/shopping.scss |
|
MyAccount |
Modules/MyAccount/myaccount.scss |
|
Checkout |
Modules/Checkout/checkout.scss |