Scss-Styleguide with BEM, OOCSS & SMACSS

Styleguides become more popular at the developer-community. The projects get more complexity, are bigger and to maintain the code become harder. Mostly you are not alone and work in a team with smart people.

If you build the project from scratch, than it’s easy for you to develop features, fix bugs or something like this. You know how it works, but if another one of your co-worker should be develop the next feature it’s very hard without a common base.
The developer must understand the environment and often it’s hard to read the code or get an overview, which modules are available. Then this case arrives, then we mostly write double code or it become fluffed.

Possible cases, which you can declare in a styleguide:

  • Tabs or Whitespace?
  • Folder-Structure
  • Structure for modules
  • Working with breakpoints
  • Naming-Convention
  • Variable-Handling
  • Importing files
  • Categorizing CSS-Rules
  • Generally CSS-Stuff


Having a good structure for your development-process is so important and the basic of all. You should pay attention that the base is mostly equal in each project – it will help you and your co-workers to incorporate easy in new projects. I will show you my personal structure (based on SMACSS):


  1. For each new module make a new file for it
  2. Prefix filenames (better searching in your editor)
  3. Partials get a underscore as a prefix
  4. Cut states and modules in different sections
  5. One single file for importing all partials like application.scss

Structure a module

A structure for module? It’s not too much? No I don’t think so. A module can has so much different types or become much complexity.

The module has three different sections

  1. At first we have a area for Config. There I define specific colors or other stuff for configuration like colors.
  2. Now the main part of the file, Base. Writing all the styles here for all types of the module
  3. The footer called States. Here I import the states for the current module. Not more.

Importing files

In a project there are so many partials. I don’t like to include files in other files. I prefer to have one single file like application.scss  and there I include all other. For this I created a structure like in this example:


  1. Structure in base, layouts and modules
  2. For each section only declare @import  once
  3. Remove file-ending

Naming conventions (BEM / SMACSS)

Block, Element, Modifier / Scalable and modular architecture for CSS

I love both methods. Above all SMACSS is a must read for every frontend-developer, which want to write scalable frontends. Jonathan Snook is the author and he wrote all his experience in a little book. Combine these two methods is the best way for me to handle naming.


At first we create a palette for globally usage like colors. We define it in the _config.scss . If we have some specific variables, then we put it in the file for the module. Readability is so important and because of this I use separators in variable-naming: a hyphen.

Handling Breakpoints: Element Queries

Element Queries? What do you write, Tim? Uhh, Element Queries with Sass are so much better than the mediaqueries. Do you know how it is too have all your specific responsive styles in an own file? This is crappy I think. You write modules, then you should declare the responsive behaviour of it there. Not in another file.

It’s not important for the performance that we have only one declaration of the mediaquery. Because of this we can use it more like Element Queries. Read more about this situation at a blogpost by Anselm Hannemann, which had the same question.

Categorizing CSS-Rules

If I write CSS / Scss I am really consistent and want to set rules for all kind of stuff. Because of this I have rules for categorizing my styles.

  1. Box
    • margin, padding, display, etc.
  2. Border & Background
    • border, border-radius, background-color, etc.
  3. Text
    • color, font-size, text-transform, etc.
  4. Other stuff
    • animations, transforms, etc.


Avoid ID’s

ID’s are really hard. They are to specific and mostly necessary for JS-Hooks. The better way is to use classes.

Avoid !important

If you need this, than goes something wrong at your CSS-architecture, because you need this only if you want to overwrite styles. If your structure is clean, than you will don’t need this. It’s like to shot with a cannon to sparrows.

Avoid child-selector

Why I avoid child-selector? It is yet a good CSS-Feature? No I don’t think so. At my start I used it often, but more and more I learned that it makes the module to specific. It depends on the structure of your html, but what is if the order will be changed? Use classes!

For a few days I tweet something about this, because of I found it in a old project. CSS Wizardy liked it and did a retweet of it. You should follow the approach of him and use more classes.


  1. Overall two whitespaces instead tabs for distances
  2. One whitespace between element and brace
  3. Line-Break between styles and new element
  4. Line-Break after closed brace
  5. Using HEX instead RGB for colors
  6. Convert HEX to RGB with Sass
    • bad example:     color: rgba(255,255,255,.3);
    • good example:   color: rgba(#000, .3);

Here’s the newest version:

I published my styleguide at github.

Do you have an improvement, supplement or want to discuss / talk with me? How do you handle your development-workflow or is your experience? You can write me a mail or find me on Twitter.

Leave a Reply

Your email address will not be published.