Dev Docs

# SCSS

# Folder Structure

Inside each theme's scss folder:

  • components/ - SCSS code from blade templates in theme/views/components.
  • partials/ - SCSS code from blade templates in theme/views/partials.
  • vendor/ - Integration with 3rd party SCSS files. This includes things like overrides or configuration using variables. If the only line you need is @import "~myvendor/file.scss", then you do that in either main.scss or a JS file and not here.
  • base.scss - Global styles and resets.
  • editor.scss - Styles to use inside the CMS Admin WYSIWYG editor.
  • fonts.scss - Importing of CSS fonts. It's preferably to not host fonts, and a third party service as it makes handling licensing easier.
  • helpers.scss - Global utility functions adn mixins. Don't be afraid to create functions and mixins in other places, its all just SCSS. this place is intended only for global utilities.
  • main.scss - The entry point for the frontend stylesheet
  • modules.scss - Module (as in CMS Modules) related code and utilities, spacing overrides for module combinations go here.
  • typography.scss - Central place to store all the different typography styles across modules. 99% of all typography styles must exist here first as mixins.
  • variables.scss - All variables go here. Unless you have local, one-time use or "utility" variables, those can exist closest to where they are used.

# Assets

All assets in assets/fonts/ and assets/images/ must be imported from SCSS using relative paths:

.component {
  background: url(../images/my-cool-bg.jpg);
}

Don't try to user variables for this. Using the syntax above ensures IDEs understand the dependencies and correctly handle refactorings.

During compilation, assets are copied to dist/ and only that is copied to production, the whole assets/ is NOT deployed to production to avoid unauthorized access to un-minified project files.

# Variables

General guidelines:

  • Try to depend on variables as much as possible.
  • If there is an existing Bootstrap variable (open '~bootstrap/scss/variables' in your IDE) that solves it, use it.
  • When styling global elements, first try to achieve the design modifying bootstrap variables only. Most of the time this won't be enough, at which point you can add a vendor/boostrap/xxx.scss file to further customize your component.

# Colors

ALl colors must be defined as variables. Don't attempt to use one-off colors. Color derivatives using SCSS functions are allowed for special effects such as shadows and gradients.

# z-index

Use the Bootstrap provided (or equivalent) z-index variables instead of manually specified ones.

$zindex-dropdown
$zindex-sticky
$zindex-fixed
$zindex-modal-backdrop
$zindex-modal
$zindex-popover
$zindex-tooltip

As recommended in Z-index on getbootstrap.com (opens new window), you can use low z-index values of 1, 2, and 3 for fixing minor in-component overlapping issues.

# Typography

All typographic styles must exist on theme/assets/scss/typography.scss as mixins. This ensures we have a central place for reviewing and detecting duplicated and very similar styles, which makes the design more cohesive when avoided.

Whenever trying to implement a typography style from a design, first look into this file to see if there is a style that matches perfectly or very closely the one from the design. Often times designers fail to create a uniform style system in their designs, so very close typographic styles should be considered equivalents.

For those typography styles that are used very often, you can define a class to use directly in HTML by using a t- prefix:

.t-header-1 {
  @include t-header-1 ();
}

.t-subtitle-1 {
  @include t-subtutle-1 ();
}

Remember to always use mixins first, as it allows to re-use the style even if changing the markup is problematic/impossible.

# Module Spacing

Spacing between Modules in a page is often not strictly defined, resulting in a lot of ad-hoc spacing rules. In order to tame this complexity all spacing logic should exist in modules.scss.

By putting al logic here, we have similar benefits to those of typography styles, where we can see all rules at play in a single pass.

In concrete, try using the existing module spacing mixins (module-spacing-N), if necessary you can add more module spacing mixins to cover your use-case. Always use variables for this e.g. $module-spacing-BRK or $module-spacing-2-BRK, etc.

All cross-module spacing rules should also live in modules.scss. Always try to use margin-top for defining spacing, this makes it easy to override spacing between two adjacent modules:

 .hero + .gallery {
   margin-top: $module-spacing-lg * 1.5; // increase the spacing when a gallery comes after a hero
 }

← Page Builder (ACF) →