Link drop: HTML and CSS coding guidelines

I’ve been reading a lot about coding guidelines lately, so I figured I would share the best resources I found. When working as part of a team, it’s important to agree upon a common coding style, not everyone has to like it but good things happen when everyone follows the rules.

Note that I don’t like all of the guidelines written in those resources which is why I will be working on writing down my own coding style.

If you’re serious about writing and maintaining a large CSS application used my multiple developers, you should know about these resources.

Code Guide and WTF, HTML and CSS? by @mdo

Code Guide is a list of HTML and CSS standards that @mdo, one of the creators of Bootstrap, put together.

WTF, HTML and CSS? is a collection of common HTML and CSS pitfalls. If you’re serious about writing CSS you should be aware of these.

mdo-ular CSS (video) - or if you prefer the slides only

Another resource by @mdo, if you read his Code Guide you won’t learn much but the presentation is well worth it.

About HTML semantics and front-end architecture

In this important article, Nicolas Gallagher explains why class names should be determined by the presentation, not the content of the elements. This is something that I wasn’t able to properly express for a long time but this article says it all.

The important thing for class name semantics in non-trivial applications is that they be driven by pragmatism and best serve their primary purpose – providing meaningful, flexible, and reusable presentational/behavioural hooks for developers to use.

Sass Guidelines

An opiniated guide on how to write good Sass.

How to structure a Sass project

If you’re wondering how to organize your Sass files, check out this guide. That’s not exactly how I would do it, but it’s a good start.

Medium’s CSS is actually pretty f**ing good

A write-up of the popular writing platform Medium’s CSS re-write by @fat (another creator of Bootstrap).

Bootstrap, Foundation and Primer

Bootstrap is the popular front-end framework and Primer is “the CSS toolkit and guidelines that power GitHub”. If you intend on creating your own style guide, these are good examples of well-thought guides.


It calls itself the “low-level utility toolkit”, it’s utility classes on crack. If you like the flexibility of CSS classes such as text-center, clearfix, pull-left, etc. Then you might like this one. It has classes to change fonts, colors, margins, padding, borders, …pretty much anything you can think of. I personally think there are too many and I really don’t like the naming (clever but not obvious). It’s also incredibly easy to misuse and start chaining utility classes to build your app, don’t. If you’re using more than one or two utility classes on an element, maybe think about making it a component. Don’t fall back into the inline style trap that CSS got us out of.


A collection of modules/components. More basic than Bootstrap and doesn’t come with preprocessor versions which makes it much harder to configure (but easy to extend). If you’re looking for a minimalist CSS framework, this is a decent option. Pure is based on SMACSS.

SMACSS by @snookca

SMACSS stands for Scalable and Modular Architecture for CSS. It provides guidelines on how to write your CSS in a way that will be easy to maintain. It’s a book and a workshop, but it offers a lot of free content online.


SassDoc makes it easy to write documentation right in your CSS files. Write your comments following a few rules and SassDoc can generate a beautiful documentation website.

Next step

Once you’re familiar with the concepts in those guidelines, I encourage you to make use of linters so that you don’t need to enforce the rules by yourself.

You should also think about putting together your own coding style if only to write down what you most likely think about all the time when writing and reviewing code.

Michel Billard's profile picture

A web developer's musings on software, product management, and other vaguely related topics.