Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.
L1–L2
Unit 03 · Stylesheets and SCSS
SCSS structure and naming
Stylesheets and SCSSPage 18 of 35Updated
Theme stylesheets are SCSS compiled by the build: tokens and mixins first, then one partial per component, named with BEM. The import order, glob imports and the builds that support them, Sass modules beside @import, and class names from production partials.
Who this is for. The theme developer adding or changing styles in a theme repository. Afterwards you can find where a rule belongs, add a component partial that is actually compiled, and name its classes the way the rest of the repository does.
Nothing on the platform constrains how a theme organises its SCSS. The conventions below are the ones production repositories follow, and following the one in front of you is what keeps it readable for the next developer.
Generic first, then components
An entry file imports the generic layer first, the variables, functions and mixins that produce no CSS of their own, then the base styles, then one partial per component. A production gulp repository's main entry:
The order is not cosmetic. A partial can use only the variables and mixins imported before it, and a later rule of the same specificity wins over an earlier one, so components come after the base styles they refine.
Glob imports, and the builds that have them
The last line above is a glob import: every file in components/, in alphabetical order. It works because the gulp build runs gulp-sass-glob before Sass, and it means a new partial in that folder ships with no other edit. Sass itself has no globs. None of the production webpack repositories configures a glob importer, so in a webpack build a new partial is compiled only once an entry imports it by name. When a new file has no effect, check which build you are in before you check the CSS.
A glob import also fixes the order alphabetically. A component that must come after another is named to sort after it, or imported by name.
@use and @import
Newer code uses Sass modules: @use loads a file once and namespaces its members (tokens.$primary), @forward re-exports them. @import is deprecated in Dart Sass and will be removed, but most theme repositories still rely on it, and one production Twig repository uses both in the same entry. They can coexist: every @use must come before the file's other rules, and members loaded with @use are not visible to files pulled in with @import unless those load them too. Converting a repository is its own task; do not half-convert one entry as part of a feature.
BEM names
Component classes follow BEM: a block, its elements after two underscores, and modifiers after two hyphens. From a production partial, _card-landscape.scss:
SCSScomponents/_card-landscape.scss and _addon.scss (extract)
One block per partial, and the partial named after the block, so .card-landscape__media is found in _card-landscape.scss without a search.
No element of an element (.card__body__title): an element belongs to its block, wherever it sits in the markup.
The same names in the template. A component template's root element carries the block class, and its header comment names the partial: Documenting a template's inputs.