In the CoreMedia Blueprint themes CSS files are generated from Sass files (see sass-lang.com). Except for the root Sass files of a theme ($theme-name.scss and preview.scss) which are also called entry points all files should start with an underscore which tells the Sass compiler that the generated code will not be written into a separate CSS file but into the same output file as the Sass file it was included from. Sass Files starting with an underscore that generate styles when importing them are called Partials.

The folder structure is as follows:

sass/                   // sass files are located inside the themes 'src' folder
├── partials/           // contains partials
│   ├── _grids.scss
│   ├── _banner.scss
│   └── ...
├── variables/          // contains configuration in form of variables
│   ├── _colors.scss
│   ├── _grids.scss
│   ├── _variables.scss
│   └── ...
├── [$theme-name].scss  // main entry file for a theme
└── preview.scss        // preview entry file for a theme (will be covered later)

All imports of variables need to be performed before any partial is being imported in the main entry file. This leads to the following import order (based on the folder structure in the last section):

// ### VARIABLES ###

@import "variables/bootstrap_variables";
@import "variables/grids";

// ### PARTIALS ###

@import "partials/grids";
@import "partials/hero";

    

Importing SASS Code of Bricks

Sass code in Bricks follows the same patterns as Sass code in themes, so the code is also split up into variables and partials. When importing a brick, you also need to make sure that all variables are loaded before any partials. For this every brick provides a _variables.scss and a _partials.scss that are meant to be imported keeping the order in mind. A typical import of bricks using the "smart-import" mechanism looks as follows:

// ### VARIABLES ###

// Own variables

@import "variables/bootstrap_variables";
@import "variables/grids";

// dependency variables

@import "?smart-import-variables";

// ### PARTIALS ###

// dependency partials

@import "?smart-import-partials";

// Own partials

@import "partials/grids";
@import "partials/hero";

    

Your own variables need to be set before any of the brick variables will be included. The reason behind this is that in sass its common practice to use the !default flag (see: Variable Defaults: !default). for variables that are meant to be configurable. As bricks in most cases provide configuration in their Sass code, you need to override configuration before their variables are imported.

The file names ?smart-import-variables and ?smart-import-partials are only placeholders. They do not actually exist but will be substituted by our theme build mechanism to include all dependencies that work with the "smart-import" mechanism. Please note that - as CoreMedia cannot make any assumptions about the structure of third-party libraries - the "smart-import" mechanism will only work with modules that have an entry coremedia.type in their package.json that is either set to lib or brick.

Caution

While also being convenient these two imports serve as a contract between a brick and a theme. A brick always expects that its Sass files are imported. This means that whenever you add a brick to your theme (by adding a dependency to its package.json) you need to import its _variables.scss and _partials.scss using the above code in your main entry sass file.

You do not need to take care of the dependencies a brick might bring in turn (transitive dependencies). This is also handled by the brick as it will already import the variables and partials of its dependencies. You also do not need to worry that code might be imported twice, only the first import of a Sass file will by performed, all later imports of the same files are ignored.

Suggestions for Preview Specific Styles

Currently, there is no deep integration for preview specific adjustments to a theme - this includes preview specific styles. The only thing that the default theme build provides is the possibility to place a preview.scss next to the $theme-name.scss that will be compiled into a preview.css in the theme's target folder next to the $theme-name.css.

The preview entry file should follow the same patterns as the main entry file but should be treated as an addition rather than a complete separated entry. While the main entry file ($theme-name.scss) should import all variables and partials required for the theme (including dependencies) the preview entry file (preview.scss) may import common variables that are also used in a theme but should never include partials (and so code generating files) that are already part of the theme. As CoreMedia only supports preview specific as an addition to the existing styles of the theme this may lead to code duplication or even unintended overrides (if the variables configuration is different, for instance).

The "smart import" mechanism also works for the preview.scss and will handle the import of preview specific bricks (which currently leads to importing the SCSS code from @coremedia/brick-preview).