Skip to content

CSS Styleguide and Coding Standards

David Baines edited this page May 6, 2016 · 5 revisions

Syntax and Formatting

  • Indents should be two spaces, not tabs.
  • Each selector should be on its own line.
  • Each attribute and value pair should be separated by one space.
  • Each attribute and value pair should be on its own line.
  • There should be a space between the last selector and the opening brace.
  • Selectors should always be classes. Data attribute selectors are also acceptable. Id selectors should only ever be used as a last resort.
  • Only use !important as an absolute last resort.
.example-2 .example-2--child {
  attribute: value;
  • Sass nesting shouldn't go deeper than three levels. Media-queries are the only exception.
.example {
  .example-1 {
    .example-2 {
      // max sass depth

      @include media-query(800px) {
        // media-query exception
  • Zeros should never have a unit. 0px, 0em, 0vh are all the same as just 0.
  • When trying to calculate a negative number, times the number by a negative number at the end, rather than adding a hyphen and stringifying the number. When sass gets "-25px" rather than -25px it can no longer perform further calculations against the number.
.example {
  top: 0px; // wrong!
  left: 0;  // right!
  margin-left: "-" + $value / 2; // wrong!
  margin-top: $value * -0.5; // right!


Katalyst use a custom flavour of BEM which essentially boils down to this:

.block--element__modifier {}

You can find more information on the Anatomy of a Component page.

Mixins and reuse

  • If you need browser prefixes for things, consider turning it in to a utility mixin. These normally live in /app/assets/stylesheets/ornament/utilities.
  • If you find yourself using a value more than three times, consider making it a variable at the top of the component file. If it's used over multiple components then it should be moved to the settings.scss file.
  • All colours should be defined in settings.scss

Logical media queries

  • You should not be adding styling and then removing them with media queries. Instead try to only add styles by mixing min and max media queries:
// wrong!
.example { 
  margin-top: 10px;
  @include media-query(800px) {
    margin-top: 0;

// right!
.example {
  @include media-query(800px, min) {
    margin-top: 10px;

Notable folder structure details

  • stylesheets/ornament/_settings.scss is where global site-wide sass variables are stored.
  • stylesheets/ornament/_core.scss is where vendor and mixin files get included.
  • stylesheets/ornament/_typography.scss is where the typography styles are kept.
  • stylesheets/ornament/utilities/ is the folder where mixins are kept.
  • stylesheets/aspects/ are for the content styling classes.
  • stylesheets/components/ are where the component styles go.
You can’t perform that action at this time.