2/2/2017 - 2:54 PM


Custom Drupal 7 theme

Uses Node.js, Gulp, BrowserSync for Sass compiling, task running and Browser Syncing.


  • Node.js - Install node.js. If you have “homebrew” - $ brew install node
  • LibSass - Install libsass - $ npm install node-sass
  • Gulp.js - Install gulp globally - $ npm install gulp -g
  • BrowserSync - Install BrowserSync - $ npm install -g browser-sync


  • CD into the theme directory and run $ npm install to fetch all required dependencies.
  • For BrowserSync update proxy server in gulpfile.js to match your local environment. NOTE: BrowserSync will not work with default drupal @import. You will need "Link CSS" module to convert to <link> element.
  • CD into the theme directory and run “gulp” to start gulp watching, compiling and Browser Syncing.

Mobile First Design & Layout

This is a Mobile first design that uses "min-width".

Default styles will apply to mobile devices, everything up from there needs to be added by "@include mq($from: tablet) {...}".

  • Refer to "utils/variables.scss" for established breakpoints.

  • Add a "tabletish" breakpoint by: "@include mq($from: tablet) {...}".

  • Add a "large / desktop" by: "@include mq($from: desktop) {...}".



  • Avoid using HTML tags in CSS selectors
    • E.g. Prefer .o-modal {} over div.o-modal {}
    • Always prefer using a class over HTML tags (with some exceptions like CSS resets)
  • Don't use ids in selectors
    • #header is overly specific compared to, for example .header and is much harder to override
    • Read more about the headaches associated with IDs in CSS here.
  • Don’t nest more than 3 levels deep
    • Nesting selectors increases specificity, meaning that overriding any CSS set therein needs to be targeted with an even more specific selector. This quickly becomes a significant maintenance issue.
  • Avoid using nesting for anything other than pseudo selectors and state selectors.
    • E.g. nesting :hover, :focus, ::before, etc. is OK, but nesting selectors inside selectors should be avoided.
  • Don't !important
    • Ever.
    • If you must, leave a comment, and prioritise resolving specificity issues before resorting to !important.
    • !important greatly increases the power of a CSS rule, making it extremely tough to override in the future. It’s only possible to override with another !important rule later in the cascade.
  • Don’t use margin-top.
    • Vertical margins collapse. Always prefer padding-top ormargin-bottom on preceding elements
  • Avoid shorthand properties (unless you really need them)
    • It can be tempting to use, for instance, background: #fff instead of background-color: #fff, but doing so overrides other values encapsulated by the shorthand property. (In this case, background-image and its associative properties are set to “none.”
    • This applies to all properties with a shorthand: border, margin, padding, font, etc.


  • Two spaces for indenting code
  • Put spaces after : in property declarations
    • E.g. color: red; instead of color:red;
  • Put spaces before { in rule declarations
    • E.g. .o-modal { instead of .o-modal{
  • Write your CSS one line per rule
  • Add a line break after } closing rule declarations
  • When grouping selectors, keep individual selectors on a single line
  • Place closing braces } on a new line
  • Add a new line at the end of .scss files
  • Trim excess whitespace

In general follow Drupal Coding standards: https://www.drupal.org/coding-standards


  • All selectors are lower case, hyphen separated aka “spinal case” eg. .my-class-name
  • Always prefer Sass’s double-slash // commenting, even for block comments
  • Avoid specifying units for zero values, e.g. margin: 0; instead of margin: 0px;
  • Always add a semicolon to the end of a property/value rule
  • Use leading zeros for decimal values opacity: 0.4; instead of opacity: .4;
  • Put spaces before and after child selector div > span instead of div>span

Source: https://github.com/dropbox/css-style-guide