Styles

SiteBox does not impose any specific method for styling. All the information presented below are mere recommendations and conventions that have been proposed by the SiteBox team.

Entry points

The following files are the main entry points for scss styles:

• frontend/src/assets/stylesheets/style.scss – basic Gatsby styles
• backend/themes/statik/assets/scss/editor.scss – Gutenberg WYSIWYG editor styles
• backend/themes/statik/assets/scss/editor-page.scss – page styles where Gutenberg is embedded

These files are processed by building scripts, and it depends on them which CSS styles will be passed to the appropriate environment (frontend or backend).

The above files contain super basic import directives that point to the corresponding files located in the commons/assets/stylesheets directory.

@charset "UTF-8";
 
@import "@commons/style.scss";

Such a solution allows to move the entire burden of defining styles to one place, i.e., the commons/assets/stylesheets directory.

Stylesheets

Styles are placed in the commons/assets/stylesheets directory. Architecture is organized according to the

SASS Guidelines (with slight modifications adapted to SiteBox needs)

One source - (backend & frontend)

Styles defined in commons/assets/stylesheets are treated as common styles for both environments (backend and frontend). This means that both environments use the same source .scss files. In specific situations (for instance: completely different HTML block structure in both environments), we can "separate" backend and frontend styles from each other. To do this, mixins should be used:

@include gatsby() {
}
 
@include gutenberg() {
}

The above mixins are automatically included in building scripts, and can be used in all .scss resources. Thanks to these mixins, Gatsby styles will not be included in Gutenberg styles, and vice versa.

This method should be treated as a last resort. It is much better to prepare blocks in such a way that they can be styled with separate styles/classes for both environments simultaneously.

Mixin usage example:

@include gatsby() {
  .wp-block-statik-core-button {
    background-color: transparent;
  }
}

Global styles

globals.scss is a common file for all SCSS declarations that do not return any CSS output. These are functions, variables, mixins or similar. These declarations are exceptionally treated by building scripts of Gatsby and Gutenberg. Once declared, all of them can be consumed in stylesheets from both frontend and backend based on project needs.

• File stores a reference to a ./globals/index.scss, which lists all declarations applied to the project.
• It is being included in every imported .scss file.
• The code contained in this file is available in every other processed .scss file.
• It should contain code that does not cause the resulting CSS file to grow (i.e., mixins and variables).

global.scss is automatically read by SiteBox CLI and other SiteBox tools and should be considered more like a road sign to make it easier to find global declarations

@import "./sass/abstracts/variables";
@import "./sass/abstracts/functions";
@import "./sass/abstracts/mixins";

globals.scss file stored as contains a reference to:

• Variables, which declare base SCSS properties across the project helper functions utilised by the boilerplate,
• Mixins, which allow to define styles that can be reused throughout the project, and
• Functions, which allow to define complex operations and abstract out common formulas that can be reused throughout the project.

Variables

Boilerplate by default comes with a minimum amount of variables applied to the project. These variables should not be removed as they are consumed by different components of the website. We strongly encourage you to come up with project-specific variables that you would re-use and control from a single file.

• font__default--family – Default font family applied to all html tags
• font__secondary--family – Secondary font family
• font--base-size – Font size and base value for all typography related
• font__h1--font-size, font__h2--font-size, font__h3--font-size, font__h4--font-size, font__h5--font-size, font__h6--font-size.

@TBD

Fonts

Fonts are automatically included in the resulting CSS code for both environments. The font configuration should be located in the commons/assets/fonts directory, where google.json, typekit.json, and local.json files should be defined (optionally).

google.json

The definition is based on the Google API.

[
  {
    "family": "Red Hat Display",
    "axes": "wght@500;700"
  }
]

The definition is based on the Typekit API

typekit.json

{
  "projects": ["nea0vsq"]
}

local.json

There's an option to include own local files. To do this, provide paths to files with @font-face rules

{
  "fonts": [
    "./local/custom-fonts/fonts-declaration.scss",
    "./local/my-font/stylesheet.css"
  ]
}

You can find more information about fonts at Fonts page

Mixins

• clearfix()

@TBD

Functions

@TBD

Individual classes

Try not to write individual CSS classes for block (additional, specific CSS classes). It's due to the fact that:

• "loose" connection is created. It will be difficult to identify in the future where a particular CSS class was used in Gutenberg,
• CSS class becomes potential clutter that will never be removed due to fear of "something breaking,"

Therefore, try to "design" the appearance of blocks in Gutenberg.

Block styles

Basic block styles are shipped together with a blocks package. These styles are meant to deliver structural declarations that simply holds a block in expected look and feel. All files are read automatically when front-end or back-end is processed.

Block styles should be defined in the commons/assets/stylesheets/blocks directory. By defining them in this path, styles for each block will be included individually, which means that they will not be included if the block does not exist or is not used. Purpose of stylesheets is to override or extend default block styles

In order to include styles for a specific block, the appropriate structure must be reflected, and the index.scss file should be placed there.

SiteBox block example:

commons
|- assets
 |- blocks
  |- statik
   |- post-type-cards
    |- index.scss

"@TBD: using statik CLI to fetch name"