elyseholladay/1-theory.md

## 1-theory.md

      
    Raw
  

              1-theory.md
            
          
    Theory

We subscribe to the following high-level theories in our Sass code:
Keep functional Sass separate from presentational styles

Keeping functional Sass separate from presentational Sass is important in order to maintain readability, search-ability and scaleability of your code. Patterns like placing mixins in the same file as presentational Sass leads to overly complex files to scan and opportunities for accidental pollution of your processed CSS.
Source: http://gist.io/4436524
Sass is a CSS assistant.

"Sass is not a replacement for CSS, it’s more like having a CSS assistant who will help you write your code. So when you’re ready to really put it to work I recommend occasional sanity checks on the resulting CSS to see if this “assistant” has created too much repeated code or if the selectors are getting too complicated. Refactoring your Sass will help keep your code clean and you’ll start learning how you can make the best use of it."
Source: http://atomeye.com/sass-and-compass.html

  
## 2-technical.md

      
    Raw
  

              2-technical.md
            
          
    Technical

When coding, we try to follow these patterns:
Namespace modules one level to eliminate conflicts.

“Typically I will name a layout Sass file after the semantic meaning of the view. In an MVC app, a great convention is either use the name of the controller or thelayout template file and append the word _container or _layout. An example would be sessions_container.scss or sessions_layout.scss. To keep things simple, I would then scope all the presentational Sass in a document by the same name, .sessions_container {}. Using this class name can be achieved by dynamically adding the class to the <body> tag when the view renders, creating multiple layout templates with a static class applied or whatever works for you.
Our #1 goal with layout Sass files is to place control of the template UI into the hands of the CSS itself rather then depending on presentational classes in our markup. This becomes even more important when considering mobile/content first and responsive web design strategies.”
...but use minimal nesting to eliminate specificity hell.

Use an extend to reuse code with no output, and a mixin to alter variables

Extending silent classes (%placeholder) should only be done when the element being extended has a relationship with the placeholder.
Use classes over elements or IDs.

IDs should only be used for unique elements that need a JavaScript hook. If it's a consistent JavaScript function, prefix it with .js-.
Check the existing codebase before adding a new variable, mixin, or extend.

Add inline documentation where necessary.

.class {
    width: 60%; // fallback width for IE
}

Naming Conventions


Choose human readable over acronyms
Shared or global name to specific name
Never use display/functionality in names (e.g. .orange-box, .form-float-left)
more to come here.

Code Standards

In code reviews/linting we expect the following syntactical standards:

Use four-space indentation, preferably with an editor config to keep them consistent.
Put spaces after the colon in property declarations.

Correct:
display: block;
Incorrect:
display:block;

Put spaces before { in rule declarations.

Correct:
.class {}
Incorrect
.class{}

Place closing braces of declaration blocks on a new line.

Correct:
.class {
  styles: go-here;
}

Incorrect:
.class {
  styles: go-here; }


Put one property per line.

Correct:
.class {
  display: block;
  color: red;
}

Incorrect:
.class {
  display: block; color: red;
}


When grouping selectors, keep individual selectors to a single line.

Correct:
.class,
.box {
  styles: go-here;
}

Incorrect:
.class, .box {
  styles: go-here;
}


Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;


## 3-commenting.md

      
    Raw
  

              3-commenting.md
            
          
    Commenting


Use /* */ comments for instructions visible in the output.


Use non-output // comments for usage, edge cases, TODOs.


Each .scss file page header should have an output-visible comment header with the name of the module, info on what the module is and a list of locations where the module is/can be used, any instructions on using the module (if it a utility/mixin/helper), the expected HTML (for style guide generation) and any TODOs.


Example for a helper/pattern/component:
/* ---------------------------------------------------------- */ 
/* PATTERN: BUTTONS ----------------------------------------- */ 
/* ---------------------------------------------------------- */ 
/* The button pattern can be used on any www RMN site,
   in any larger component or module.                         

   A button consists of a single, pressable element, either
   a <button>, <input>, or <a> with additional JS; button text
   with or without iconography; a hover, focus, and a disabled
   state, and CSS transitions.                                */

/* EXPECTED HTML -------------------------------------------- */
/* In preferred order of usage:                               */

/* As a link:
   <a href="#" class="button [additional classes]“>Text</a>   */

/* As a button element:
   <button class="button [additional classes]“>Text</button>  */

/* As an input:
   <input type="submit" value='input[type="submit"]'
     class="button [additional classes]“/>                    */

/* There are multiple types of buttons, as follows:

   Default:      .button
   Secondary:    .button .button--secondary
   Disabled:     .button[disabled=disabled]
   Code Button:  .button .button--code
   Red Button:   .button .button--red
   Blue Button:  .button .button--blue
   White Button: .button .button--white-outline

   If you need to create a new button type, [instructions]    */

/* TO DO LIST ----------------------------------------------- */
/* TODO  Create placeholder extends instead of using .button
         in the HTML going forward.                           */

Example for a page module:
/* ---------------------------------------------------------- */ 
/* MODULE: HEADER ------------------------------------------- */ 
/* ---------------------------------------------------------- */ 
/* The header module appears on every www RMN property.       */
/* For mdot headers, see /mobile/gui/sass/header.scss         

   It consists of the following components:
   _menu-utility.scss (blog link, hearts/stars, account, i18n),
   site-navigation (logo and search form) - in this file,
   and _menu-site.scss (browse & ideas dropdown)              */

/* EXPECTED HTML -------------------------------------------- */
/* <header id="top" role="banner" class="site-header">
      [menu-utility]
      [site-header-main]
      [site-navigation]
      [toggles]
      [form-search]
      [menu-site]
   </header>                                                  */

/* TO DO LIST ----------------------------------------------- */
/* TODO  break out .site-navigation into a new file           */ 
/* TODO  The styling for this will need to be slightly
         refactored when we are able to get away from our old
         CMS placements.                                      */