How to Use Theme Designer

Owned by Danny Gibas
Last updated: Nov 13, 2024
4 min read

Modes

Theme Designer supports three modes, Developer Mode, Preview Mode and Presentation Mode.

Demo Mode

Overview: Demo mode is used to present theme options to clients. The demo mode is based off the "Clean" theme which reflects a Peak Resort branded site with minimal configurations preset. In this mode, the theme will implement the various style mixins dynamically by using the design control. It is important to note that when in this mode, there should be no mixins implemented in the clients theme file other than the three defalut mixins (@include theme-vouchers-css(), @include theme-rewards-css(), @include fix-header-for-td()) that are required to provide base styles for presenting various plugins.

Developer Mode

Developer mode is activated by toggling on developer mode. Doing so enables additional developer features including proving access to "Preview Mode", and revealing the mixin export options. This is the standard mode that you should be in while developing a new theme.

Preview Mode

Preview Mode provides a way to preview your theme with the mixins implemented on the client stylesheet. Enabling Preview Mode disables the Theme Designer styling controls as well as the styles being applied via the UI. This allows you to preview how the theme will look when running in Commerce.

Note: Preview Mode is only available when Demo Mode is enabled.

How to Demo

Demo mode is the default state for Theme Designer. There is no configuration necessary to start using it. The controls on the left panel are used to select between the pages you want to view. The controls in the right panel provide the theme options. There is currently a limitation with the checkout page in demo mode in that it will not retain the settings configured on other pages. This should be resolved in the future.

Theme options

Theme options are broken into different categories. Global options are applied site wide. Page specific options are applied only to the loaded page. Developer options should not be used in Demo mode.

How To Develop Themes

Using Mixins

Theme Designer uses SASS Mixins to implement theme options. The mixins provide all the CSS necessary to implement the chosen option as well as limited arguments to extend the configuration capabilities [when doing advanced theming]. This means you no longer have to manually write or copy various CSS to apply styles. The mixins ensure consistency in how theme elements are styled for all clients.

Using Preview Mode

The Theme Designer UI works by wrapping the various mixins in implementation classes and then toggling those classes on and off in the page root element. When you app ply mixins to the client theme file, those mixins will conflict with the mixins the UI is selecting. To avoid these conflicts, it is important to enable Preview Mode while developing. If you want to return to demo mode, you most comment out the mixins in the client stylesheet and toggle Preview Mode back off.

Step-By-Step Theming Process

  1. Pull a copy of the theme designer branch with git clone git@bitbucket.org:aspenwareunity/commerce-theme-builder.git

  2. Run Theme Designer with the yarn dev command in terminal

  3. Create a duplicate of the Clean Theme directory and rename it to the current client.

  4. Update the _colors.scss file in the client theme directory with all of the client color options.

  5. Update the _variables.scss file in the client theme directory with the paths to the correct image files.

  6. Update the _typography.scss file in the client theme directory with the clients font information.

  7. In the Theme Designer source files, open layouts/default.vue and checkout.vue. Locate the scss import statement that targets the client theme. Change the path in both files to point at the client theme directory you are working on. This will make Theme Designer load that clients SCSS into the Design window.

  8. Remove any CSS or Mixins if they exist in the _theme.scss file.

  9. In Theme Designer, in Presentation Mode, set all of the theme option controls to match the client choices.

  10. Enable Developer mode, and click the "Export All Mixins" button.

  11. Copy the mixins from the dialog box and paste them into the clients _theme.scss file. Make sure they are uncommented and save the file.

  12. In Theme Designer, enable Preview Mode. You should now see the mixins from the clients _theme.scss file being applied.

  13. While still in Preview Mode, make any additional configurations necessary to the mixins in the clients _theme.scss file and ensure they appear correct in the Theme Designer preview.

  14. Copy the clients entire theme directory from Theme Designer over to the Theme directory in commerce.

  15. Fire up a local instance of Commerce, set the environment to the client and QA the entire theme.

  16. If it looks good, commit the theme to Commerce source.

  17. IMPORTANT: DO NOT Commit any changes you made in the Theme Designer source.

Known Limitations and Bugs

  1. There is a limitation with the checkout page in demo mode in that it will not retain the settings configured on other pages. This should be resolved in the future.

  2. A code change is necessary to display anything other than the “Clean Theme”, so when developing a theme there is no UI method to view other themes.