HTML & Stylesheets

Guiding Principles

In general

• HTML is more maintainable when classes describe the content rather than apply a style
• HTML should be kept as minimal as possible - as few elements as possible and preferably just one class per element.

In this app

• Styles that are repeated throughout the app should use mixins (since they shouldn't be applied using presentational classes)
• The Sass files are organized using a modified 7-1 architecture (see modifications below)

Modified 7-1 Architecture

The Sass Guidelines outline the 7-1 Architecture for organizing Sass files in a project. This architecture uses 7 folders (abstracts, base, components, layout, pages, themes, and vendors) to organize everything and one file (main.scss) to bring everything together. In this project, we follow that structure, with the following modifications:

• abstracts is called utils, and mixins are broken out into their own files (so there is a mixins folder inside utils)
• as with all Rails projects, vendors is not inside the main stylesheets folder
• as with all Rails projects, main.scss is called application.scss
• there is no themes folder

Mixing vs Extending

Harry at CSS Wizardry gives a great explanation of this. His tl;dr:

Use @extend for same-for-a-reason; use a mixin for same-just-because.

There are three main ways to share groups of CSS properties among multiple elements.

Extend a Placeholder

.some_class { # or some other type of selector
  @extend %some-placeholder;
}

This should only be used when there is an inheritance type of relationship - that is, you're making an extension of something else. Harry gives an example where positive, negative, and neutral buttons are an extension of a plain button.

Extend a Class

.some_class { # or some other type of selector
  @extend .some_other_class;
}

You should probably never do this. Chris at 8 Gram Gorilla describes how the properties listed under every single occurrence of .some_other_class will be copied in, even though you probably didn't intend for that to happen.

Include a Mixin

.some_class { # or some other type of selector
  @include some-mixin();
}

This is my default approach. Harry uses an example where the default typography for a webpage requires both the font family and font weight to be set, and these need to be applied to many selectors.

A mixin with no parameters is like a convenient copy and paste. This leads to two common concerns:

1. the CSS output by Sass won't be "dry" but it doesn't matter from a development perspective because we are only specifying it in one place in our source code (the Sass files)
2. the "wetness" in the CSS also doesn't matter from a performance / file size perspective because "Gzip favours repetition, so that will almost entirely negate the costs of the slight added filesize"

tl;dr

Use @extend if you are extending something else, use a mixin if you want to include some set of properties. Only @extend placeholders, never class selectors.