A Simple SCSS Architecture, and Best Practice Playbook

#modular css#architecture#best practice#styleguide

I decided to write my own playbook that covers Scss file structure standards - I will probably add to this as I go.

I have spent a lot of time looking at different Sass/Scss formatting, naming, and architecture standards. The bible probably being Hugo Giraudel’s Sass Guidelines - Although very comprehensive, well maintained, and well written the standards were a little too thorough for my needs.

File structure

  • Categorized styles; making them easier to maintain
  • 5-1 Pattern architecture; for clearer organization (based on the 7-1 Pattern)
  • Clear delineation between grouped and associated rules
  • Encourages common style, components and variable (inline with Atomic Design)
  • Modular style management that facilitates Styleguide Driven Development
  • Reusable approach
scss/                               # Import all ‘-dir.scss’ files
|
|- abstracts/                   
|	|- __abstracts-dir.scss     # Import all abstracts .scss files
|	|- _fonts.scss              # Font Import
|	|- _mixins.scss             # Scss Mixins
|	|- _variables.scss          # Scss Variables
|
|- base/
|	|- __base-dir.scss          # Import all base .scss files
|	|- _reset.scss              # Custom Reset/Normalize
|	|- _typography.scss         # Typography Rules
|	…                           # Etc.
|
|- components/
|	|- __components-dir.scss    # Import all components .scss files
|	|- _button.scss             # Button Styles
|	|- _input.scss              # Input Styles
|	|- _modal.scss              # Modal Styles
|	…	                    # Etc.
|
|- layouts/
|	|- __layouts-dir.scss       # Import all layouts .scss files
|	|- _footer.scss             # Footer Styles
|	|- _main-navigation.scss    # Main Navigation Styles
|	…                           # Etc.
|
|- vendor/
|	|- __vendor-dir.scss        # Import vendor folders
|	|- bourbon/                 # Bourbon
|	|- fontawesome/             # Font Awesome
|	|- neat/                    # Bourbon Neat
|	|- normalize/               # Normalize
|	…                           # Etc.
|
`styles.scss                        # Main Scss File

Styles.scss

  • Charset should be included
  • Only directory files -dir.scss files should be imported
  • Changes should not be made to this file
  • Filename is always ‘styles’ as it is a compiled file containing multiple stylesheets
  • All files except /styles.scss require an underscore at the beginning of each filename
@charset 'utf-8';

//Vendor
@import "vendor/__vendor-dir";

//Abstracts
@import "abstracts/__abstracts-dir";

//Base Styles
@import "base/__base-dir";

//Components
@import "components/__components-dir";

//Layout
@import "layouts/__layouts-dir";

Vendors

  • Use the __vendors-dir.scss
  • All 3rd-party vendor tools (frameworks, libraries, helpers) should be separated into folders
  • Only the 3rd-party master file for each vendor tool should be imported
  • One @import per line
  • Vendor tool version number should be included in an inline comment
  • The following are imported as standard: 
/*
This file is used to contain all vendor imports.
*/

//Import Vendor files
@import "bourbon/bourbon"; //4.2.6
@import "neat/neat"; //1.7.2
@import "fontawesome/font-awesome"; //4.4.0
@import "normalize/normalize"; //3.0.3
/* Additonal Vendor Tools */

Abstracts

  • Use the __abstracts-dir.scss
  • Helper functions and non–output snippets only (font-face imports, reusable mixins, global variables, colors, etc.)
  • One @import per line
  • The following files are imported as standard ready for customization:
    • _fonts.scss
    • _mixins.scss
    • _variables.scss
  • Abstracts should be grouped with an inline comment title
  • One abstract per line
  • C-style comments can be used to add context
  • Files with no data should not be removed
/*
This file is used to contain all abstracts imports.
Files inside this folder can contain abstract settings, helpers or functions. They have no direct output.
*/

//Import Abstracts files
@import "fonts";
@import "mixins";
@import "variables";

Example of _fonts.scss

//Font Imports
@include font-face("Open Sans", "../fonts/open-sans/OpenSans-Light", 300, $file-formats: ttf);

Example of _variables.scss

//Variables

//Colors
$red: #EF4B46;
$blue: dodgerblue;
$yellow: rgba(239, 181, 67, 1);

Base

  • Use the __base-dir.scss
  • Global styles are imported here
  • A custom reset file can be added to override normalize
  • Typography (h1-6, p, a, blockquote, etc.) should be included
  • Globally defined tags (body, main, article, div, etc.) should also be included
  • One @import per line
  • The following files are imported as standard ready for customization:
    • _reset.scss
    • _typography.scss
  • Additional base stylesheets can be imported
/*
This file is used to contain all base imports.
Files inside this folder can contain global styles used in the project.
*/

//Import Base files
@import "reset";
@import "typography";
/* Additonal Base Stylesheets */

Components

  • Use the __components-dir.scss
  • Micro level reusable components are imported here
  • Each component does one thing and one thing only
  • Components are re-usable across the project
  • Components are independent
  • One @import per line
  • Each stylesheet contains all component styles, variations and states
/*
This file is used to contain all component imports.
Files inside this folder should contain all styles relating to a reusable component.
*/

//Import Component files
@import "button";
@import "input";
@import "modal";
/* Additonal Component Stylesheets */

Example of _button.scss

//Button
.btn {
  display: block;
  color: $red;
  border-color: transparent;

  &:disabled, 
  &.disabled {  
    pointer-events: none;
  }
}

//Alternate Button
.btn.alt {
  color: $blue;
}

Layouts

  • Use the __layouts-dir.scss
  • Unique combinations of components and base styles are imported here
  • One @import per line
  • Each stylesheet contains all component style overrides, and specific layout only attributes
/*
This file is used to contain all component imports.
Files inside this folder can contain specific element styles and layout. 
*/

//Import Layout files
@import "main-navigation";
@import "footer";
//Additonal Layouts Stylesheets

Example of _footer.scss

//Footer
footer {
  @include display(flex);
  @include justify-content(space-between);
  width: 100%;

  &.dark {
    background: rgba(0,0,0,1);  
  }
}

//Footer Buttons
footer .btn {  
  @include flex(0 0 auto);
  color: $red; 
}

Additional Stylesheets

  • Ensure additional stylesheets are added in the appropriate folder and imported correctly in the directories -dir.scss file.

Example of __components-dir.scss

/*
This file is used to contain all component imports.
Files inside this folder should contain all styles relating to a reusable component.
*/

//Import Component files
@import "button";
@import "input";
@import "modal";
@import "accordion";
@import "dropdown";
@import "carousel";
@import "form";
@import "icon";
@import "label";

Example of __layouts-dir.scss

/*
This file is used to contain all component imports.
Files inside this folder can contain specific element styles and layout. 
*/

//Import Layout files
@import "main-navigation";
@import "footer";
@import "sidebar";
@import "masthead";

Writing Rules

  • Two (2) spaces indents, no tabs
  • Single line whitespace between rules
  • No more than 2 levels of nesting
  • Structure for each element is as follows:
    • Style the element itself
    • Style the element’s variants, modifiers, and states
    • Styles the element’s descendants (i.e. children)

Example of _footer.scss

//Footer
footer {
  @include display(flex);
  @include justify-content(space-between);
  width: 100%;

  &.dark {
    background: rgba(0,0,0,1);  
  }

  .container {
    padding: 1em;
  }
}

//Footer Buttons
footer .btn {  
  @include flex(0 0 auto);
  color: $red; 
}

//Footer Copyright Message
footer .copyright {  
  text-align: center; 
}

Commenting

  • CSS rules that aren’t obvious should be commented
  • C-style comments should be utilized for a large block of text
  • Inline (C++-style) comments should be utilized for single line comments
  • No comments should appear in a production environment – All CSS should be minified, stripping comments in the process, before being deployed.
// This element will move when it’s parent is active

/*
This file is used in all instances of a button
Colors used within the button.scss file are defined here
*/

Download

Fork on Github

You can fork this architeture from github.

Important

Jekyll is used to compile the scss so the styles.scss file sits in /css.

The following lines of code in the _config.yml file tell Jekyll what to compile.

sass:
sass_dir: assets/_scss # Scss location
style: :compressed

I have added a few example stylesheets to /base, /components, and /layouts too.