Groundwork Documentation

  1. CSS Organisation
  2. Syntax
  3. Principles

1. CSS Organisation

The CSS organisation is based on Inverted Triangle CSS by Harry Roberts, from the most applicable styles (variables, base) to specific modules (objects and components) and to very specific trumping utilities and shameful hacks.

  1. Variables: global variables and site-wide settings eg responsive.css
  2. Base: unclassed HTML elements eg a {}
  3. Objects: cosmetic-free objects, abstractions, and design patterns eg o-media.css
  4. Components: discrete, complete chunks of UI eg button.css
  5. Utilities: high-specificity, very explicit selectors that trump everything else. Overrides and helper classes eg .u-hiddenvisually {}
  6. Shameful: temporarily disorganised CSS lives in shame.css

Rainbow coloured Inverted CSS Triangle

All files relating to a particular module go in that module folder: eg JavaScript, PNGs, SVGs, CSS and the Handlebars test snippet.

Simplified directory structure

├── assets
│   ├── css
│   │   ├── settings
│   │   └── shame.css
│   ├── images
│   └── js
└── modules
    ├── components
    │   └── forms
    |       └── button
    ├── objects
    └── utilities

2. Syntax

Modified BEM syntax

In short, this:

.block {}
.block__element {}
.block--modifier {}

The block is the module (object or component), the block__element is a descendant of that module and the block--modifier is a variation on that module.

For example:

.search {}
.search__field {}
.search--full {}

BEM ground rules


To add clarity to the block__element--modifier convention, use “namespacing”: prefixing a module with an identifying character:

.o-object {}
.component {}
.u-utility {}
.js-javascript {}
._-hack {}
.is-state {}, has-state {}

For example, .button {}, .o-media {}, .u-cf, _-messy-hack. The odd one is out component – no c- prefix here, because components are the most common type of module, and if it doesn’t have a prefix, it’ll be a component.

3. Principles of Modular CSS

Modular CSS is a way of organising your CSS, and other assets, into discrete and re‑usable chunks.

Some key principles

Build what you need. Start simple. Stay simple.

  1. ID-based CSS selectors must not be used. IDs have a much higher specificity, which can then lead to all sorts of specifity wars when trying to apply a style.
  2. HTML elements must not be used in CSS selectors. This means classes can be applied to any element eg <input class="button" type="submit"> and <button class="button">pushme</button>.
  3. Only use the module for one bit of functionality. This is the Single Responsibility Principle.
  4. Class names should be functional & independent of content. Again, this makes a module re-usable in different contexts.
  5. Modules must have unique names.


A guiding principle in Kanban development is to make work visible (Kanban 看板 literally means billboard in Japanese). To this end, use a styleguide, from the beginning. Groundwork recommends Fractal, a magnificent, automated, styleguide builder.

Credits & further reading