“paint brushes next to drawing book and watercolor palette” by Tim Arterbury on Unsplash

Rules for theming and Styling with CSS, SCSS

Theming guidelines — Part 3

Styling using Cascading Style Sheets is an integral part of web development.

Theming guidelines

This article is part of a block of articles about theming guidelines.

Any code is generally clearer and easier to maintain when it does not use globals, css styles are global

Some projects have only custom styling and do not use any toolkits for fulfilling the individual needs of the client. Toolkits are commonly used for rapid prototyping or for theming larger systems. Please read how to customize toolkits if you want to work with one from the beginning.

Best practices for styling and theming

Use standards

  • UTF-8 encoding
  • valid CSS or SCSS

Do not use inline CSS

Inlining CSS will increase the size of the HTML which is by default not cached. Javascript can generate and manipulate inline CSS for some use cases like animations or drag and drop.

Use preprocessor

Preprocessors for generating CSS are conventional in various popular CMS.

  • SASS with SCSS syntax is most common
  • SASS with SASS syntax used less often
  • LESS usage is declining since Bootstrap started using SASS
  • Stylus can have an honorable mention

There is an option to write tomorrows CSS syntax, today using CSS next and PostCSS. Toolkits using CSS next are not popular at the moment.

Use CSS in JS

Use emotion, emotion is a library designed for writing CSS styles with JavaScript is a library designed for writing CSS styles with JavaScript

🚨Use only class name selectors

It is not allowed to select using

  • HTML elements selectors
  • id attribute selectors

Always use only class names selectors.

Naming class names

Class names and comments should be in English. There are few options for naming conventions, but BEM Block__Element — Modifier is most popular.

BEM — Block__Element — Modifier is a methodology that helps you to create reusable components and code sharing in front-end development

BEM by Example — an article is dealing with BEM naming convention into detail, please read the featured article if you are not familiar with BEM.

🚨Do not use nested selectors🚨

Nested selectors will add specificity to the styles. Overriding nested selectors will have to be an equal or more specific selector. It is even more complicated to work with nested selectors in themes.

✍️Use same class multiple times as a trick for overriding nested selectors
// Do not overide like this
.aui div.table {...}
// use same class multiple times
.table.table.table {...}
// Or with SCSS 
.table {
&#{&}#{&} {...} //= .table.table.table {...}
// PS: In styled-components or emotion you can use
.table {
&&& {...} //= .table.table.table {...}

Write your CSS rules without vendor prefixes

Forget about them entirely and use tools like autoprefixer and PostCSS.

🚨Use special class names for adding javascript functionality🚨

Styling and interactivity should not be added to an element using just one class selector.

  • use class names that start with “.js-” (class names are meant to be used only for javascript functionality)
  • never use class names that start with “.js-” for styling

This will allow you to reuse the same javascript functionality on different styled elements, and separate concerns to HTML, CSS and JS languages.


Automate things that can be automated. Cost of enforcing some of the rules can be too high. It is always a better investment and uses tooling that will enforce rules.

Enforcing code style rules in code reviews is a waste of expensive developer time.


Projects should use .editorconfig (http://editorconfig.org/), for basic formatting rules like

  • encoding
  • Unix-styled end of lines
  • the use of spaces over tabs
  • indent size
  • settings can be used by other tools such as prettier

All the setting can be different for various file extensions. Nearly every IDE and Editor is supported.

Package manager

Use npm or other package management tools and modules you want to use in the project. Do not download files from the internet an inline them into your git repository.


Do not commit generated code into your repository. Exclude build or dist folders from your git.

Autoprefixer and PostCSS

Allow you to write your CSS rules without vendor prefixes.

Automatic code style by pretty printing

Possible options:

  • automatic formatting for CSS, SASS, and javascript
  • automatic optimization of images in various formats (png, jpeg, jpg, gif, svg)

Tools that are used pretty printing by prettier, and javascript rules using an eslint ideally a combination of both by using something like https://www.npmjs.com/package/eslint-config-with-prettier.

Precommit and prepush git hooks

As the name suggests you are able to run scripts before every commit or push. Use automatic code style and pretty printing with git hooks and push only prettified code to the repository

  • the prettified code will have less merge conflicts
  • only automatically optimized images will be committed to the repository
  • you will never see another PR comment addressing code style