Frontend Developer Manual / Version 2406.1
Table Of Contents
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)
Example 4.6. Folder structure of the Sass files
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";
Example 4.7. Import order in entry files of a theme
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";
Example 4.8. Import order in entry files of a theme with bricks
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
).