Establishing CSS conventions and documenting them > Articles  > Establishing CSS conventions and documenting them


If semantics is defined as “a set of rules and conventions in order to allow a group of people to understand each other”…

Why not apply this concept to CSS conception ?


(Note : this article was previously published in French a few weeks before this translation –if you have any feedback on the translation made by Nicolas Hoffmann and John Elbing, please let us know.)

The reign of disorder

Surely you have in your experience, recovered one day running a CSS that looks like this :

.new-left, .new-right {
   background:url('/layout/images/icon-new.png') 0 0 no-repeat;
	 padding-left: 30px; /* don't touch */
  display: inline-block;
  min-height: 30px;
zoom:1; /* IE */
.new-right {
  display: block; /* don't know why, but don't touch */
 background-position: 100% 0;
  padding: 30px;padding-left:0;
/* ================= */
/* NEW */ .jpg {line-height: 13px; min-height: 1em; }
/* NEWNEW */ .jpg {line-height: 13px; min-height: 1.2em; }

It is the perfect example of how CSS were produced before : this language is very permissive and integration was the last link of the chain, the CSS were a heap of ruins and the only rule that prevailed was… disorder..

Many voices have been raised against these bad practices. Imagine you get this on a complex integration, it is particularly unpleasant :
 * Indentation is catastrophic and hinders readability ;
 * Properties are never in the same order ;
 * The sections are not clearly identified ;
 * You cannot be sure where you are in the project ;
 * And above all we do not know how to do something without making this house of cards collapse !

With the rising complexity of projects, it becomes very important to organize ourselves and agree on conventions for writing CSS. Conventions help to design, but they also make maintenance much easier. Let us add that if you have to update a CSS, you will be more inclined to maintain it carefully if it is already well structured.

Examples of conventions

There are many, there are almost as many as front-end developers ! :)

These conventions can sometimes surprise with their level of detail, but this rigor brings unparalleled comfort in the usage of a style sheet, even during conception.

In general, the following are described :
 * The different block comments (overall structure, subpart, help, etc.) ;
 * The choosen indentation : spaces / tabs, the number of, etc. ;
 * Marking properties, prefixed or not, on a single line if a single property ;
 * The order of the properties ;
 * Atomic classes available ;

  • etc.

Here are some example of conventions :

If you are using CSS frameworks, they also set their conventions. For example, you may study KNACSS’s conventions.

BEM (Block Element Modifier also provides an interesting idea for CSS : indicate each module, each module child and each module modifier in the way of naming classes :


Thus, it is possible to understand general structure and its modifications only by looking at the structure of HTML/CSS.

Let’s add to this that these agreements have effects that often go beyond the strict framework of the writing style sheets. For example, the fact of putting a single property per line greatly facilitates the display of changes to a release management tool code such as Git.

With many properties on the same line as in the example below, how do you quickly find out what exactly has been changed on the line in question ?

CSS code modified, displayed on Github, not clear

On the opposite, it is clear in this example below what was modified on each line.

CSS code modified, displayed on Github, clear to read

Other tools may also facilitate this structuration effort : preprocessors like Sass or LESS allow to split CSS files in several sub-files, thereby isolating each lot of your structure of your style sheet. Thus, research and / or modification will be more effective in smaller files.


One or several documents identifying the style guides must be created, even if it is for internal use only. Typographic element, different blocks, global layout, etc. must be described and explained.

Here is an example (in french) : des guides de styles pour votre intégrateur.

CSS Styleguide example

It will already facilitate the creation of the CSS : the front-end developer will have an overall vision and detailed view of the web designer’s work, and is more likely to transcribe it faithfully. He will also have an overview of the various modules to produce.

Secondly, the newcomer during the project will have a reference document. Add to that a well ordered and well commented CSS greatly facilitates maintenance and evolution.

Finally… why not give this document to your customer ? It is a guarantee of seriousness and professionalism, sustainability, both for the site and for its CSS. It would be a shame to miss all theses benefits… and you could be the agency taking over the site.

This style guide concept can be even more important in some approaches : “styleguide driven development”.

Here are some examples :

This approach puts documentation as a central node via a living styleguide. This may seem surprising, but at the same time, this hinders the bad practice of making styleguides at the end of the project (or never).


As you can see, there are lots of possible conventions and tools, the best being - in my humble opinion - the ones you choose and stick to.

Let’s say it : our CSS should be pampered and kept up with utmost rigor !

References, further reading


This article is part of the series “Great modern CSS conception principles”.

À propos de cet article

Vos commentaires

modération a priori

Attention, votre message n’apparaîtra qu’après avoir été relu et approuvé.

Qui êtes-vous ?
Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Suivre les commentaires : RSS 2.0 | Atom