Structure

Rules

Main file

• The main file should begin with @charset
• The main file should act purely as a list of Imports otherwise- think of it like a table of contents
• Avoid sub-imports, these tend to muddy the waters
• Imports should follow the order:
  • variables
  • mixins
  • base
  • vendor fixes
  • components
  • utilities
  • sin bin

Selectors

• Selectors should be sorted first by priority (low - high), then alphabetically
• Descendant selectors should precede combination selectors
• Utility classes should never be modified from their defaults
• Classes that exist only to describe context (such as state) should only have contextual styles (that is, styles that only apply when the class is used in conjunction with another selector)

!important

The use of !important should be limited to utility classes, to ensure they always take priority. After all, if the utility class weren't meant to take priority, it shouldn't be used.

Variables

• Variables should be contained within a dedicated partial, which should be the first partial imported into the main file
• Group variables by type, sorted alphabetically

Extends & Includes (Mixins)

• Mixins should be grouped into partials inside mixins/ according to function (e.g. _clearfix.scss might include @clearfix_both, @clearfix_top and @clearfix_btm)
• Extends & Includes should precede all properties except all inside blocks
• Extends should come first
• Includes should follow Extends
• Extends & Includes should be sorted alphabetically

Base

See 'Base styles' page for more information.

Vendor fixes

Sometimes, external styles are brought into our environment from dependencies we have little or no control over, but need fixing. While it's still recommended to follow these guidelines as closely as possible, some rules are bound to just get in the way here. As long as all those fixes are kept together in this partial the rest of the stylesheet should remain clean and readable.

Components

Component styles should be broken up into separate partials inside components/.

Utilities

• Utilities should be grouped into partials inside utilities/ according to function (e.g. _margin.scss might include .mrg_x__reg, .mrg_t__lrg, etc.)

Sin bin

Sometimes, despite our best efforts, we wind up having to hack a solution together. When those situations arise, put them in the sin bin- this keeps all the rough edges together and encourages us to return later to clean them up. Try not to let the sin bin grow too big!

Directory structure

• css/
  • base/
    • _demarcating.scss
    • _embedded.scss
    • _forms.scss
    • _interactive.scss
    • _media.scss
    • _root.scss
    • _scripting.scss
    • _sectioning.scss
    • _tables.scss
    • _text_content.scss
    • _text_semantics.scss
  • components/
  • mixins/
  • utilities/
  • _layout.scss
  • _sin_bin.scss
  • _variables.scss
  • main.scss