Baseline Docs

Modular CSS

The style sheets have been structured with modularity in mind to make it easy to add new features and components while ensuring the code base is easy to maintain over time. The structure has borrowed a lot from Jonathan Snook's SMACSS (Scalable and Modular CSS) approach. The stylesheets are broken down into four main sections:

Base

Base styles are the foundation of the site. In this directory you will find the following:

External Files	Refers to Normalize which takes the place of a traditional reset.
`_base.scss`	Style sheet where styles are applied to an element using the element selector.
`_settings.scss`	This stylesheet includes site-wide the colors, fonts, etc.
`_helpers.scss`	This is where you can place any Sass mixins, functions, or extends.
`_content.scss`	This is where universal text and content styles reside.

Layout

The layout styles are just that, they determine how main sections of the page are structured. Within this directory there are:

`_layout.scss`	This stylesheet is where the main container styles are stored such as `.l-container`, `header`, `footer`, etc.
`_grid.scss`	The grid, which is discussed in detail in the layout section of this guide can be changed to whatever is required by adjusting the variables at the top of the file. The calculations to build the grid are done through Sass.

Modules

Modules are discrete components of the page, such as navigation, alert dialogs, the photo viewer, etc. This section of the CSS is where you will most likely spend most of your time. Any new features, design elements, components will be added to this section.

States

State, as defined by SMACSS, augments and overrides all other styles. This section at the moment only contains styles that control the display state of an element such as whether or not is is hidden .is-hidden or is visible .is-visible. These can be expanded to also contain states such as whether an element is expanded or collapsed, or if the element is in an error state.

BEM

When creating new styles it is best to employ the BEM methodology.

BEM – meaning block, element, modifier – is a front-end naming methodology thought up by the guys at Yandex. It is a smart way of naming your CSS classes to give them more transparency and meaning to other developers. Harry Roberts of CSS Wizardry

As stated by Harry Roberts in his article MindBEMding:

.block represents the higher level of an abstraction or component.
.block__element represents a descendent of .block that helps form .block as a whole.
.block--modifier represents a different state or version of .block.

Styles should be broken down in this pattern. Here is an example of a module we'll call widget:

The main styles that control the widget will be attached to the root: widget.

If the widget module contains any custom element styles such as headings they can be scoped to the widget like this: widget__title or widget__heading.

If there are any modifications to the original widget such as a lighter background color, you can add a modifier to the root class which uses two dashes to signify its relationship: widget--light.

An example in CSS and SCSS (Sass 3.2.15 and below):

.widget { ... }

.widget__title { ... }

.widget__body { ... }

.widget--light { ... }

An example in SCSS (Sass 3.3 and above):

.widget {
  &__title { ... }

  &__body { ... }

  &--light { ... }
}

The resulting HTML would look like this:

<div class="widget">
  <p class="widget__title">...</p>
  <p class="widget__body">...</p>
</div>

And with the modifier:

<div class="widget widget--light">
  <p class="widget__title">...</p>
  <p class="widget__body">...</p>
</div>

Coding Styles

This section is optional, but when maintaining stylesheets for a large code base with multiple contributors, it helps to follow some basic guidelines to keep things consistent.

Coding Style

Use two spaces to indent.
Each property and value pair gets its own line.
Put spaces after : in property declarations.
Put spaces before { in rule declarations.
Use hex color codes #000 unless using rgba.
Use '//' for comment blocks (instead of '/* */'). Without single quotes, of course.

Here is good example syntax:

.styleguide-format {
  border: 1px solid #0f0;
  color: #000;
  background: rgba(0,0,0,0.5);
}

SCSS Style

Any $variable or @mixin that is used in more than one file should be put in the _settings.scss or _helpers.scss depending on their function.
Limit nesting as much as possible. Nesting too deep will lead to overly-specific selectors and make overriding them in the future problematic.
Always place @extend and @include statements on the first lines of a declaration block.

Here is an example:

.widget {
  @include clearfix;
  @extend .component; 
  border: 1px solid $border-color;
  background: $background-color;

  a {
    color: $widget-link-color;

    &:hover {
      color: darken($widget-link-color, 10%);
    }
  }
}

Code Styles