SCSS CSS

Styling approach

• In general we try to keep html markup as minimal as possible. We use helper classes sparingly and instead rely on SCSS mixins and variables to keep our code clean.
• Use content descriptive class names to define and namespace larger content blocks
  • Content descriptive means related to the content not the visual layout.
    • Avoid classes that describe the visual design: .top-blue-box
    • Instead describe the content: .feature-header
  • Larger content block could be a <section> element.
    • Try to rely on html elements to define the content within. Classes are ok, but try and be minimal.
• Generic container classes like: .wrapper , .container, .outer are ok for "wrap it in a div and call it a day" situations.
• Avoid margin-top. We try to set a standard where margins are set on a sections bottom, OR a .section-spacer element is used. This way if section elements are not present, they consistently push content below them down ensuring proper spacing.
• Avoid using !important. Only use !important if there is no alternative.

CSS declaration order

• Based on https://9elements.com/css-rule-order/
• In general: most important in terms of layout to least important.

.classname {
  @include spacing;                /*   1. SCSS Includes (non responsive)  */
  position: absoute;               /*   2. Position and Layout             */
  top: 0;                          /*      Position and Layout             */
  left: 10px;                      /*      Position and Layout             */
  display: flex;                   /*   3. Display and Visibility          */
  overflow: hidden;                /*   4. Overflow and Clipping           */
  margin: 20px;                    /*   5. Box Model                       */
  padding: 20px;                   /*      Box Model                       */
  border: 1px solid black;         /*      Box Model                       */
  transition: all 0.2s ease-in;    /*   6. Animation                       */
  background-color: pink;          /*   7. Background                      */
  font-size: 2em;                  /*   8. Typography                      */
  color: black;                    /*      Typography                      */
  @include breakpoint(small) {     /*   9. Responsive rules                */
    background-color: yellow;      /*      Responsive rules                */
  }                                /*      Responsive rules                */
  a {                              /*  10. Nested rules                    */
    text-decoration: underline;    /*      Nested rules                    */
  }                                /*      Nested rules                    */
  &:hover {                        /*  11. Pseudo rules                    */
    background: aqua;              /*      Pseudo rules                    */
  }                                /*      Pseudo rules                    */
}

Responsive

• We use a 'breakpoint' mixin to handle responsive SCSS rules.
• Use SCSS media query rules will be nested within a selector's default rule.

@mixin breakpoint($point) {
  @if $point == large {
    @media (max-width: $large - 1px) {
      @content;
    }
  } @else if $point == medium {
    @media (max-width: $medium - 1px) {
      @content;
    }
  } @else if $point == mediumup {
    @media (min-width: $medium) {
      @content;
    }
  } @else if $point == small {
    @media (max-width: $small - 1px) {
      @content;
    }
  } @else {
    @media (max-width: $point) {
      @content;
    }
  }
}

.element {
  font-size: 20px;
  @include breakpoint(small) {
    font-size: 10px;
  }
}
/* 
In this example we will set `.element`'s default font size to 20px and reduce it to 10px for small screens:
*/

Helper classes

• Use helper classes sparingly.
• Generally we setup helper classes for common typography, section spacing, high level layout rules (page containers etc)

Example Markup and SCSS

<div class="page-home">
  <div class="page-container">
   <section class="hero">
     <div class="wrapper">
       <h1>{{page_title}}</h1>
       <a href="#" class="button">{{button_text}}</a>
     </div>
   </section>
   <section class="main-section">
     <div class="wysiwyg">
      {{page_content}}
     </div>
   </section>
  </div>
</div>

.page-home {
  /* .page-content is a global helper class */
  .hero {
    .wrapper {
      position: relative;
      display: flex;
      width: 100%;
      /* breakpoint is a global mixin */
      @include breakpoint(small) {
        display: block;
      }
      h1 {
        color: red;
        @include breakpoint(small) {
          color: blue;
        }
      }
    }
  }
  .top-section {
    /* .wysiwyg is a global helper class */
  }
}