CSS coding guidelines

HTML coding guidelines
June 2, 2017
Javascript coding guidelines
June 8, 2017

Lately our company uses LESS CSS precompiling. Bootstrap 3 is at the core and provides the responsive grid, forms etc.

LESS gives the advantage of being able to split CSS code into sub-files. This provides better overview than putting everything into one large file.

The Gulp toolchain takes care of compiling and optimizing the resulting CSS files.

Coding guidelines

Be generic, be reasonable, be semantic, be modular

Be generic

  • Always use class names instad of IDs
  • Try to make your code re-usable
  • provide clear class-naming (see below)
  • do not use inline styles
  • Think of possible context and try to match the CSS selector to the context.

Be reasonable

  • Keep your code readable
  • Check the project browser scope before deciding which modern feature you are going to use
  • Start testing in older browsers early on

Be semantic

  • Try to give an idea of context when creating classes
  • Use nesting wisely in LESS

Be modular

  • Keeping your CSS selectors lean will greatly increase modularity
  • Use nesting wisely in LESS
  • Create re-usable utility classes (for spacing, text-weight etc.)

Writing style/Naming Convention

Use dashed-camel-case for class naming.

Good: .my-class-name, .page-title, .text-bold

Bad: .MYCLASS, .MyClassName, .tBold

Keep readability in mind: use semi-collapsed writing style, one line per selector.

.my-class {
  font-size: 12px;

.my-class {
  margin: 0 auto;
  width: 100%;

CSS Selectors

Keep selectors lean and small. Long selectors are slow at parsing. Long selector are also called “overspecified”. Read more about CSS specificity.

How CSS selectors are parsed

When the browser starts parsing the CSS file, it reads all selectors from right to left.

Consider this long selector:

#MyPage ul.some-class li.another-class a span { //... }

A browser will parse as follows:

  1. Find all span elements on the page
  2. Find all span elements inside an a
  3. Find all span a inside elements with CSS class another-class
  4. Find all li.another-class
  5. Find all li.another-class a span inside elements with CSS class some-class
  6. Find all ul.some-class
  7. Find all ul.some-class li.another-class a span inside elements with ID MyPage

Another problem with this long selector is the use of the ID instead of a class. To change the design of this selector, you have  3 bad options:

  • Add another ID to the selector: #MyPage #AnotherId ul.some-class li.another-class a span
  • Use !important
  • Use inline styles on the element

All of these three options are bad.

A better approach could be

.another-class span { //... }

Which reads: Find all span elements inside elements with CSS class another-class

How to name classes

Never use IDs for CSS selectors.

Finding a good name for a CSS class can be somewhat complicated because it has to meet the following conditions:

  • it must be generic but still provide context: create a generic class for look-alike elements and add modifier classes to achieve different designs
  • it should not convey layout or design: do not use colors or directional names

Some class namings should be according to Bootstrap 3 naming convention: .nav-, .btn-. You must follow this convention.


/* bad */
.NavigationLeft { ... }
.red_text { ... }
.GreenButton { ... }
#FormButton { ... }  <-- NEVER USE IDs IN CSS!!

/* good */
.nav-secondary { ... }
.text-error or .text-danger { ... }
.btn-primary or .btn-action { ... }
.btn-default { ... }

This writing style is derived from OOCSS and BEM and extended to our needs and rules.

Constructing definitions for reusablity

Start at the lowest denominator then specify as you go along. For example, if your layout is built with different styled, box-like elements, start with a .box class. Different versions of this box can then be achieved using modifier classes, for example .box.box-primary

Put all definitions for .box elements into a file /css/less/_box.less.

.box {
  border: 1px solid transparent;
  background-color: #ffffff;

.box-primary {
  border-color: blue;
  background-color: blue;
  color: white;

Providing state

State classes generally follow the HTML states (:active, :hover, :disabled etc).

When applying a state to an element, always use any of these where applicable:

  • active: for navigations, buttons; anything that can be toggled to activate. In case of navigation, always add to the list element:
    <li class="active">
      <a href="/some/path">A link<a>
  • has-*:  add to container element for additional layout possibilities using cascade. .box.has-image, .teaser.has-chart