davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang=fr>
<!-- Has to be within the first 1024 bytes, hence before the <title>
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset=utf-8>
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name=viewport content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no">
<!-- Required to make a valid HTML5 document. -->
<title>Sass Guidelines (archive) — David Larlet</title>
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<link rel="mask-icon" href="/static/david/icons/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/static/david/icons/favicon.ico">
<meta name="apple-mobile-web-app-title" content="David Larlet">
<meta name="application-name" content="David Larlet">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/static/david/icons/browserconfig.xml">
<meta name="theme-color" content="#f0f0ea">
<!-- That good ol' feed, subscribe :p. -->
<link rel=alternate type="application/atom+xml" title=Feed href="/david/log/">

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="http://sass-guidelin.es/">

<style>
/* http://meyerweb.com/eric/tools/css/reset/ */
html, body, div, span,
h1, h2, h3, h4, h5, h6, p, blockquote, pre,
a, abbr, address, big, cite, code,
del, dfn, em, img, ins,
small, strike, strong, tt, var,
dl, dt, dd, ol, ul, li,
fieldset, form, label, legend,
table, caption, tbody, tfoot, thead, tr, th, td,
article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup,
menu, nav, output, ruby, section, summary,
time, mark, audio, video {
  margin: 0;
  padding: 0;
  border: 0;
  font-size: 100%;
  font: inherit;
  vertical-align: baseline;
}
/* HTML5 display-role reset for older browsers */
article, aside, details, figcaption, figure,
footer, header, hgroup, menu, nav, section { display: block; }
body { line-height: 1; }
blockquote, q { quotes: none; }
blockquote:before, blockquote:after,
q:before, q:after {
  content: '';
  content: none;
}
table {
  border-collapse: collapse;
  border-spacing: 0;
}

/* http://practicaltypography.com/equity.html */
/* https://calendar.perfplanet.com/2016/no-font-face-bulletproof-syntax/ */
/* https://www.filamentgroup.com/lab/js-web-fonts.html */
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff') format('woff');
  font-weight: 300;
  font-style: italic;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff') format('woff');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'ConcourseT3';
  src: url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff2') format('woff2'),
       url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}


/* http://practice.typekit.com/lesson/caring-about-opentype-features/ */
body {
  /* http://www.cssfontstack.com/ Palatino 99% Win 86% Mac */
  font-family: "EquityTextB", Palatino, serif;
  background-color: #f0f0ea;
  color: #07486c;
  font-kerning: normal;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: subpixel-antialiased;
  text-rendering: optimizeLegibility;
  font-variant-ligatures: common-ligatures contextual;
  font-feature-settings: "kern", "liga", "clig", "calt";
}
pre, code, kbd, samp, var, tt {
  font-family: 'TriplicateT4c', monospace;
}
em {
  font-style: italic;
  color: #323a45;
}
strong {
  font-weight: bold;
  color: black;
}
nav {
  background-color: #323a45;
  color: #f0f0ea;
  display: flex;
  justify-content: space-around;
  padding: 1rem .5rem;
}
  nav:last-child {
    border-bottom: 1vh solid #2d7474;
  }
  nav a {
    color: #f0f0ea;
  }
  nav abbr {
    border-bottom: 1px dotted white;
  }

h1 {
  border-top: 1vh solid #2d7474;
  border-bottom: .2vh dotted #2d7474;
  background-color: #e3e1e1;
  color: #323a45;
  text-align: center;
  padding: 5rem 0 4rem 0;
  width: 100%;
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
}
  h1.single {
    padding-bottom: 10rem;
  }
  h1 span {
    position: absolute;
    top: 1vh;
    left: 20%;
    line-height: 0;
  }
    h1 span a {
      line-height: 1.7;
      padding: 1rem 1.2rem .6rem 1.2rem;
      border-radius: 0 0 6% 6%;
      background: #2d7474;
      font-size: 1.3rem;
      color: white;
      text-decoration: none;
    }
h2 {
  margin: 4rem 0 1rem;
  border-top: .2vh solid #2d7474;
  padding-top: 1vh;
}
h3 {
  text-align: center;
  margin: 3rem 0 .75em;
}
hr {
  height: .4rem;
  width: .4rem;
  border-radius: .4rem;
  background: #07486c;
  margin: 2.5rem auto;
}
time {
  display: bloc;
  margin-left: 0 !important;
}
ul, ol {
  margin: 2rem;
}
ul {
  list-style-type: square;
}
a {
  text-decoration-skip-ink: auto;
  text-decoration-thickness: 0.05em;
  text-underline-offset: 0.09em;
}
article {
  max-width: 50rem;
  display: flex;
  flex-direction: column;
  margin: 2rem auto;
}
  article.single {
    border-top: .2vh dotted #2d7474;
    margin: -6rem auto 1rem auto;
    background: #f0f0ea;
    padding: 2rem;
  }
  article p:last-child {
    margin-bottom: 1rem;
  }
p {
  padding: 0 .5rem;
  margin-left: 3rem;
}
  p + p,
  figure + p {
    margin-top: 2rem;
  }

blockquote {
  background-color: #e3e1e1;
  border-left: .5vw solid #2d7474;
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 1rem;
  margin: 1.5rem;
}
  blockquote cite {
    font-style: italic;
  }
  blockquote p {
    margin-left: 0;
  }

figure {
  border-top: .2vh solid #2d7474;
  background-color: #e3e1e1;
  text-align: center;
  padding: 1.5rem 0;
  margin: 1rem 0 0;
  font-size: 1.5rem;
  width: 100%;
}
  figure img {
    max-width: 250px;
    max-height: 250px;
    border: .5vw solid #323a45;
    padding: 1px;
  }
figcaption {
  padding: 1rem;
  line-height: 1.4;
}
aside {
  display: flex;
  flex-direction: column;
  background-color: #e3e1e1;
  padding: 1rem 0;
  border-bottom: .2vh solid #07486c;
}
  aside p {
    max-width: 50rem;
    margin: 0 auto;
  }

/* https://fvsch.com/code/css-locks/ */
p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
  font-size: 1rem;
  line-height: calc( 1.5em + 0.2 * 1rem );
}
h1 {
  font-size: 1.9rem;
  line-height: calc( 1.2em + 0.2 * 1rem );
}
h2 {
  font-size: 1.6rem;
  line-height: calc( 1.3em + 0.2 * 1rem );
}
h3 {
  font-size: 1.35rem;
  line-height: calc( 1.4em + 0.2 * 1rem );
}
@media (min-width: 20em) {
  /* The (100vw - 20rem) / (50 - 20) part
     resolves to 0-1rem, depending on the
     viewport width (between 20em and 50em). */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.5em + 0.2 * (100vw - 50rem) / (20 - 50) );
    margin-left: 0;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.2em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.3em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.4em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
}
@media (min-width: 50em) {
  /* The right part of the addition *must* be a
     rem value. In this example we *could* change
     the whole declaration to font-size:2.5rem,
     but if our baseline value was not expressed
     in rem we would have to use calc. */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * 1rem );
    line-height: 1.5em;
  }
  p, li, pre, details {
    margin-left: 3rem;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * 1rem );
    line-height: 1.2em;
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * 1rem );
    line-height: 1.3em;
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * 1rem );
    line-height: 1.4em;
  }
  figure img {
    max-width: 500px;
    max-height: 500px;
  }
}

figure.unsquared {
  margin-bottom: 1.5rem;
}
  figure.unsquared img {
    height: inherit;
  }


@media print {
  body { font-size: 100%; }
  a:after { content: " (" attr(href) ")"; }
  a, a:link, a:visited, a:after {
    text-decoration: underline;
    text-shadow: none !important;
    background-image: none !important;
    background: white;
    color: black;
  }
  abbr[title] { border-bottom: 0; }
  abbr[title]:after { content: " (" attr(title) ")"; }
  img { page-break-inside: avoid; }
  @page { margin: 2cm .5cm; }
  h1, h2, h3 { page-break-after: avoid; }
  p3 { orphans: 3; widows: 3; }
  img {
    max-width: 250px !important;
    max-height: 250px !important;
  }
  nav, aside { display: none; }
}

ul.with_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_columns {
    column-count: 2;
  }
}
@media (min-width: 50em) {
  ul.with_columns {
    column-count: 3;
  }
}
ul.with_two_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_two_columns {
    column-count: 1;
  }
}
@media (min-width: 50em) {
  ul.with_two_columns {
    column-count: 2;
  }
}

.gallery {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-around;
}
  .gallery figure img {
    margin-left: 1rem;
    margin-right: 1rem;
  }
  .gallery figure figcaption {
    font-family: 'ConcourseT3'
  }

footer {
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
  border-top: 3px solid white;
  padding: 4rem 0;
  background-color: #07486c;
  color: white;
}
  footer > * {
    max-width: 50rem;
    margin: 0 auto;
  }
  footer a {
    color: #f1c40f;
  }
  footer .avatar {
    width: 200px;
    height: 200px;
    border-radius: 50%;
    float: left;
    -webkit-shape-outside: circle();
    shape-outside: circle();
    margin-right: 2rem;
    padding: 2px 5px 5px 2px;
    background: white;
    border-left: 1px solid #f1c40f;
    border-top: 1px solid #f1c40f;
    border-right: 5px solid #f1c40f;
    border-bottom: 5px solid #f1c40f;
  }
</style>

<h1>
  <span><a id="jumper" href="#jumpto" title="Un peu perdu ?">?</a></span>
  Sass Guidelines (archive)
  <time>Pour la pérennité des contenus liés. Non-indexé, retrait sur simple email.</time>
</h1>
<section>
  <article>
    <h3><a href="http://sass-guidelin.es/">Source originale du contenu</a></h3>
    <h2 class="baseline">An opinionated styleguide for writing sane, maintainable and scalable Sass.</h2>

<div class="translation-warning">
    <p>The Sass Guidelines project has been translated into several languages by <a target="_blank" href="https://github.com/HugoGiraudel/sass-guidelines/blob/gh-pages/_data/languages.yml">generous contributors</a>. Open the <button data-toggle="aside" class="link-like" role="button" type="button">options panel</button> to switch.</p>
</div>

<h1 id="about-the-author">About the author</h1>

<p>My name is <a href="http://hugogiraudel.com">Hugo Giraudel</a>, I am a French front-end developer based in Berlin, Germany. I have been writing Sass for over two years now and am the author of Sass-related projects such as <a href="http://sassdoc.com">SassDoc</a> and <a href="http://sass-compatibility.github.io">Sass-Compatibility</a>. I also wrote a book about CSS (in French) entitled <a href="http://www.amazon.fr/dp/2212140231">CSS3 Pratique du Design Web</a>.</p>

<p>I have also written a couple of Sass libraries, mostly for the heck of it: <a href="https://github.com/HugoGiraudel/SassyJSON">SassyJSON</a>, <a href="http://sassylists.com">SassyLists</a>, <a href="https://github.com/HugoGiraudel/SassySort">SassySort</a>, <a href="https://github.com/HugoGiraudel/SassyCast">SassyCast</a>, <a href="https://github.com/HugoGiraudel/SassyMatrix">SassyMatrix</a>, <a href="https://github.com/HugoGiraudel/SassyBitwise">SassyBitwise</a>, <a href="https://github.com/HugoGiraudel/SassyIteratorsGenerators">SassyIteratorsGenerators</a>, <a href="https://github.com/HugoGiraudel/SassyLogger">SassyLogger</a>, <a href="https://github.com/HugoGiraudel/SassyStrings">SassyStrings</a> and <a href="https://github.com/HugoGiraudel/SassyGradients">SassyGradients</a>.</p>

<h1 id="contributing">Contributing</h1>

<p>Sass Guidelines is a free project that I maintain in my spare time. Needless to say, it is quite a large amount of work to keep everything up-to-date, documented and relevant. Obviously, knowing that you liked this styleguide is already much appreciated!</p>

<p>Now if you feel like contributing, please know that tweeting about it, spreading the word, or fixing a tiny typo by opening an issue or a pull-request on the <a href="https://github.com/HugoGiraudel/sass-guidelines">GitHub repository</a> would be great!</p>

<p>Last but not least before we start: if you enjoyed this document, or if it is useful for you or your team, please consider supporting it!</p>

<h1 id="table-of-contents">Table of Contents</h1>

<h1 id="about-sass">About Sass</h1>

<p>This is how <a href="http://sass-lang.com">Sass</a> describes itself in its <a href="http://sass-lang.com/documentation/file.SASS_REFERENCE.html">documentation</a>:</p>

<blockquote>
  <p>Sass is an extension of CSS that adds power and elegance to the basic language.</p>
</blockquote>

<p>Sass’s ultimate objective is to fix CSS’s flaws. CSS, as we all know, is not the best language in the world <sup>[citation needed]</sup>. While very simple to learn, it can quickly get quite messy, especially on large projects.</p>

<p>This is where Sass comes in, as a meta-language, to improve CSS’s syntax in order to provide extra features and handy tools. Meanwhile, Sass wants to be conservative regarding the CSS language.</p>

<p>The point is not to turn CSS into a fully-featured programming language; Sass only wants to help where CSS fails. Because of this, getting started with Sass is no harder than learning CSS: it simply adds a couple of extra features on top of it.</p>

<p>That being said, there are many ways to use these features. Some good, some bad, some unusual. These guidelines are meant to give you a consistent and documented approach to writing Sass code.</p>

<h6 id="further-reading">Further reading</h6>

<h2 id="ruby-sass-or-libsass">Ruby Sass or LibSass</h2>

<p><a href="https://github.com/hcatlin/sass/commit/fa5048ba405619273e474a50400c7243fbff54fe">Sass’s first commit</a> goes back as far as late 2006, over 8 years ago. Needless to say it has come a long way since then. Initially developed in Ruby, varied ports popped up here and there. The most successful one, <a href="https://github.com/sass/libsass">LibSass</a> (written in C) is now close to being fully compatible with the original Ruby version.</p>

<p>In 2014, <a href="https://github.com/sass/libsass/wiki/The-LibSass-Compatibility-Plan">Ruby Sass and LibSass teams decided to wait for both versions to sync up before moving forward</a>. Since then, LibSass has been actively releasing versions to have feature-parity with its older brother. The last remaining inconsistencies are gathered and listed by myself under the <a href="http://sass-compatibility.github.io">Sass-Compatibility</a> project. If you are aware of an incompatibility between the two versions that is not listed, please be kind enough to open an issue.</p>

<p>Coming back to choosing your compiler. Actually, it all depends on your project. If it is a Ruby on Rails project, you better use Ruby Sass, which is perfectly suited for such a case. Also, be aware that Ruby Sass will always be the reference implementation and will always lead LibSass in features.</p>

<p>On non-Ruby projects that need a workflow integration, LibSass is probably a better idea since it is mostly dedicated to being wrapped. So if you want to use, let’s say Node.js, <a href="https://github.com/sass/node-sass">node-sass</a> is all chosen.</p>

<h6 id="further-reading-1">Further reading</h6>

<h2 id="sass-or-scss">Sass or SCSS</h2>

<p>There is quite a lot of confusion regarding the semantics of the name <em>Sass</em>, and for good reason: Sass means both the preprocessor and its own syntax. Not very convenient, is it?</p>

<p>You see, Sass initially described a syntax of which the defining characteristic was its indentation-sensitivity. Soon enough, Sass maintainers decided to close the gap between Sass and CSS by providing a CSS-friendly syntax called <em>SCSS</em> for <em>Sassy CSS</em>. The motto is: if it’s valid CSS, it’s valid SCSS.</p>

<p>Since then, Sass (the preprocessor) has been providing two different syntaxes: Sass (not all-caps, <a href="http://sassnotsass.com">please</a>), also known as <em>the indented syntax</em>, and SCSS. Which one to use is pretty much up to you since both are strictly equivalent in features. It’s only a matter of aesthetics at this point.</p>

<p>Sass’s whitespace-sensitive syntax relies on indentation to get rid of braces, semi-colons and other punctuation symbols, leading to a leaner and shorter syntax. Meanwhile, SCSS is easier to learn since it’s mostly some tiny extra bits on top of CSS.</p>

<p>I, myself, prefer SCSS over Sass because it is closer to CSS and friendlier to most developers. Because of that, SCSS is the default syntax throughout these guidelines. You can switch to Sass indented syntax in the <button data-toggle="aside" class="link-like" role="button" type="button">options panel</button>.</p>

<h6 id="further-reading-2">Further reading</h6>

<h2 id="other-preprocessors">Other preprocessors</h2>

<p>Sass is a preprocessor among others. Its most serious competitor has to be <a href="http://lesscss.org/">LESS</a>, a Node.js based preprocessor that has gotten quite popular thanks to the famous CSS framework <a href="http://getbootstrap.com/">Bootstrap</a> using it. There is also <a href="http://learnboost.github.io/stylus/">Stylus</a> - which is kind of the nerdy, unrestricted version of LESS - where you can do pretty much whatever you want since it almost turns CSS into a programming language.</p>

<p><em>Why choose Sass over LESS or another preprocessor?</em> is still a valid question today. Not so long ago, we used to recommend Sass for Ruby-based projects because it was first made in Ruby and played well with Ruby on Rails. Now that LibSass has caught up (mostly) with original Sass, this is no longer relevant advice.</p>

<p>What I do like with Sass is its conservative approach to CSS. Sass’s design is based on strong principles: much of the design approach comes naturally out of the core teams’ beliefs that a) adding extra features has a complexity cost that needs to be justified by usefulness and, b) it should be easy to reason about what a given block of styles is doing by looking at that block alone. Also, Sass has a much sharper attention to detail than other preprocessors. As far as I can tell, the core designers care deeply about supporting every corner-case of CSS compatibility and making sure every general behavior is consistent.</p>

<p>In other words, Sass is not a preprocessor aimed at pleasing nerdy wannabe programmers like me by adding extraordinary features on top of a language that is not intended to support any logical use-cases. It is a software aimed at solving actual issues; helping to provide useful functionality to CSS where CSS falls short.</p>

<p>Preprocessors aside, we should also mention postprocessors, which have received significant exposure in the last few months, thanks mainly to <a href="https://github.com/postcss/postcss">PostCSS</a> and <a href="https://cssnext.github.io/">cssnext</a>. Postprocessors are pretty much equivalent to preprocessors except they do not provide anything else other than upcoming CSS syntax.</p>

<p>You can think of postprocessors as a polyfill for unsupported CSS features. For instance, you would write variables as they are described in the <a href="http://dev.w3.org/csswg/css-variables/">CSS specifications</a>, then compile your stylesheets with a postprocessor only to find every variable occurrence gets replaced with its value, as Sass would do.</p>

<p>The idea behind postprocessors is that once browsers support new features (e.g. CSS variables), the postprocessor does not compile them anymore and lets browsers take over.</p>

<p>While providing tomorrow’s syntax today is something of a noble idea, I have to say I still prefer using Sass for most tasks. However, there are some occasions where I believe postprocessors are more suited than Sass and the like - CSS prefixing for instance - but we’ll get back to this.</p>

<h6 id="further-reading-3">Further reading</h6>

<h1 id="introduction">Introduction</h1>

<h2 id="why-a-styleguide">Why a styleguide</h2>

<p>A styleguide is not just a pleasing document to read, picturing an ideal state for your code. It is a key document in a project’s life, describing how and why code should be written. It may look like overkill for small projects, but it helps a lot in keeping the codebase clean, scalable and easily maintainable.</p>

<p>Needless to say, the more developers involved on a project, the more code guidelines are needed. Along the same lines, the bigger the project, the more a styleguide is a must.</p>

<p><a href="http://csswizardry.com">Harry Roberts</a> states it very well in <a href="http://cssguidelin.es/#the-importance-of-a-styleguide">CSS Guidelines</a>:</p>

<blockquote>
  <p>A coding styleguide (note, not a visual styleguide) is a valuable tool for teams who:</p>
  <ul>
    <li>build and maintain products for a reasonable length of time;</li>
    <li>have developers of differing abilities and specialties;</li>
    <li>have a number of different developers working on a product at any given time;</li>
    <li>on-board new staff regularly;</li>
    <li>have a number of codebases that developers dip in and out of.</li>
  </ul>
</blockquote>

<h2 id="disclaimer">Disclaimer</h2>

<p>First things first: <strong>this is not a CSS styleguide</strong>. This document will not discuss naming conventions for CSS classes, modular patterns and the question of IDs in the CSS world. These guidelines only aim at dealing with Sass-specific content.</p>

<p>Also, this styleguide is my own and therefore <strong>very opinionated</strong>. Think of it as a collection of methodologies and advice that I have polished and given over the years. It also gives me the opportunity to link to a handful of insightful resources, so be sure to check the <em>further readings</em>.</p>

<p>Obviously, this is certainly not the only way of doing things, and it may or may not suit your project. Feel free to pick from it and adapt it to your needs. As we say, <em>your mileage may vary</em>.</p>

<h2 id="key-principles">Key principles</h2>

<p>At the end of the day, if there is one thing I would like you to get from this whole styleguide, it is that <strong>Sass should be kept as simple as it can be</strong>.</p>

<p>Thanks to my silly experiments like <a href="https://github.com/HugoGiraudel/SassyBitwise">bitwise operators</a>, <a href="https://github.com/HugoGiraudel/SassyIteratorsGenerators">iterators and generators</a> and <a href="https://github.com/HugoGiraudel/SassyJSON">a JSON parser</a> in Sass, we are all well aware of what one can do with this preprocessor.</p>

<p>Meanwhile, CSS is a simple language. Sass, being intended to write CSS, should not get much more complex than regular CSS. The <a href="http://en.wikipedia.org/wiki/KISS_principle">KISS principle</a> (Keep It Simple Stupid) is key here and may even take precedence over the <a href="http://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY principle</a> (Don’t Repeat Yourself) in some circumstances.</p>

<p>Sometimes, it’s better to repeat a little to keep the code maintainable, rather than building a top-heavy, unwieldy, unnecessarily complicated system that is completely unmaintainable because it is overly complex.</p>

<p>Also, and let me quote <a href="https://csswizardry.com">Harry Roberts</a> once again, <strong>pragmatism trumps perfection</strong>. At some point, you will probably find yourself going against the rules described here. If it makes sense, if it feels right, do it. Code is just a means, not an end.</p>

<h6 id="further-reading-4">Further reading</h6>

<h1 id="syntax--formatting">Syntax &amp; formatting</h1>

<p>If you ask me, the very first thing a styleguide should do is describe the way we want our code to look.</p>

<p>When several developers are involved in writing CSS on the same project(s), it is only a matter of time before one of them starts doing things their own way. Code guidelines that promote consistency not only prevent this, but also help when it comes to reading and updating the code.</p>

<p>Roughly, we want (shamelessly inspired by <a href="http://cssguidelin.es/#syntax-and-formatting">CSS Guidelines</a>):</p>

<ul>
  <li>two (2) spaces indents, no tabs;</li>
  <li>ideally, 80-characters wide lines;</li>
  <li>properly written multi-line CSS rules;</li>
  <li>meaningful use of whitespace.</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">0</span> <span class="mi">1</span><span class="kt">em</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">block</span><span class="p">;</span> <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>

    <span class="na">padding</span><span class="o">:</span> <span class="mi">0</span> <span class="mi">1</span><span class="kt">em</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Since Sass indented-syntax forces those coding standards</span>
<span class="c1">// There is no wrong way of proceeding</span>
<span class="nc">.foo</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">0</span> <span class="mi">1</span><span class="kt">em</span></code></pre></div>

  </div>
</div>

<p>We will not tackle the question of file organization in this section. It is the object of <a href="#architecture">another section</a>.</p>

<h2 id="strings">Strings</h2>

<p>Believe it or not, strings play quite a large role in both CSS and Sass ecosystems. Most CSS values are either lengths or strings (usually unquoted), so it actually is quite crucial to stick to some guidelines when dealing with strings in Sass.</p>

<h3 id="encoding">Encoding</h3>

<p>To avoid any potential issue with character encoding, it is highly recommended to force <a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a> encoding in the <a href="#main-file">main stylesheet</a> using the <code>@charset</code> directive. Make sure it is the very first element of the stylesheet and there is no character of any kind before it.</p>

<h3 id="quotes">Quotes</h3>

<p>CSS does not require strings to be quoted, not even those containing spaces. Take font-family names for instance: it doesn’t matter whether you wrap them in quotes for the CSS parser.</p>

<p>Because of this, Sass <em>also</em> does not require strings to be quoted. Even better (and <em>luckily</em>, you’ll concede), a quoted string is strictly equivalent to its unquoted twin (e.g. <code>'abc'</code> is strictly equal to <code>abc</code>).</p>

<p>That being said, languages that do not require strings to be quoted are definitely a minority and so, <strong>strings should always be wrapped with single quotes</strong> (<code>'</code>) in Sass (single being easier to type than double on <em>qwerty</em> keyboards). Besides consistency with other languages, including CSS’ cousin JavaScript, there are several reasons for this choice:</p>

<ul>
  <li>color names are treated as colors when unquoted, which can lead to serious issues;</li>
  <li>most syntax highlighters will choke on unquoted strings;</li>
  <li>it helps general readability;</li>
  <li>there is no valid reason not to quote strings.</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$direction</span><span class="o">:</span> <span class="s1">'</span><span class="s2">left'</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$direction</span><span class="o">:</span> <span class="no">left</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$direction</span><span class="o">:</span> <span class="s1">'</span><span class="s2">left'</span>

<span class="c1">// Nope</span>
<span class="nv">$direction</span><span class="o">:</span> <span class="no">left</span></code></pre></div>

  </div>
</div>

<h3 id="strings-as-css-values">Strings as CSS values</h3>

<p>Specific CSS values such as <code>initial</code> or <code>sans-serif</code> require not to be quoted. Indeed, the declaration <code>font-family: 'sans-serif'</code> will silently fail because CSS is expecting an identifier, not a quoted string. Because of this, we do not quote those values.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$font-type</span><span class="o">:</span> <span class="no">sans-serif</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$font-type</span><span class="o">:</span> <span class="s1">'</span><span class="s2">sans-serif'</span><span class="p">;</span>

<span class="c1">// Okay I guess</span>
<span class="nv">$font-type</span><span class="o">:</span> <span class="nf">unquote</span><span class="p">(</span><span class="s1">'</span><span class="s2">sans-serif'</span><span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="na">$font-type</span><span class="o">:</span> <span class="no">sans-serif</span>

<span class="c1">// Nope</span>
<span class="na">$font-type</span><span class="o">:</span> <span class="s1">'</span><span class="s2">sans-serif'</span>

<span class="c1">// Okay I guess</span>
<span class="na">$font-type</span><span class="o">:</span> <span class="nf">unquote</span><span class="p">(</span><span class="s1">'</span><span class="s2">sans-serif'</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>Hence, we can make a distinction between strings intended to be used as CSS values (CSS identifiers) like in the previous example, and strings when sticking to the Sass data type, for instance map keys.</p>

<p>We don’t quote the former, but we do wrap the latter in single quotes.</p>

<h3 id="strings-containing-quotes">Strings containing quotes</h3>

<p>If a string contains one or several single quotes, one might consider wrapping the string with double quotes (<code>"</code>) instead, in order to avoid escaping too many characters within the string.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Okay</span>
<span class="k">@warn</span> <span class="s1">'</span><span class="s2">You can\'t do that.'</span><span class="p">;</span>

<span class="c1">// Okay</span>
<span class="k">@warn</span> <span class="s2">"You can't do that."</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Okay</span>
<span class="k">@warn</span> <span class="s1">'</span><span class="s2">You can\'t do that.'</span>

<span class="c1">// Okay</span>
<span class="k">@warn</span> <span class="s2">"You can't do that."</span></code></pre></div>

  </div>
</div>

<h3 id="urls">URLs</h3>

<p>URLs should be quoted as well, for the same reasons as above:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">background-image</span><span class="o">:</span> <span class="sx">url('/images/kittens.jpg')</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">background-image</span><span class="o">:</span> <span class="sx">url(/images/kittens.jpg)</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span>
  <span class="na">background-image</span><span class="o">:</span> <span class="sx">url('/images/kittens.jpg')</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span>
  <span class="na">background-image</span><span class="o">:</span> <span class="sx">url(/images/kittens.jpg)</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-5">Further reading</h6>

<h2 id="numbers">Numbers</h2>

<p>In Sass, number is a data type including everything from unitless numbers to lengths, durations, frequencies, angles and so on. This allows calculations to be run on such measures.</p>

<h3 id="zeros">Zeros</h3>

<p>Numbers should display leading zeros before a decimal value less than one. Never display trailing zeros.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span><span class="p">;</span>
  <span class="na">opacity</span><span class="o">:</span> <span class="mi">0</span><span class="mf">.5</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">2</span><span class="mf">.0</span><span class="kt">em</span><span class="p">;</span>
  <span class="na">opacity</span><span class="o">:</span> <span class="mf">.5</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span>
  <span class="na">opacity</span><span class="o">:</span> <span class="mi">0</span><span class="mf">.5</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span>
  <span class="na">padding</span><span class="o">:</span> <span class="mi">2</span><span class="mf">.0</span><span class="kt">em</span>
  <span class="na">opacity</span><span class="o">:</span> <span class="mf">.5</span></code></pre></div>

  </div>
</div>

<h3 id="units">Units</h3>

<p>When dealing with lengths, a <code>0</code> value should never ever have a unit.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$length</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$length</span><span class="o">:</span> <span class="mi">0</span><span class="kt">em</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$length</span><span class="o">:</span> <span class="mi">0</span>

<span class="c1">// Nope</span>
<span class="nv">$length</span><span class="o">:</span> <span class="mi">0</span><span class="kt">em</span></code></pre></div>

  </div>
</div>

<p>The most common mistake I can think of regarding numbers in Sass, is thinking that units are just some strings that can be safely appended to a number. While that sounds true, it is certainly not how units work. Think of units as algebraic symbols. For instance, in the real world, multiplying 5 inches by 5 inches gives you 25 square inches. The same logic applies to Sass.</p>

<p>To add a unit to a number, you have to multiply this number by <em>1 unit</em>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$value</span><span class="o">:</span> <span class="mi">42</span><span class="p">;</span>

<span class="c1">// Yep</span>
<span class="nv">$length</span><span class="o">:</span> <span class="nv">$value</span> <span class="o">*</span> <span class="mi">1</span><span class="kt">px</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$length</span><span class="o">:</span> <span class="nv">$value</span> <span class="o">+</span> <span class="no">px</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nv">$value</span><span class="o">:</span> <span class="mi">42</span>

<span class="c1">// Yep</span>
<span class="nv">$length</span><span class="o">:</span> <span class="nv">$value</span> <span class="o">*</span> <span class="mi">1</span><span class="kt">px</span>

<span class="c1">// Nope</span>
<span class="nv">$length</span><span class="o">:</span> <span class="nv">$value</span> <span class="o">+</span> <span class="no">px</span></code></pre></div>

  </div>
</div>

<p>Note that adding <em>0 member of that unit</em> also works, but I would rather recommend the aforementioned method since adding <em>0 unit</em> can be a bit confusing. Indeed, when trying to convert a number to another compatible unit, adding 0 will not do the trick.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$value</span><span class="o">:</span> <span class="mi">42</span> <span class="o">+</span> <span class="mi">0</span><span class="kt">px</span><span class="p">;</span>
<span class="c1">// -&gt; 42px</span>

<span class="nv">$value</span><span class="o">:</span> <span class="mi">1</span><span class="kt">in</span> <span class="o">+</span> <span class="mi">0</span><span class="kt">px</span><span class="p">;</span>
<span class="c1">// -&gt; 1in</span>

<span class="nv">$value</span><span class="o">:</span> <span class="mi">0</span><span class="kt">px</span> <span class="o">+</span> <span class="mi">1</span><span class="kt">in</span><span class="p">;</span>
<span class="c1">// -&gt; 96px</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nv">$value</span><span class="o">:</span> <span class="mi">42</span> <span class="o">+</span> <span class="mi">0</span><span class="kt">px</span>
<span class="c1">// -&gt; 42px</span>

<span class="nv">$value</span><span class="o">:</span> <span class="mi">1</span><span class="kt">in</span> <span class="o">+</span> <span class="mi">0</span><span class="kt">px</span>
<span class="c1">// -&gt; 1in</span>

<span class="nv">$value</span><span class="o">:</span> <span class="mi">0</span><span class="kt">px</span> <span class="o">+</span> <span class="mi">1</span><span class="kt">in</span>
<span class="c1">// -&gt; 96px</span></code></pre></div>

  </div>
</div>

<p>In the end, it really depends on what you are trying to achieve. Just keep in mind that adding the unit as a string is not a good way to proceed.</p>

<p>To remove the unit of a value, you have to divide it by <em>one unit of its kind</em>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$length</span><span class="o">:</span> <span class="mi">42</span><span class="kt">px</span><span class="p">;</span>

<span class="c1">// Yep</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nv">$length</span> <span class="o">/</span> <span class="mi">1</span><span class="kt">px</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nf">str-slice</span><span class="p">(</span><span class="nv">$length</span> <span class="o">+</span> <span class="nf">unquote</span><span class="p">(</span><span class="s1">'</span><span class="s2">'</span><span class="p">)</span><span class="o">,</span> <span class="mi">1</span><span class="o">,</span> <span class="mi">2</span><span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nv">$length</span><span class="o">:</span> <span class="mi">42</span><span class="kt">px</span>

<span class="c1">// Yep</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nv">$length</span> <span class="o">/</span> <span class="mi">1</span><span class="kt">px</span>

<span class="c1">// Nope</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nf">str-slice</span><span class="p">(</span><span class="nv">$length</span> <span class="o">+</span> <span class="nf">unquote</span><span class="p">(</span><span class="s1">'</span><span class="s2">'</span><span class="p">)</span><span class="o">,</span> <span class="mi">1</span><span class="o">,</span> <span class="mi">2</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>Appending a unit as a string to a number results in a string, preventing any additional operation on the value. Slicing the numeric part of a number with a unit also results in a string. This is not what you want.</p>

<h3 id="calculations">Calculations</h3>

<p><strong>Top-level numeric calculations should always be wrapped in parentheses</strong>. Not only does this requirement dramatically improve readability, it also prevents some edge cases by forcing Sass to evaluate the contents of the parentheses.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">width</span><span class="o">:</span> <span class="p">(</span><span class="mi">100</span><span class="kt">%</span> <span class="o">/</span> <span class="mi">3</span><span class="p">);</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">%</span> <span class="o">/</span> <span class="mi">3</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span>
  <span class="na">width</span><span class="o">:</span> <span class="p">(</span><span class="mi">100</span><span class="kt">%</span> <span class="o">/</span> <span class="mi">3</span><span class="p">)</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">%</span> <span class="o">/</span> <span class="mi">3</span></code></pre></div>

  </div>
</div>

<h3 id="magic-numbers">Magic numbers</h3>

<p>“Magic number” is an <a href="http://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants">old school programming</a> term for <em>unnamed numerical constant</em>. Basically, it’s just a random number that happens to <em>just work</em>™ yet is not tied to any logical explanation.</p>

<p>Needless to say <strong>magic numbers are a plague and should be avoided at all costs</strong>. When you cannot manage to find a reasonable explanation for why a number works, add an extensive comment explaining how you got there and why you think it works. Admitting you don’t know why something works is still more helpful to the next developer than them having to figure out what’s going on from scratch.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="cm">/**</span>
<span class="cm"> * 1. Magic number. This value is the lowest I could find to align the top of</span>
<span class="cm"> * `.foo` with its parent. Ideally, we should fix it properly.</span>
<span class="cm"> */</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">top</span><span class="o">:</span> <span class="mi">0</span><span class="mf">.327</span><span class="kt">em</span><span class="p">;</span> <span class="cm">/* 1 */</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="cm">/**</span>
 <span class="cm">* 1. Magic number. This value is the lowest I could find to align the top of</span>
 <span class="cm">* `.foo` with its parent. Ideally, we should fix it properly.</span>
 <span class="cm">*/</span>
<span class="nc">.foo</span>
  <span class="na">top</span><span class="o">:</span> <span class="mi">0</span><span class="mf">.327</span><span class="kt">em</span> <span class="cm">/* 1 </span><span class="c">*/</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-6">Further reading</h6>

<h2 id="colors">Colors</h2>

<p>Colors occupy an important place in the CSS language. Naturally, Sass ends up being a valuable ally when it comes to manipulating colors, mostly by providing a handful of <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html">powerful functions</a>.</p>

<h3 id="color-formats">Color formats</h3>

<p>In order to make colors as simple as they can be, my advice would be to respect the following order of preference for color formats:</p>

<ol>
  <li><a href="http://www.w3.org/TR/css3-color/#svg-color">CSS color keywords</a>;</li>
  <li><a href="http://en.wikipedia.org/wiki/HSL_and_HSV">HSL notation</a>;</li>
  <li><a href="http://en.wikipedia.org/wiki/RGB_color_model">RGB notation</a>;</li>
  <li>Hexadecimal notation. Preferably lowercase and shortened when possible.</li>
</ol>

<p>For starters, keywords often speak for themselves. The HSL representation is not only the easiest one for the human brain to comprehend<sup>[citation needed]</sup>, it also makes it easy for stylesheet authors to tweak the color by adjusting the hue, saturation and lightness individually. RGB still has the benefit of showing right away if the color is more of a blue, a green or a red but it does not make it easy to build a color from the three parts. Lastly, hexadecimal is close to indecipherable for the human mind.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="mh">#FF0000</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="mh">#FF0000</span></code></pre></div>

  </div>
</div>

<p>When using HSL or RGB notation, always add a single space after a comma (<code>,</code>) and no space between parentheses (<code>(</code>, <code>)</code>) and content.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="nf">rgba</span><span class="p">(</span><span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="mf">.1</span><span class="p">);</span>
  <span class="na">background</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span><span class="mi">300</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="p">);</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="nf">rgba</span><span class="p">(</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="mf">.1</span><span class="p">);</span>
  <span class="na">background</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span> <span class="mi">300</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span> <span class="p">);</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="nf">rgba</span><span class="p">(</span><span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="mi">0</span><span class="mf">.1</span><span class="p">)</span>
  <span class="na">background</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span><span class="mi">300</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="p">)</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="nf">rgba</span><span class="p">(</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="o">,</span><span class="mi">0</span><span class="mf">.1</span><span class="p">)</span>
  <span class="na">background</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span> <span class="mi">300</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span><span class="o">,</span> <span class="mi">100</span><span class="kt">%</span> <span class="p">)</span></code></pre></div>

  </div>
</div>

<h3 id="colors-and-variables">Colors and variables</h3>

<p>When using a color more than once, store it in a variable with a meaningful name representing the color.</p>

<p>Now you are free to use this variable wherever you want. However, if your usage is strongly tied to a theme, I would advise against using the variable as is. Instead, store it in another variable with a name explaining how it should be used.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$main-theme-color</span><span class="o">:</span> <span class="nv">$sass-pink</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="na">$main-theme-color</span><span class="o">:</span> <span class="nv">$sass-pink</span></code></pre></div>

  </div>
</div>

<p>Doing this would prevent a theme change leading to something like <code>$sass-pink: blue</code>.</p>

<h3 id="lightening-and-darkening-colors">Lightening and darkening colors</h3>

<p>Both <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html#lighten-instance_method"><code>lighten</code></a> and <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html#darken-instance_method"><code>darken</code></a> functions manipulate the lightness of a color in the HSL space by adding to or subtracting from the lightness in the HSL space. Basically, they are nothing but aliases for the <code>$lightness</code> parameter of the <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html#adjust_color-instance_method"><code>adjust-color</code></a> function.</p>

<p>The thing is, those functions often do not provide the expected result. On the other hand, the <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html#mix-instance_method"><code>mix</code></a> function is a nice way to lighten or darken a color by mixing it with either <code>white</code> or <code>black</code>.</p>

<p>The benefit of using <code>mix</code> rather than one of the two aforementioned functions is that it will progressively go to black (or white) as you decrease the proportion of the color, whereas <code>darken</code> and <code>lighten</code> will quickly blow out a color all the way to black or white.</p>

<figure role="group">
  <img alt="Illustration of the difference between lighten/darken and mix by KatieK&#10;" sizes="100vw" srcset="http://sass-guidelin.es/assets/images/lighten-darken-mix_small.png  540w,&#10;             http://sass-guidelin.es/assets/images/lighten-darken-mix_medium.png 900w,&#10;             http://sass-guidelin.es/assets/images/lighten-darken-mix_large.png 1200w,&#10;             http://sass-guidelin.es/assets/images/lighten-darken-mix_huge.png  1590w"/>
  <figcaption><p>Illustration of the difference between <code>lighten</code>/<code>darken</code> and <code>mix</code> by <a href="http://codepen.io/KatieK2/pen/tejhz/">KatieK</a></p>
</figcaption>
</figure>

<p>If you don’t want to write the <code>mix</code> function every time, you can create two easy-to-use functions <code>tint</code> and <code>shade</code> (which are also a part of <a href="http://compass-style.org/reference/compass/helpers/colors/#shade">Compass</a>) to do the same thing:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Slightly lighten a color</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {Color} $color - color to tint</span>
<span class="c1">/// @param {Number} $percentage - percentage of `$color` in returned color</span>
<span class="c1">/// @return {Color}</span>
<span class="k">@function</span> <span class="nt">tint</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@return</span> <span class="nt">mix</span><span class="o">(</span><span class="nt">white</span><span class="o">,</span> <span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">);</span>
<span class="p">}</span>

<span class="c1">/// Slightly darken a color</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {Color} $color - color to shade</span>
<span class="c1">/// @param {Number} $percentage - percentage of `$color` in returned color</span>
<span class="c1">/// @return {Color}</span>
<span class="k">@function</span> <span class="nt">shade</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@return</span> <span class="nt">mix</span><span class="o">(</span><span class="nt">black</span><span class="o">,</span> <span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">);</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Slightly lighten a color</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {Color} $color - color to tint</span>
<span class="c1">/// @param {Number} $percentage - percentage of `$color` in returned color</span>
<span class="c1">/// @return {Color}</span>
<span class="k">@function</span> <span class="nt">tint</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span>
  <span class="k">@return</span> <span class="nt">mix</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="nt">white</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span>

<span class="c1">/// Slightly darken a color</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {Color} $color - color to shade</span>
<span class="c1">/// @param {Number} $percentage - percentage of `$color` in returned color</span>
<span class="c1">/// @return {Color}</span>
<span class="k">@function</span> <span class="nt">shade</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span>
  <span class="k">@return</span> <span class="nt">mix</span><span class="o">(</span><span class="err">$</span><span class="nt">color</span><span class="o">,</span> <span class="nt">black</span><span class="o">,</span> <span class="err">$</span><span class="nt">percentage</span><span class="o">)</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>The <a href="http://sass-lang.com/documentation/Sass/Script/Functions.html#scale_color-instance_method"><code>scale-color</code></a> function is designed to scale properties more fluidly by taking into account how high or low they already are. It should provide results that are as nice as <code>mix</code>’s but with a clearer calling convention. The scaling factor isn’t exactly the same though.</p>
</div>

<h6 id="further-reading-7">Further reading</h6>

<h2 id="lists">Lists</h2>

<p>Lists are the Sass equivalent of arrays. A list is a flat data structure (unlike <a href="#maps">maps</a>) intended to store values of any type (including lists, leading to nested lists).</p>

<p>Lists should respect the following guidelines:</p>

<ul>
  <li>either inlined or multilines;</li>
  <li>necessarily on multilines if too long to fit on an 80-character line;</li>
  <li>unless used as is for CSS purposes, always comma separated;</li>
  <li>always wrapped in parenthesis;</li>
  <li>trailing comma if multilines, not if inlined.</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$font-stack</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span><span class="p">);</span>

<span class="c1">// Yep</span>
<span class="nv">$font-stack</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span>
  <span class="no">sans-serif</span><span class="o">,</span>
<span class="p">);</span>

<span class="c1">// Nope</span>
<span class="nv">$font-stack</span><span class="o">:</span> <span class="s1">'</span><span class="s2">Helvetica'</span> <span class="s1">'</span><span class="s2">Arial'</span> <span class="no">sans-serif</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$font-stack</span><span class="o">:</span> <span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$font-stack</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span><span class="o">,</span><span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="na">$font-stack</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span><span class="p">)</span>

<span class="c1">// Nope (not supported)</span>
<span class="na">$font-stack</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span>
  <span class="nt">sans-serif</span><span class="o">,</span>
<span class="o">)</span>

<span class="c1">// Nope</span>
<span class="na">$font-stack</span><span class="o">:</span> <span class="s1">'</span><span class="s2">Helvetica'</span> <span class="s1">'</span><span class="s2">Arial'</span> <span class="no">sans-serif</span>

<span class="c1">// Nope</span>
<span class="na">$font-stack</span><span class="o">:</span> <span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span>

<span class="c1">// Nope</span>
<span class="na">$font-stack</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">Helvetica'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">Arial'</span><span class="o">,</span> <span class="no">sans-serif</span><span class="o">,</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>When adding new items to a list, always use the provided API. Do not attempt to add new items manually.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$shadows</span><span class="o">:</span> <span class="p">(</span><span class="mi">0</span> <span class="mi">42</span><span class="kt">px</span> <span class="mi">13</span><span class="mf">.37</span><span class="kt">px</span> <span class="ni">hotpink</span><span class="p">);</span>

<span class="c1">// Yep</span>
<span class="nv">$shadows</span><span class="o">:</span> <span class="nf">append</span><span class="p">(</span><span class="nv">$shadows</span><span class="o">,</span> <span class="nv">$shadow</span><span class="o">,</span> <span class="n">comma</span><span class="p">);</span>

<span class="c1">// Nope</span>
<span class="nv">$shadows</span><span class="o">:</span> <span class="nv">$shadows</span><span class="o">,</span> <span class="nv">$shadow</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nv">$shadows</span><span class="o">:</span> <span class="p">(</span><span class="mi">0</span> <span class="mi">42</span><span class="kt">px</span> <span class="mi">13</span><span class="mf">.37</span><span class="kt">px</span> <span class="ni">hotpink</span><span class="p">)</span>

<span class="c1">// Yep</span>
<span class="nv">$shadows</span><span class="o">:</span> <span class="nf">append</span><span class="p">(</span><span class="nv">$shadows</span><span class="o">,</span> <span class="nv">$shadow</span><span class="o">,</span> <span class="n">comma</span><span class="p">)</span>

<span class="c1">// Nope</span>
<span class="nv">$shadows</span><span class="o">:</span> <span class="nv">$shadows</span><span class="o">,</span> <span class="nv">$shadow</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-8">Further reading</h6>

<h2 id="maps">Maps</h2>

<p>Since Sass 3.3, stylesheet authors can define maps — the Sass term for associative arrays, hashes or even JavaScript objects. A map is a data structure mapping keys (that can be any data type, including maps although I wouldn’t recommend it) to values of any type.</p>

<p>Maps should be written as follows:</p>

<ul>
  <li>space after the colon (<code>:</code>);</li>
  <li>opening brace (<code>(</code>) on the same line as the colon (<code>:</code>);</li>
  <li><strong>quoted keys</strong> if they are strings (which represents 99% of the cases);</li>
  <li>each key/value pair on its own new line;</li>
  <li>comma (<code>,</code>) at the end of each key/value;</li>
  <li><strong>trailing comma</strong> (<code>,</code>) on last item to make it easier to add, remove or reorder items;</li>
  <li>closing brace (<code>)</code>) on its own new line;</li>
  <li>no space or new line between closing brace (<code>)</code>) and semi-colon (<code>;</code>).</li>
</ul>

<p>Illustration:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">small'</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">medium'</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">large'</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="o">,</span>
<span class="p">);</span>

<span class="c1">// Nope</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span> <span class="n">small</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span> <span class="no">medium</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span> <span class="no">large</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span> <span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">small'</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span> <span class="s1">'</span><span class="s2">medium'</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span> <span class="s1">'</span><span class="s2">large'</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="o">,</span><span class="p">)</span>

<span class="c1">// Nope</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span> <span class="s1">'</span><span class="s2">small'</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span> <span class="s1">'</span><span class="s2">medium'</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span> <span class="s1">'</span><span class="s2">large'</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span> <span class="p">)</span>

<span class="c1">// Nope</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span><span class="n">small</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span> <span class="no">medium</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span> <span class="no">large</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="o">,</span><span class="p">)</span>

<span class="c1">// Nope (since it is not supported)</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span>
  <span class="na">'small'</span><span class="o">:</span> <span class="mi">767</span><span class="kt">px</span><span class="o">,</span>
  <span class="na">'medium'</span><span class="o">:</span> <span class="mi">992</span><span class="kt">px</span><span class="o">,</span>
  <span class="na">'large'</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="o">,</span>
<span class="o">)</span></code></pre></div>

  </div>
</div>

<h3 id="debugging-a-sass-map">Debugging a Sass map</h3>

<p>If you ever find yourself lost, wondering what kind of crazy magic is happening in a Sass map, worry not because there is still a way to be saved.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@mixin</span><span class="nf"> debug-map</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span> <span class="p">{</span>
  <span class="k">@at-root</span> <span class="p">{</span>
    <span class="k">@debug</span><span class="o">-</span><span class="n">map</span> <span class="p">{</span>
      <span class="na">__toString__</span><span class="o">:</span> <span class="nf">inspect</span><span class="p">(</span><span class="nv">$map</span><span class="p">);</span>
      <span class="na">__length__</span><span class="o">:</span> <span class="nf">length</span><span class="p">(</span><span class="nv">$map</span><span class="p">);</span>
      <span class="na">__depth__</span><span class="o">:</span> <span class="nf">if</span><span class="p">(</span><span class="nf">function-exists</span><span class="p">(</span><span class="s1">'</span><span class="s2">map-depth'</span><span class="p">)</span><span class="o">,</span> <span class="nf">map-depth</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span><span class="o">,</span> <span class="n">null</span><span class="p">);</span>
      <span class="na">__keys__</span><span class="o">:</span> <span class="nf">map-keys</span><span class="p">(</span><span class="nv">$map</span><span class="p">);</span>
      <span class="nt">__properties__</span> <span class="p">{</span>
        <span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span> <span class="p">{</span>
          <span class="nn">#</span><span class="p">{</span><span class="s1">'</span><span class="s2">('</span> <span class="o">+</span> <span class="nt">type-of</span><span class="o">(</span><span class="err">$</span><span class="nt">value</span><span class="o">)</span> <span class="o">+</span> <span class="s1">'</span><span class="s2">) '</span> <span class="o">+</span> <span class="err">$</span><span class="nt">key</span><span class="p">}</span><span class="nd">:</span> <span class="nt">inspect</span><span class="o">(</span><span class="err">$</span><span class="nt">value</span><span class="o">);</span>
        <span class="p">}</span>
      <span class="p">}</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nf">=debug-map</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span>
  <span class="k">@at-root</span>
    <span class="k">@debug</span><span class="o">-</span><span class="n">map</span>
      <span class="na">__toString__</span><span class="o">:</span> <span class="nf">inspect</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span>
      <span class="na">__length__</span><span class="o">:</span> <span class="nf">length</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span>
      <span class="na">__depth__</span><span class="o">:</span> <span class="nf">if</span><span class="p">(</span><span class="nf">function-exists</span><span class="p">(</span><span class="s1">'</span><span class="s2">map-depth'</span><span class="p">)</span><span class="o">,</span> <span class="nf">map-depth</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span><span class="o">,</span> <span class="n">null</span><span class="p">)</span>
      <span class="na">__keys__</span><span class="o">:</span> <span class="nf">map-keys</span><span class="p">(</span><span class="nv">$map</span><span class="p">)</span>
      <span class="nt">__properties__</span>
        <span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span>
          <span class="na">#{'('</span><span class="err"> </span><span class="na">+</span><span class="err"> </span><span class="na">type-of($value)</span><span class="err"> </span><span class="na">+</span><span class="err"> </span><span class="na">')</span><span class="err"> </span><span class="na">'</span><span class="err"> </span><span class="na">+</span><span class="err"> </span><span class="na">$key}</span><span class="o">:</span> <span class="nf">inspect</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>If you are interested in knowing the depth of the map, add the following function. The mixin will display it automatically.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Compute the maximum depth of a map</span>
<span class="c1">/// @param {Map} $map</span>
<span class="c1">/// @return {Number} max depth of `$map`</span>
<span class="k">@function</span> <span class="nt">map-depth</span><span class="o">(</span><span class="err">$</span><span class="nt">map</span><span class="o">)</span> <span class="p">{</span>
  <span class="nv">$level</span><span class="o">:</span> <span class="mi">1</span><span class="p">;</span>

  <span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span> <span class="p">{</span>
    <span class="k">@if</span> <span class="nf">type-of</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span> <span class="o">==</span> <span class="s1">'</span><span class="s2">map'</span> <span class="p">{</span>
      <span class="nv">$level</span><span class="o">:</span> <span class="nf">max</span><span class="p">(</span><span class="nf">map-depth</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="o">,</span> <span class="nv">$level</span><span class="p">);</span>
    <span class="p">}</span>
  <span class="p">}</span>

  <span class="k">@return</span> <span class="err">$</span><span class="nt">level</span><span class="o">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Compute the maximum depth of a map</span>
<span class="c1">/// @param {Map} $map</span>
<span class="c1">/// @return {Number} max depth of `$map`</span>
<span class="k">@function</span> <span class="nt">map-depth</span><span class="o">(</span><span class="err">$</span><span class="nt">map</span><span class="o">)</span>
  <span class="nv">$level</span><span class="o">:</span> <span class="mi">1</span>

  <span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span>
    <span class="k">@if</span> <span class="nf">type-of</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span> <span class="o">==</span> <span class="s1">'</span><span class="s2">map'</span>
      <span class="nv">$level</span><span class="o">:</span> <span class="nf">max</span><span class="p">(</span><span class="nf">map-depth</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="o">,</span> <span class="nv">$level</span><span class="p">)</span>

  <span class="k">@return</span> <span class="err">$</span><span class="nt">level</span><span class="o">;</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-9">Further reading</h6>

<h2 id="css-ruleset">CSS Ruleset</h2>

<p>At this point, this is mostly revising what everybody knows, but here is how a CSS ruleset should be written (at least, according to most guidelines, including <a href="http://cssguidelin.es/#anatomy-of-a-ruleset">CSS Guidelines</a>):</p>

<ul>
  <li>related selectors on the same line; unrelated selectors on new lines;</li>
  <li>the opening brace (<code>{</code>) spaced from the last selector by a single space;</li>
  <li>each declaration on its own new line;</li>
  <li>a space after the colon (<code>:</code>);</li>
  <li>a trailing semi-colon (<code>;</code>) at the end of all declarations;</li>
  <li>the closing brace (<code>}</code>) on its own new line;</li>
  <li>a new line after the closing brace <code>}</code>.</li>
</ul>

<p>Illustration:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nc">.foo</span><span class="o">,</span> <span class="nc">.foo-bar</span><span class="o">,</span>
<span class="nc">.baz</span> <span class="p">{</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span><span class="o">,</span>
<span class="nc">.foo-bar</span><span class="o">,</span> <span class="nc">.baz</span> <span class="p">{</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">block</span><span class="p">;</span>
    <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
    <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span> <span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nc">.foo</span><span class="o">,</span> <span class="nc">.foo-bar</span><span class="o">,</span>
<span class="nc">.baz</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span>

<span class="c1">// Nope</span>
<span class="nc">.foo</span><span class="o">,</span>
<span class="nc">.foo-bar</span><span class="o">,</span> <span class="nc">.baz</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">block</span>
    <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
    <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span></code></pre></div>

  </div>
</div>

<p>Adding to those CSS-related guidelines, we want to pay attention to:</p>

<ul>
  <li>local variables being declared before any declarations, then spaced from declarations by a new line;</li>
  <li>mixin calls with no <code>@content</code> coming before any declaration;</li>
  <li>nested selectors always coming after a new line;</li>
  <li>mixin calls with <code>@content</code> coming after any nested selector;</li>
  <li>no new line before a closing brace (<code>}</code>).</li>
</ul>

<p>Illustration:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span><span class="o">,</span> <span class="nc">.foo-bar</span><span class="o">,</span>
<span class="nc">.baz</span> <span class="p">{</span>
  <span class="nv">$length</span><span class="o">:</span> <span class="mi">42</span><span class="kt">em</span><span class="p">;</span>

  <span class="k">@include</span><span class="nd"> ellipsis</span><span class="p">;</span>
  <span class="k">@include</span><span class="nd"> size</span><span class="p">(</span><span class="nv">$length</span><span class="p">);</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span><span class="p">;</span>

  <span class="k">&amp;</span><span class="nd">:hover</span> <span class="p">{</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
  <span class="p">}</span>

  <span class="k">@include</span><span class="nd"> respond-to</span><span class="p">(</span><span class="s1">'</span><span class="s2">small'</span><span class="p">)</span> <span class="p">{</span>
    <span class="na">overflow</span><span class="o">:</span> <span class="no">visible</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span><span class="o">,</span> <span class="nc">.foo-bar</span><span class="o">,</span>
<span class="nc">.baz</span>
  <span class="nv">$length</span><span class="o">:</span> <span class="mi">42</span><span class="kt">em</span>

  <span class="nd">+ellipsis</span>
  <span class="nd">+size</span><span class="p">(</span><span class="nv">$length</span><span class="p">)</span>
  <span class="na">display</span><span class="o">:</span> <span class="no">block</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">margin</span><span class="o">:</span> <span class="mi">0</span> <span class="no">auto</span>

  <span class="k">&amp;</span><span class="nd">:hover</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">red</span>

  <span class="nd">+respond-to</span><span class="p">(</span><span class="s1">'</span><span class="s2">small'</span><span class="p">)</span>
    <span class="na">overflow</span><span class="o">:</span> <span class="no">visible</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-10">Further reading</h6>

<h2 id="declaration-sorting">Declaration Sorting</h2>

<p>I cannot think of many topics where opinions are as divided as they are regarding declaration sorting in CSS. Concretely, there are two factions here:</p>

<ul>
  <li>sticking to the alphabetical order;</li>
  <li>ordering declarations by type (position, display, colors, font, miscellaneous…).</li>
</ul>

<p>There are pros and cons for both ways. On one hand, alphabetical order is universal (at least for languages using the latin alphabet) so there is no argument about sorting one property before another. However, it seems extremely weird to me to see properties such as <code>bottom</code> and <code>top</code> not right next to each other. Why would animations should appear before the display type? There are a lot of oddities with alphabetical ordering.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span><span class="p">;</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span><span class="p">;</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span><span class="p">;</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span><span class="p">;</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span><span class="p">;</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span></code></pre></div>

  </div>
</div>

<p>On the other hand, ordering properties by type makes perfect sense. Every font-related declarations are gathered, <code>top</code> and <code>bottom</code> are reunited and reading a ruleset kind of feels like reading a short story. But unless you stick to some conventions like <a href="https://github.com/necolas/idiomatic-css">Idiomatic CSS</a>, there is a lot of room for interpretation in this way of doing things. Where would <code>white-space</code> go: font or display? Where does belong <code>overflow</code> exactly? What is the property order within a group (it could be alphabetically, oh the irony)?</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span><span class="p">;</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span><span class="p">;</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span><span class="p">;</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span><span class="p">;</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span></code></pre></div>

  </div>
</div>

<p>There is also another interesting subtree of type ordering called <a href="https://github.com/brandon-rhodes/Concentric-CSS">Concentric CSS</a>, that seems to be quite popular as well. Basically, Concentric CSS relies on the box-model to define an order: starts outside, moves inward.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span><span class="p">;</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span><span class="p">;</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span><span class="p">;</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span><span class="p">;</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span><span class="p">;</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">width</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span>
  <span class="na">height</span><span class="o">:</span> <span class="mi">100</span><span class="kt">px</span>
  <span class="na">position</span><span class="o">:</span> <span class="no">absolute</span>
  <span class="na">right</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">bottom</span><span class="o">:</span> <span class="mi">0</span>
  <span class="na">background</span><span class="o">:</span> <span class="nb">black</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">white</span>
  <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span>
  <span class="na">font-size</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">em</span></code></pre></div>

  </div>
</div>

<p>I must say I cannot decide myself. A <a href="http://css-tricks.com/poll-results-how-do-you-order-your-css-properties/">recent poll on CSS-Tricks</a> determined that over 45% developers order their declarations by type against 14% alphabetically. Also, there are 39% that go full random, including myself.</p>

<figure role="group">
  <img src="http://sass-guidelin.es/assets/images/css-order-chart.png" alt="Chart showing how developers order their CSS declarations&#10;"/>
  <figcaption><p>Chart showing how developers order their CSS declarations</p>
</figcaption>
</figure>

<p>Because of this, I will not impose a choice in this styleguide. Pick the one you prefer, as long as you are consistent throughout your stylesheets (i.e. not the <em>random</em> option).</p>

<div class="note">
  <p>A <a href="http://peteschuster.com/2014/12/reduce-file-size-css-sorting/">recent study</a> shows that using <a href="https://github.com/csscomb/csscomb.js">CSS Comb</a> (which uses <a href="https://github.com/csscomb/csscomb.js/blob/master/config/csscomb.json">type ordering</a>) for sorting CSS declarations ends up shortening the average file size under Gzip compression by 2.7%, compared to 1.3% when sorting alphabetically.</p>
</div>

<h6 id="further-reading-11">Further reading</h6>

<h2 id="selector-nesting">Selector Nesting</h2>

<p>One particular feature Sass provides that is being overly misused by many developers is <em>selector nesting</em>. Selector nesting offers a way for stylesheet authors to compute long selectors by nesting shorter selectors within each others.</p>

<h3 id="general-rule">General rule</h3>

<p>For instance, the following Sass nesting:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="nc">.bar</span> <span class="p">{</span>
    <span class="k">&amp;</span><span class="nd">:hover</span> <span class="p">{</span>
      <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="nc">.bar</span>
    <span class="k">&amp;</span><span class="nd">:hover</span>
      <span class="na">color</span><span class="o">:</span> <span class="nb">red</span></code></pre></div>

  </div>
</div>

<p>… will generate this CSS:</p>

<div>

<div class="highlight"><pre><code class="language-css" data-lang="css"><span class="nc">.foo</span> <span class="nc">.bar</span><span class="nd">:hover</span> <span class="p">{</span>
  <span class="k">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

</div>

<p>Along the same lines, since Sass 3.3 it is possible to use the current selector reference (<code>&amp;</code>) to generate advanced selectors. For instance:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="k">&amp;</span><span class="nt">-bar</span> <span class="p">{</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>

</div>

<p>… will generate this CSS:</p>

<p>This method is often used along with <a href="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/">BEM naming conventions</a> to generate <code>.block__element</code> and <code>.block--modifier</code> selectors based on the original selector (i.e. <code>.block</code> in this case).</p>

<div class="note">
  <p>While it might be anecdotal, generating new selectors from the current selector reference (<code>&amp;</code>) makes those selectors unsearchable in the codebase since they do not exist per se.</p>
</div>

<p>The problem with selector nesting is that it ultimately makes code more difficult to read. One has to mentally compute the resulting selector out of the indentation levels; it is not always quite obvious what the CSS will end up being.</p>

<p>This statement becomes truer as selectors get longer and references to the current selector (<code>&amp;</code>) more frequent. At some point, the risk of losing track and not being able to understand what’s going on anymore is so high that it is not worth it.</p>

<p>To prevent such a situation, we <strong>avoid selector nesting as much as possible</strong>. However, there are obviously a few exceptions to this rule.</p>

<h3 id="exceptions">Exceptions</h3>

<p>For starters, it is allowed and even recommended to nest pseudo-classes and pseudo-elements within the initial selector.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>

  <span class="k">&amp;</span><span class="nd">:hover</span> <span class="p">{</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">green</span><span class="p">;</span>
  <span class="p">}</span>

  <span class="na">&amp;</span><span class="o">::</span><span class="n">before</span> <span class="p">{</span>
    <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">pseudo-element'</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span>

  <span class="k">&amp;</span><span class="nd">:hover</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">green</span>

  <span class="na">&amp;</span><span class="o">::</span><span class="n">before</span>
    <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">pseudo-element'</span></code></pre></div>

  </div>
</div>

<p>Using selector nesting for pseudo-classes and pseudo-elements not only makes sense (because it deals with closely related selectors), it also helps keep everything about a component at the same place.</p>

<p>Also, when using component-agnostic state classes such as <code>.is-active</code>, it is perfectly fine to nest it under the component’s selector to keep things tidy.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="c1">// ...</span>

  <span class="k">&amp;</span><span class="nc">.is-active</span> <span class="p">{</span>
    <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="c1">// ...</span>

  <span class="k">&amp;</span><span class="nc">.is-active</span>
    <span class="na">font-weight</span><span class="o">:</span> <span class="no">bold</span></code></pre></div>

  </div>
</div>

<p>Last but not least, when styling an element because it happens to be contained within another specific element, it is also fine to use nesting to keep everything about the component at the same place.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="c1">// ...</span>

  <span class="nc">.no-opacity</span> <span class="k">&amp;</span> <span class="p">{</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">none</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="c1">// ...</span>

  <span class="nc">.no-opacity</span> <span class="k">&amp;</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">none</span></code></pre></div>

  </div>
</div>

<p>When working with unexperienced developers, a selector such as <code>.no-opacity &amp;</code> might look a little weird. To prevent any confusion, you can build a very short mixin that transform this odd syntax into an explicit API.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Helper mixin to provide simple API to selector nesting</span>
<span class="c1">/// @param {String} $selector - Selector</span>
<span class="k">@mixin</span><span class="nf"> when-inside</span><span class="p">(</span><span class="nv">$selector</span><span class="p">)</span> <span class="p">{</span>
  <span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">selector</span><span class="p">}</span> <span class="k">&amp;</span> <span class="p">{</span>
    <span class="k">@content</span><span class="o">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Helper mixin to provide simple API to selector nesting</span>
<span class="c1">/// @param {String} $selector - Selector</span>
<span class="nf">=when-inside</span><span class="p">(</span><span class="nv">$selector</span><span class="p">)</span> <span class="err">{</span>
  <span class="nn">#</span><span class="err">{$</span><span class="nt">selector</span><span class="err">}</span> <span class="k">&amp;</span>
    <span class="k">@content</span>
<span class="err">}</span></code></pre></div>

  </div>
</div>

<p>Rewriting our previous example, it would look like this:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="c1">// ...</span>

  <span class="k">@include</span><span class="nd"> when-inside</span><span class="p">(</span><span class="s1">'</span><span class="s2">.no-opacity'</span><span class="p">)</span> <span class="p">{</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">none</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="c1">// ...</span>

  <span class="nd">+when-inside</span><span class="p">(</span><span class="s1">'</span><span class="s2">.no-opacity'</span><span class="p">)</span>
    <span class="na">display</span><span class="o">:</span> <span class="no">none</span></code></pre></div>

  </div>
</div>

<p>As with everything, the specifics are somewhat irrelevant, consistency is key. If you feel fully confident with selector nesting, then use selector nesting. Just make sure your whole team is okay with that.</p>

<h6 id="further-reading-12">Further reading</h6>

<h1 id="naming-conventions">Naming conventions</h1>

<p>In this section, we will not deal with the best CSS naming conventions for maintainability and scale; not only is that up to you, it’s also out of the scope of a Sass styleguide. I suggest those recommended by <a href="http://cssguidelin.es/#naming-conventions">CSS Guidelines</a>.</p>

<p>There are a few things you can name in Sass, and it is important to name them well so the whole code base looks both consistent and easy to read:</p>

<ul>
  <li>variables;</li>
  <li>functions;</li>
  <li>mixins.</li>
</ul>

<p>Sass placeholders are deliberately omitted from this list since they can be considered as regular CSS selectors, thus following the same naming pattern as classes.</p>

<p>Regarding variables, functions and mixins, we stick to something very <em>CSS-y</em>: <strong>lowercase hyphen-delimited</strong>, and above all meaningful.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$vertical-rhythm-baseline</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">rem</span><span class="p">;</span>

<span class="k">@mixin</span><span class="nf"> size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>

<span class="k">@function</span> <span class="nt">opposite-direction</span><span class="o">(</span><span class="err">$</span><span class="nt">direction</span><span class="o">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="na">$vertical-rhythm-baseline</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">rem</span>

<span class="nf">=size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span>
  <span class="c1">// ...</span>

<span class="k">@function</span> <span class="nt">opposite-direction</span><span class="o">(</span><span class="err">$</span><span class="nt">direction</span><span class="o">)</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-13">Further reading</h6>

<h2 id="constants">Constants</h2>

<p>If you happen to be a framework developer or library writer, you might find yourself dealing with variables that are not meant to be updated in any circumstances: constants. Unfortunately (or fortunately?), Sass does not provide any way to define such entities, so we have to stick to strict naming conventions to make our point.</p>

<p>As for many languages, I suggest all-caps snakerized variables when they are constants. Not only is this a very old convention, but it also contrasts well with usual lowercased hyphenated variables.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$CSS_POSITIONS</span><span class="o">:</span> <span class="p">(</span><span class="no">top</span><span class="o">,</span> <span class="no">right</span><span class="o">,</span> <span class="no">bottom</span><span class="o">,</span> <span class="no">left</span><span class="o">,</span> <span class="no">center</span><span class="p">);</span>

<span class="c1">// Nope</span>
<span class="nv">$css-positions</span><span class="o">:</span> <span class="p">(</span><span class="no">top</span><span class="o">,</span> <span class="no">right</span><span class="o">,</span> <span class="no">bottom</span><span class="o">,</span> <span class="no">left</span><span class="o">,</span> <span class="no">center</span><span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$CSS_POSITIONS</span><span class="o">:</span> <span class="p">(</span><span class="no">top</span><span class="o">,</span> <span class="no">right</span><span class="o">,</span> <span class="no">bottom</span><span class="o">,</span> <span class="no">left</span><span class="o">,</span> <span class="no">center</span><span class="p">)</span>

<span class="c1">// Nope</span>
<span class="na">$css-positions</span><span class="o">:</span> <span class="p">(</span><span class="no">top</span><span class="o">,</span> <span class="no">right</span><span class="o">,</span> <span class="no">bottom</span><span class="o">,</span> <span class="no">left</span><span class="o">,</span> <span class="no">center</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-14">Further reading</h6>

<h2 id="namespace">Namespace</h2>

<p>If you intend to distribute your Sass code, in the case of a library, a framework, a grid system or whatever, you might want to consider namespacing all your variables, functions, mixins and placeholders so it does not conflict with anyone else’s code.</p>

<p>For instance, if you work on a <em>Sassy Unicorn</em> project that is meant to be used by developers all over the world (who wouldn’t, right?), you could consider using <code>su-</code> as a namespace. It is specific enough to prevent any naming collisions and short enough not to be a pain to write.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$su-configuration</span><span class="o">:</span> <span class="p">(</span> <span class="o">...</span> <span class="p">);</span>

<span class="k">@function</span> <span class="nt">su-rainbow</span><span class="o">(</span><span class="err">$</span><span class="nt">unicorn</span><span class="o">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="na">$su-configuration</span><span class="o">:</span> <span class="p">(</span> <span class="o">...</span> <span class="p">)</span>

<span class="k">@function</span> <span class="nt">su-rainbow</span><span class="o">(</span><span class="err">$</span><span class="nt">unicorn</span><span class="o">)</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>Note that automatic namespacing is definitely a design goal for the upcoming <code>@import</code> revamp from Sass 4.0. As that comes closer to fruition, it will become less and less useful to do manual namespacing; eventually, manually-namespaced libraries may actually be harder to use.</p>
</div>

<h6 id="further-reading-15">Further reading</h6>

<p>CSS is a tricky language, full of hacks and oddities. Because of this, it should be heavily commented, especially if you or someone else intend to read and update the code 6 months or 1 year from now. Don’t let you or anybody else be in the position of <em>I-didn’t-write-this-oh-my-god-why</em>.</p>

<p>As simple as CSS can get, there is still a lot of room for comments. These could be explaining:</p>

<ul>
  <li>the structure and/or role of a file;</li>
  <li>the goal of a ruleset;</li>
  <li>the idea behind a magic number;</li>
  <li>the reason for a CSS declaration;</li>
  <li>the order of CSS declarations;</li>
  <li>the thought process behind a way of doing things.</li>
</ul>

<p>And I probably forgot a lot of other various reasons as well. Commenting takes very little time when done seamlessly along with the code so do it at the right time. Coming back at a piece of code to comment it is not only completely unrealistic but also extremely annoying.</p>

<p>Ideally, <em>any</em> CSS ruleset should be preceded by a C-style comment explaining the point of the CSS block. This comment also hosts numbered explanations regarding specific parts of the ruleset. For instance:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="cm">/**</span>
<span class="cm"> * Helper class to truncate and add ellipsis to a string too long for it to fit</span>
<span class="cm"> * on a single line.</span>
<span class="cm"> * 1. Prevent content from wrapping, forcing it on a single line.</span>
<span class="cm"> * 2. Add ellipsis at the end of the line.</span>
<span class="cm"> */</span>
<span class="nc">.ellipsis</span> <span class="p">{</span>
  <span class="na">white-space</span><span class="o">:</span> <span class="no">nowrap</span><span class="p">;</span> <span class="cm">/* 1 */</span>
  <span class="na">text-overflow</span><span class="o">:</span> <span class="n">ellipsis</span><span class="p">;</span> <span class="cm">/* 2 */</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="cm">/**</span>
 <span class="cm">* Helper class to truncate and add ellipsis to a string too long for it to fit</span>
 <span class="cm">* on a single line.</span>
 <span class="cm">* 1. Prevent content from wrapping, forcing it on a single line.</span>
 <span class="cm">* 2. Add ellipsis at the end of the line.</span>
 <span class="cm">*/</span>
<span class="nc">.ellipsis</span>
  <span class="na">white-space</span><span class="o">:</span> <span class="no">nowrap</span> <span class="cm">/* 1 </span><span class="c">*/</span>
  <span class="na">text-overflow</span><span class="o">:</span> <span class="n">ellipsis</span> <span class="cm">/* 2 </span><span class="c">*/</span>
  <span class="na">overflow</span><span class="o">:</span> <span class="no">hidden</span></code></pre></div>

  </div>
</div>

<p>Basically everything that is not obvious at first glance should be commented. There is no such thing as too much documentation. Remember that you cannot <em>comment too much</em>, so get on fire and write comments for everything that is worth it.</p>

<p>When commenting a Sass-specific section, use Sass inline comments instead of a C-style block. This makes the comment invisible in the output, even in expanded mode during development.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Add current module to the list of imported modules.</span>
<span class="c1">// `!global` flag is required so it actually updates the global variable.</span>
<span class="nv">$imported-modules</span><span class="o">:</span> <span class="nf">append</span><span class="p">(</span><span class="nv">$imported-modules</span><span class="o">,</span> <span class="nv">$module</span><span class="p">)</span> <span class="nv">!global</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Add current module to the list of imported modules.</span>
<span class="c1">// `!global` flag is required so it actually updates the global variable.</span>
<span class="na">$imported-modules</span><span class="o">:</span> <span class="nf">append</span><span class="p">(</span><span class="nv">$imported-modules</span><span class="o">,</span> <span class="nv">$module</span><span class="p">)</span> <span class="nv">!global</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-16">Further reading</h6>

<h2 id="documentation">Documentation</h2>

<p>Every variable, function, mixin and placeholder that is intended to be reused all over the codebase should be documented as part of the global API using <a href="http://sassdoc.com">SassDoc</a>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Vertical rhythm baseline used all over the code base.</span>
<span class="c1">/// @type Length</span>
<span class="nv">$vertical-rhythm-baseline</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">rem</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Vertical rhythm baseline used all over the code base.</span>
<span class="c1">/// @type Length</span>
<span class="na">$vertical-rhythm-baseline</span><span class="o">:</span> <span class="mi">1</span><span class="mf">.5</span><span class="kt">rem</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>Three slashes (<code>/</code>) required.</p>
</div>

<p>SassDoc has two major roles:</p>

<ul>
  <li>forcing standardized comments using an annotation-based system for everything that is part of a public or private API;</li>
  <li>being able to generate an HTML version of the API documentation by using any of the SassDoc endpoints (CLI tool, Grunt, Gulp, Broccoli, Node…).</li>
</ul>

<figure role="group">
  <img alt="Documentation generated by SassDoc&#10;" sizes="100vw" srcset="http://sass-guidelin.es/assets/images/sassdoc-preview_small.png  540w,&#10;               http://sass-guidelin.es/assets/images/sassdoc-preview_medium.png 900w,&#10;               http://sass-guidelin.es/assets/images/sassdoc-preview_large.png 1200w,&#10;               http://sass-guidelin.es/assets/images/sassdoc-preview_huge.png  1590w"/>
  <figcaption><p>Documentation generated by SassDoc</p>
</figcaption>
</figure>

<p>Here is an example of a mixin extensively documented with SassDoc:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Mixin helping defining both `width` and `height` simultaneously.</span>
<span class="c1">///</span>
<span class="c1">/// @author Hugo Giraudel</span>
<span class="c1">///</span>
<span class="c1">/// @access public</span>
<span class="c1">///</span>
<span class="c1">/// @param {Length} $width - Element’s `width`</span>
<span class="c1">/// @param {Length} $height ($width) - Element’s `height`</span>
<span class="c1">///</span>
<span class="c1">/// @example scss - Usage</span>
<span class="c1">///   .foo {</span>
<span class="c1">///     @include size(10em);</span>
<span class="c1">///   }</span>
<span class="c1">///</span>
<span class="c1">///   .bar {</span>
<span class="c1">///     @include size(100%, 10em);</span>
<span class="c1">///   }</span>
<span class="c1">///</span>
<span class="c1">/// @example css - CSS output</span>
<span class="c1">///   .foo {</span>
<span class="c1">///     width: 10em;</span>
<span class="c1">///     height: 10em;</span>
<span class="c1">///   }</span>
<span class="c1">///</span>
<span class="c1">///   .bar {</span>
<span class="c1">///     width: 100%;</span>
<span class="c1">///     height: 10em;</span>
<span class="c1">///   }</span>
<span class="k">@mixin</span><span class="nf"> size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span> <span class="p">{</span>
  <span class="na">width</span><span class="o">:</span> <span class="nv">$width</span><span class="p">;</span>
  <span class="na">height</span><span class="o">:</span> <span class="nv">$height</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Mixin helping defining both `width` and `height` simultaneously.</span>
<span class="c1">///</span>
<span class="c1">/// @author Hugo Giraudel</span>
<span class="c1">///</span>
<span class="c1">/// @access public</span>
<span class="c1">///</span>
<span class="c1">/// @param {Length} $width - Element’s `width`</span>
<span class="c1">/// @param {Length} $height ($width) - Element’s `height`</span>
<span class="c1">///</span>
<span class="c1">/// @example scss - Usage</span>
<span class="c1">///   .foo</span>
<span class="c1">///     +size(10em)</span>
<span class="c1">///</span>
<span class="c1">///   .bar</span>
<span class="c1">///     +size(100%, 10em)</span>
<span class="c1">///</span>
<span class="c1">/// @example css - CSS output</span>
<span class="c1">///   .foo {</span>
<span class="c1">///     width: 10em;</span>
<span class="c1">///     height: 10em;</span>
<span class="c1">///   }</span>
<span class="c1">///</span>
<span class="c1">///   .bar {</span>
<span class="c1">///     width: 100%;</span>
<span class="c1">///     height: 10em;</span>
<span class="c1">///   }</span>
<span class="nf">=size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span>
  <span class="na">width</span><span class="o">:</span> <span class="nv">$width</span>
  <span class="na">height</span><span class="o">:</span> <span class="nv">$height</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-17">Further reading</h6>

<h1 id="architecture">Architecture</h1>

<p>Architecting a CSS project is probably one of the most difficult things you will have to do in a project’s life. Keeping the architecture consistent and meaningful is even harder.</p>

<p>Fortunately, one of the main benefits of using a CSS preprocessor is having the ability to split the codebase over several files without impacting performance (like the <code>@import</code> CSS directive would do). Thanks to Sass’s overload of the <code>@import</code> directive, it is perfectly safe (and actually recommended) to use as many files as necessary in development, all compiled into a single stylesheet when going to production.</p>

<p>On top of that, I cannot stress enough the need for folders, even on small scale projects. At home, you don’t drop every sheet of paper into the same box. You use folders; one for the house/flat, one for the bank, one for bills, and so on. There is no reason to do otherwise when structuring a CSS project. Split the codebase into meaningful separated folders so it is easy to find stuff later when you have to come back to the code.</p>

<p>There are a lot of popular architectures for CSS projects: <a href="http://oocss.org/">OOCSS</a>, <a href="http://bradfrost.com/blog/post/atomic-web-design/">Atomic Design</a>, <a href="http://getbootstrap.com/">Bootstrap</a>-like, <a href="http://foundation.zurb.com/">Foundation</a>-like… They all have their merits, pros and cons.</p>

<p>I, myself, use an approach that happens to be quite similar to <a href="https://smacss.com/">SMACSS</a> from <a href="http://snook.ca/">Jonathan Snook</a>, which focuses on keeping things simple and obvious.</p>

<div class="note">
  <p>I have learnt that architecture is most of the time very specific to the project. Feel free to discard completely or adapt the proposed solution so that you deal with a system that suits your needs.</p>
</div>

<h6 id="further-reading-18">Further reading</h6>

<h2 id="components">Components</h2>

<p>There is a major difference between making it <em>work</em>, and making it <em>good</em>. Again, CSS is quite a messy language <sup>[citation needed]</sup>. The less CSS we have, the merrier. We don’t want to deal with megabytes of CSS code. To keep stylesheets short and efficient—and this will not be any surprise to you—it is usually a good idea to think of an interface as a collection of components.</p>

<p>Components can be anything, as long as they:</p>

<ul>
  <li>do one thing and one thing only;</li>
  <li>are re-usable and re-used across the project;</li>
  <li>are independent.</li>
</ul>

<p>For instance, a search form should be treated as a component. It should be reusable, at different positions, on different pages, in various situations. It should not depend on its position in the DOM (footer, sidebar, main content…).</p>

<p>Most of any interface can be thought of as little components and I highly recommend you stick to this paradigm. This will not only shorten the amount of CSS needed for the whole project, but also happens to be much easier to maintain than a chaotic mess where everything is flustered.</p>

<h2 id="the-7-1-pattern">The 7-1 pattern</h2>

<p>Back to architecture, shall we? I usually go with what I call the <em>7-1 pattern</em>: 7 folders, 1 file. Basically, you have all your partials stuffed into 7 different folders, and a single file at the root level (usually named <code>main.scss</code>) which imports them all to be compiled into a CSS stylesheet.</p>

<ul>
  <li><code>base/</code></li>
  <li><code>components/</code></li>
  <li><code>layout/</code></li>
  <li><code>pages/</code></li>
  <li><code>themes/</code></li>
  <li><code>utils/</code></li>
  <li><code>vendors/</code></li>
</ul>

<p>And of course:</p>

<figure role="group">
  <img alt="Wallpaper by Julien He&#10;" sizes="100vw" srcset="http://sass-guidelin.es/assets/images/sass-wallpaper_small.jpg  540w,&#10;             http://sass-guidelin.es/assets/images/sass-wallpaper_medium.jpg 900w,&#10;             http://sass-guidelin.es/assets/images/sass-wallpaper_large.jpg 1200w,&#10;             http://sass-guidelin.es/assets/images/sass-wallpaper_huge.jpg  1590w"/>
  <figcaption><p>Wallpaper by <a href="https://twitter.com/julien_he">Julien He</a></p>
</figcaption>
</figure>

<p>Ideally, we can come up with something like this:</p>

<div class="highlight"><pre><code>
sass/
|
|– base/
|   |– _reset.scss       # Reset/normalize
|   |– _typography.scss  # Typography rules
|   ...                  # Etc…
|
|– components/
|   |– _buttons.scss     # Buttons
|   |– _carousel.scss    # Carousel
|   |– _cover.scss       # Cover
|   |– _dropdown.scss    # Dropdown
|   ...                  # Etc…
|
|– layout/
|   |– _navigation.scss  # Navigation
|   |– _grid.scss        # Grid system
|   |– _header.scss      # Header
|   |– _footer.scss      # Footer
|   |– _sidebar.scss     # Sidebar
|   |– _forms.scss       # Forms
|   ...                  # Etc…
|
|– pages/
|   |– _home.scss        # Home specific styles
|   |– _contact.scss     # Contact specific styles
|   ...                  # Etc…
|
|– themes/
|   |– _theme.scss       # Default theme
|   |– _admin.scss       # Admin theme
|   ...                  # Etc…
|
|– utils/
|   |– _variables.scss   # Sass Variables
|   |– _functions.scss   # Sass Functions
|   |– _mixins.scss      # Sass Mixins
|   |– _helpers.scss     # Class &amp; placeholders helpers
|
|– vendors/
|   |– _bootstrap.scss   # Bootstrap
|   |– _jquery-ui.scss   # jQuery UI
|   ...                  # Etc…
|
|
`– main.scss             # Main Sass file
</code></pre></div>

<div class="note">
  <p>Files follow the same naming conventions described above: they are hyphen-delimited.</p>
</div>

<h3 id="base-folder">Base folder</h3>

<p>The <code>base/</code> folder holds what we might call the boilerplate code for the project. In there, you might find the reset file, some typographic rules, and probably a stylesheet (that I’m used to calling <code>_base.scss</code>), defining some standard styles for commonly used HTML elements.</p>

<ul>
  <li><code>_base.scss</code></li>
  <li><code>_reset.scss</code></li>
  <li><code>_typography.scss</code></li>
</ul>

<h3 id="layout-folder">Layout folder</h3>

<p>The <code>layout/</code> folder contains everything that takes part in laying out the site or application. This folder could have stylesheets for the main parts of the site (header, footer, navigation, sidebar…), the grid system or even CSS styles for all the forms.</p>

<ul>
  <li><code>_grid.scss</code></li>
  <li><code>_header.scss</code></li>
  <li><code>_footer.scss</code></li>
  <li><code>_sidebar.scss</code></li>
  <li><code>_forms.scss</code></li>
  <li><code>_navigation.scss</code></li>
</ul>

<div class="note">
  <p>The <code>layout/</code> folder might also be called <code>partials/</code>, depending on what you prefer.</p>
</div>

<h3 id="components-folder">Components folder</h3>

<p>For smaller components, there is the <code>components/</code> folder. While <code>layout/</code> is <em>macro</em> (defining the global wireframe), <code>components/</code> is more focused on widgets. It contains all kind of specific modules like a slider, a loader, a widget, and basically anything along those lines. There are usually a lot of files in <code>components/</code> since the whole site/application should be mostly composed of tiny modules.</p>

<ul>
  <li><code>_media.scss</code></li>
  <li><code>_carousel.scss</code></li>
  <li><code>_thumbnails.scss</code></li>
</ul>

<div class="note">
  <p>The <code>components/</code> folder might also be called <code>modules/</code>, depending on what you prefer.</p>
</div>

<h3 id="pages-folder">Pages folder</h3>

<p>If you have page-specific styles, it is better to put them in a <code>pages/</code> folder, in a file named after the page. For instance, it’s not uncommon to have very specific styles for the home page hence the need for a <code>_home.scss</code> file in <code>pages/</code>.</p>

<div class="note">
  <p>Depending on your deployment process, these files could be called on their own to avoid merging them with the others in the resulting stylesheet. It is really up to you.</p>
</div>

<h3 id="themes-folder">Themes folder</h3>

<p>On large sites and applications, it is not unusual to have different themes. There are certainly different ways of dealing with themes but I personally like having them all in a <code>themes/</code> folder.</p>

<div class="note">
  <p>This is very project-specific and is likely to be non-existent on many projects.</p>
</div>

<h3 id="utils-folder">Utils folder</h3>

<p>The <code>utils/</code> folder gathers all Sass tools and helpers used across the project. Every global variable, function, mixin and placeholder should be put in here.</p>

<p>The rule of thumb for this folder is that it should not output a single line of CSS when compiled on its own. These are nothing but Sass helpers.</p>

<ul>
  <li><code>_variables.scss</code></li>
  <li><code>_mixins.scss</code></li>
  <li><code>_functions.scss</code></li>
  <li><code>_placeholders.scss</code> (frequently named <code>_helpers.scss</code>)</li>
</ul>

<div class="note">
  <p>The <code>utils/</code> folder might also be called <code>helpers/</code>, <code>sass-helpers/</code> or <code>sass-utils/</code>, depending on what you prefer.</p>
</div>

<h3 id="vendors-folder">Vendors folder</h3>

<p>And last but not least, most projects will have a <code>vendors/</code> folder containing all the CSS files from external libraries and frameworks – Normalize, Bootstrap, jQueryUI, FancyCarouselSliderjQueryPowered, and so on. Putting those aside in the same folder is a good way to say “Hey, this is not from me, not my code, not my responsibility”.</p>

<ul>
  <li><code>_normalize.scss</code></li>
  <li><code>_bootstrap.scss</code></li>
  <li><code>_jquery-ui.scss</code></li>
  <li><code>_select2.scss</code></li>
</ul>

<p>If you have to override a section of any vendor, I recommend you have an 8th folder called <code>vendors-extensions/</code> in which you may have files named exactly after the vendors they overwrite.</p>

<p>For instance, <code>vendors-extensions/_bootstrap.scss</code> is a file containing all CSS rules intended to re-declare some of Bootstrap’s default CSS. This is to avoid editing the vendor files themselves, which is generally not a good idea.</p>

<h3 id="main-file">Main file</h3>

<p>The main file (usually labelled <code>main.scss</code>) should be the only Sass file from the whole code base not to begin with an underscore. This file should not contain anything but <code>@import</code> and comments.</p>

<p>Files should be imported according to the folder they live in, one after the other in the following order:</p>

<ol>
  <li><code>vendors/</code></li>
  <li><code>utils/</code></li>
  <li><code>base/</code></li>
  <li><code>layout/</code></li>
  <li><code>components/</code></li>
  <li><code>pages/</code></li>
  <li><code>themes/</code></li>
</ol>

<p>In order to preserve readability, the main file should respect these guidelines:</p>

<ul>
  <li>one file per <code>@import</code>;</li>
  <li>one <code>@import</code> per line;</li>
  <li>no new line between two imports from the same folder;</li>
  <li>a new line after the last import from a folder;</li>
  <li>file extensions and leading underscores omitted.</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@import</span> <span class="s1">'</span><span class="s2">vendors/bootstrap'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">vendors/jquery-ui'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">utils/variables'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">utils/functions'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">utils/mixins'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">utils/placeholders'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">base/reset'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">base/typography'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/navigation'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/grid'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/header'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/footer'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/sidebar'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">layout/forms'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">components/buttons'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">components/carousel'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">components/cover'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">components/dropdown'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">pages/home'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">pages/contact'</span><span class="p">;</span>

<span class="k">@import</span> <span class="s1">'</span><span class="s2">themes/theme'</span><span class="p">;</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">themes/admin'</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@import</span> <span class="s">vendors/bootstrap</span>
<span class="k">@import</span> <span class="s">vendors/jquery-ui</span>

<span class="k">@import</span> <span class="s">utils/variables</span>
<span class="k">@import</span> <span class="s">utils/functions</span>
<span class="k">@import</span> <span class="s">utils/mixins</span>
<span class="k">@import</span> <span class="s">utils/placeholders</span>

<span class="k">@import</span> <span class="s">base/reset</span>
<span class="k">@import</span> <span class="s">base/typography</span>

<span class="k">@import</span> <span class="s">layout/navigation</span>
<span class="k">@import</span> <span class="s">layout/grid</span>
<span class="k">@import</span> <span class="s">layout/header</span>
<span class="k">@import</span> <span class="s">layout/footer</span>
<span class="k">@import</span> <span class="s">layout/sidebar</span>
<span class="k">@import</span> <span class="s">layout/forms</span>

<span class="k">@import</span> <span class="s">components/buttons</span>
<span class="k">@import</span> <span class="s">components/carousel</span>
<span class="k">@import</span> <span class="s">components/cover</span>
<span class="k">@import</span> <span class="s">components/dropdown</span>

<span class="k">@import</span> <span class="s">pages/home</span>
<span class="k">@import</span> <span class="s">pages/contact</span>

<span class="k">@import</span> <span class="s">themes/theme</span>
<span class="k">@import</span> <span class="s">themes/admin</span></code></pre></div>

  </div>
</div>

<p>There is another way of importing partials that I deem valid as well. On the bright side, it makes the file more readable. On the other hand, it makes updating it slightly more painful. Anyway, I’ll let you decide which is best, it does not matter much. For this way of doing, the main file should respect these guidelines:</p>

<ul>
  <li>one <code>@import</code> per folder;</li>
  <li>a linebreak after <code>@import</code>;</li>
  <li>each file on its own line;</li>
  <li>a new line after the last import from a folder;</li>
  <li>file extensions and leading underscores omitted.</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@import</span>
  <span class="s1">'</span><span class="s2">vendors/bootstrap'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">vendors/jquery-ui'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">utils/variables'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">utils/functions'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">utils/mixins'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">utils/placeholders'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">base/reset'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">base/typography'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">layout/navigation'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">layout/grid'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">layout/header'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">layout/footer'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">layout/sidebar'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">layout/forms'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">components/buttons'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">components/carousel'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">components/cover'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">components/dropdown'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">pages/home'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">pages/contact'</span><span class="p">;</span>

<span class="k">@import</span>
  <span class="s1">'</span><span class="s2">themes/theme'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">themes/admin'</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@import</span>
  <span class="nt">vendors</span><span class="o">/</span><span class="nt">bootstrap</span><span class="o">,</span>
  <span class="nt">vendors</span><span class="o">/</span><span class="nt">jquery-ui</span>

<span class="k">@import</span>
  <span class="nt">utils</span><span class="o">/</span><span class="nt">variables</span><span class="o">,</span>
  <span class="nt">utils</span><span class="o">/</span><span class="nt">functions</span><span class="o">,</span>
  <span class="nt">utils</span><span class="o">/</span><span class="nt">mixins</span><span class="o">,</span>
  <span class="nt">utils</span><span class="o">/</span><span class="nt">placeholders</span>

<span class="k">@import</span>
  <span class="nt">base</span><span class="o">/</span><span class="nt">reset</span><span class="o">,</span>
  <span class="nt">base</span><span class="o">/</span><span class="nt">typography</span>

<span class="k">@import</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">navigation</span><span class="o">,</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">grid</span><span class="o">,</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">header</span><span class="o">,</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">footer</span><span class="o">,</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">sidebar</span><span class="o">,</span>
  <span class="nt">layout</span><span class="o">/</span><span class="nt">forms</span>

<span class="k">@import</span>
  <span class="nt">components</span><span class="o">/</span><span class="nt">buttons</span><span class="o">,</span>
  <span class="nt">components</span><span class="o">/</span><span class="nt">carousel</span><span class="o">,</span>
  <span class="nt">components</span><span class="o">/</span><span class="nt">cover</span><span class="o">,</span>
  <span class="nt">components</span><span class="o">/</span><span class="nt">dropdown</span>

<span class="k">@import</span>
  <span class="nt">pages</span><span class="o">/</span><span class="nt">home</span><span class="o">,</span>
  <span class="nt">pages</span><span class="o">/</span><span class="nt">contact</span>

<span class="k">@import</span>
  <span class="nt">themes</span><span class="o">/</span><span class="nt">theme</span><span class="o">,</span>
  <span class="nt">themes</span><span class="o">/</span><span class="nt">admin</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>In order to not have to import each file manually, there is an extension to Ruby Sass called <a href="https://github.com/chriseppstein/sass-globbing">sass-globbing</a>, making it possible to use glob patterns in Sass <code>@import</code> such as <code>@import "components/*"</code>.</p>
  <p>That being said, I would not recommend it because it imports files following the alphabetical order which is usually not what you want, especially when dealing with a source-order dependent language.</p>
</div>

<h2 id="shame-file">Shame file</h2>

<p>There is an interesting concept that has been made popular by <a href="http://csswizardry.com">Harry Roberts</a>, <a href="http://daverupert.com">Dave Rupert</a> and <a href="http://css-tricks.com">Chris Coyier</a> that consists of putting all the CSS declarations, hacks and things we are not proud of in a <em>shame file</em>. This file, dramatically titled <code>_shame.scss</code>, would be imported after any other file, at the very end of the stylesheet.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="cm">/**</span>
<span class="cm"> * Nav specificity fix.</span>
<span class="cm"> *</span>
<span class="cm"> * Someone used an ID in the header code (`#header a {}`) which trumps the</span>
<span class="cm"> * nav selectors (`.site-nav a {}`). Use !important to override it until I</span>
<span class="cm"> * have time to refactor the header stuff.</span>
<span class="cm"> */</span>
<span class="nc">.site-nav</span> <span class="nt">a</span> <span class="p">{</span>
    <span class="na">color</span><span class="o">:</span> <span class="mh">#BADA55</span> <span class="nv">!important</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="cm">/**</span>
 <span class="cm">* Nav specificity fix.</span>
 <span class="cm">*</span>
 <span class="cm">* Someone used an ID in the header code (`#header a {}`) which trumps the</span>
 <span class="cm">* nav selectors (`.site-nav a {}`). Use !important to override it until I</span>
 <span class="cm">* have time to refactor the header stuff.</span>
 <span class="cm">*/</span>
<span class="nc">.site-nav</span> <span class="nt">a</span>
    <span class="na">color</span><span class="o">:</span> <span class="mh">#BADA55</span> <span class="nv">!important</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-19">Further reading</h6>

<h1 id="responsive-web-design-and-breakpoints">Responsive Web Design and breakpoints</h1>

<p>I do not think we still have to introduce Responsive Web Design now that it is everywhere. However you might ask yourself <em>why is there a section about RWD in a Sass styleguide?</em> Actually there are quite a few things that can be done to make working with breakpoints easier, so I thought it would not be such a bad idea to list them here.</p>

<h2 id="naming-breakpoints">Naming breakpoints</h2>

<p>I think it is safe to say that media queries should not be tied to specific devices. For instance, this is definitely a bad idea to try targeting iPads or Blackberry phones specifically. Media queries should take care of a range of screen sizes, until the design breaks and the next media query takes over.</p>

<p>For the same reasons, breakpoints should not be named after devices but something more general. Especially since some phones are now bigger than tablets, some tablets bigger than some tiny screen computers, and so on…</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">medium'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">large'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">huge'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
<span class="p">);</span>

<span class="c1">// Nope</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">tablet'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">computer'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">tv'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
<span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">medium'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">large'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">huge'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">))</span>

<span class="c1">// Nope</span>
<span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">tablet'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">computer'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">tv'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">))</span></code></pre></div>

  </div>
</div>

<p>At this point, any naming convention that makes crystal clear that a design is not intimately tied to a specific device type will do the trick, as long as it gives a sense of magnitude.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">seed'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">sprout'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">plant'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span>
<span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nv">$breakpoints</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">seed'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">800</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">sprout'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1000</span><span class="kt">px</span><span class="p">)</span><span class="o">,</span> <span class="s1">'</span><span class="s2">plant'</span><span class="o">:</span> <span class="p">(</span><span class="no">min-width</span><span class="o">:</span> <span class="mi">1200</span><span class="kt">px</span><span class="p">))</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>The previous examples uses nested maps to define breakpoints, however this really depends on what kind of breakpoint manager you use. You could opt for strings rather than inner maps for more flexibility (e.g. <code>'(min-width: 800px)'</code>).</p>
</div>

<h6 id="further-reading-20">Further reading</h6>

<h2 id="breakpoint-manager">Breakpoint manager</h2>

<p>Once you have named your breakpoints the way you want, you need a way to use them in actual media queries. There are plenty of ways to do so but I must say I am a big fan of the breakpoint map read by a getter function. This system is both simple and efficient.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Responsive manager.</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $breakpoint - Breakpoint</span>
<span class="c1">/// @requires $breakpoints</span>
<span class="k">@mixin</span><span class="nf"> respond-to</span><span class="p">(</span><span class="nv">$breakpoint</span><span class="p">)</span> <span class="p">{</span>
  <span class="nv">$raw-query</span><span class="o">:</span> <span class="nf">map-get</span><span class="p">(</span><span class="nv">$breakpoints</span><span class="o">,</span> <span class="nv">$breakpoint</span><span class="p">);</span>

  <span class="k">@if</span> <span class="nv">$raw-query</span> <span class="p">{</span>
    <span class="nv">$query</span><span class="o">:</span> <span class="nf">if</span><span class="p">(</span><span class="nf">type-of</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">)</span> <span class="o">==</span> <span class="s1">'</span><span class="s2">string'</span><span class="o">,</span> <span class="nf">unquote</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">)</span><span class="o">,</span> <span class="nf">inspect</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">));</span>

    <span class="k">@media</span> <span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">query</span><span class="p">}</span> <span class="p">{</span>
      <span class="k">@content</span><span class="o">;</span>
    <span class="p">}</span>
  <span class="p">}</span> <span class="k">@else</span> <span class="p">{</span>
    <span class="k">@error</span> <span class="s1">'</span><span class="s2">No value found for `</span><span class="si">#{</span><span class="nv">$breakpoint</span><span class="si">}</span><span class="s2">`. '</span>
         <span class="o">+</span> <span class="s1">'</span><span class="s2">Please make sure it is defined in `$breakpoints` map.'</span><span class="o">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Responsive manager.</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $breakpoint - Breakpoint</span>
<span class="c1">/// @requires $breakpoints</span>
<span class="nf">=respond-to</span><span class="p">(</span><span class="nv">$breakpoint</span><span class="p">)</span>
  <span class="na">$raw-query</span><span class="o">:</span> <span class="nf">map-get</span><span class="p">(</span><span class="nv">$breakpoints</span><span class="o">,</span> <span class="nv">$breakpoint</span><span class="p">)</span>

  <span class="k">@if</span> <span class="nv">$raw-query</span>
    <span class="nv">$query</span><span class="o">:</span> <span class="nf">if</span><span class="p">(</span><span class="nf">type-of</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">)</span> <span class="o">==</span> <span class="s1">'</span><span class="s2">string'</span><span class="o">,</span> <span class="nf">unquote</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">)</span><span class="o">,</span> <span class="nf">inspect</span><span class="p">(</span><span class="nv">$raw-query</span><span class="p">))</span>

    <span class="k">@media</span> <span class="nn">#</span><span class="err">{$</span><span class="nt">query</span><span class="err">}</span>
      <span class="k">@content</span>

  <span class="k">@else</span>
    <span class="k">@error</span> <span class="s1">'</span><span class="s2">No value found for `</span><span class="si">#{</span><span class="nv">$breakpoint</span><span class="si">}</span><span class="s2">`. '</span>
         <span class="o">+</span> <span class="s1">'</span><span class="s2">Please make sure it is defined in `$breakpoints` map.'</span></code></pre></div>

  </div>
</div>

<div class="note">
  <p>Obviously, this is a fairly simplistic breakpoint manager. If you need a slightly more permissive one, may I recommend you do not reinvent the wheel and use something that has been proven effective such as <a href="https://github.com/sass-mq/sass-mq">Sass-MQ</a>, <a href="http://breakpoint-sass.com/">Breakpoint</a> or <a href="https://github.com/eduardoboucas/include-media">include-media</a>.</p>
</div>

<h6 id="further-reading-21">Further reading</h6>

<p>Not so long ago, there was quite a hot debate about where media queries should be written: do they belong within selectors (as Sass allows it) or strictly dissociated from them? I have to say I am a fervent defender of the <em>media-queries-within-selectors</em> system, as I think it plays well with the ideas of <em>components</em>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>

  <span class="k">@include</span><span class="nd"> respond-to</span><span class="p">(</span><span class="s1">'</span><span class="s2">medium'</span><span class="p">)</span> <span class="p">{</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">blue</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">color</span><span class="o">:</span> <span class="nb">red</span>

  <span class="nd">+respond-to</span><span class="p">(</span><span class="s1">'</span><span class="s2">medium'</span><span class="p">)</span>
    <span class="na">color</span><span class="o">:</span> <span class="nb">blue</span></code></pre></div>

  </div>
</div>

<p>Leading to the following CSS output:</p>

<div>

<div class="highlight"><pre><code class="language-css" data-lang="css"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="k">color</span><span class="o">:</span> <span class="nb">red</span><span class="p">;</span>
<span class="p">}</span>

<span class="k">@media</span> <span class="o">(</span><span class="nt">min-width</span><span class="o">:</span> <span class="nt">800px</span><span class="o">)</span> <span class="p">{</span>
  <span class="nc">.foo</span> <span class="p">{</span>
    <span class="k">color</span><span class="o">:</span> <span class="nb">blue</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

</div>

<p>You might hear that this convention results in duplicated media queries in the CSS output. That is definitely true. Although, <a href="http://sasscast.tumblr.com/post/38673939456/sass-and-media-queries">tests have been made</a> and the final word is that it doesn’t matter once Gzip (or any equivalent) has done its thing:</p>

<blockquote>
  <p>… we hashed out whether there were performance implications of combining vs scattering Media Queries and came to the conclusion that the difference, while ugly, is minimal at worst, essentially non-existent at best.<br/>
— <a href="https://twitter.com/snugug">Sam Richards</a>, regarding <a href="http://breakpoint-sass.com/">Breakpoint</a></p>
</blockquote>

<p>Now, if you really are concerned about duplicated media queries, you can still use a tool to merge them such as <a href="https://github.com/aaronjensen/sass-media_query_combiner">this gem</a> however I feel like I have to warn you against possible side-effects of moving CSS code around. You are not without knowing that source order is important.</p>

<h6 id="further-reading-22">Further reading</h6>

<h1 id="variables">Variables</h1>

<p>Variables are the essence of any programming language. They allow us to reuse values without having to copy them over and over again. Most importantly, they make updating a value very easy. No more find and replace or manual crawling.</p>

<p>However CSS is nothing but a huge basket containing all our eggs. Unlike many languages, there are no real scopes in CSS. Because of this, we have to pay real attention when adding variables at the risk of witnessing conflicts.</p>

<p>My advice would be to only create variables when it makes sense to do so. Do not initiate new variables for the heck of it, it won’t help. A new variable should be created only when all of the following criteria are met:</p>

<ul>
  <li>the value is repeated at least twice;</li>
  <li>the value is likely to be updated at least once;</li>
  <li>all occurrences of the value are tied to the variable (i.e. not by coincidence).</li>
</ul>

<p>Basically, there is no point declaring a variable that will never be updated or that is only being used at a single place.</p>

<h2 id="scoping">Scoping</h2>

<p>Variable scoping in Sass has changed over the years. Until fairly recently, variable declarations within rulesets and other scopes were local by default. However when there was already a global variable with the same name, the local assignment would change the global variable. Since version 3.4, Sass now properly tackles the concept of scopes and create a new local variable instead.</p>

<p>The docs talk about <em>global variable shadowing</em>. When declaring a variable that already exists on the global scope in an inner scope (selector, function, mixin…), the local variable is said to be <em>shadowing</em> the global one. Basically, it overrides it just for the local scope.</p>

<p>The following code snippet explains the <em>variable shadowing</em> concept.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Initialize a global variable at root level.</span>
<span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">initial value'</span><span class="p">;</span>

<span class="c1">// Create a mixin that overrides that global variable.</span>
<span class="k">@mixin</span><span class="nf"> global-variable-overriding</span> <span class="p">{</span>
  <span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">mixin value'</span> <span class="nv">!global</span><span class="p">;</span>
<span class="p">}</span>

<span class="na">.local-scope</span><span class="o">::</span><span class="n">before</span> <span class="p">{</span>
  <span class="c1">// Create a local variable that shadows the global one.</span>
  <span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">local value'</span><span class="p">;</span>

  <span class="c1">// Include the mixin: it overrides the global variable.</span>
  <span class="k">@include</span><span class="nd"> global-variable-overriding</span><span class="p">;</span>

  <span class="c1">// Print the variable’s value.</span>
  <span class="c1">// It is the **local** one, since it shadows the global one.</span>
  <span class="na">content</span><span class="o">:</span> <span class="nv">$variable</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// Print the variable in another selector that does no shadowing.</span>
<span class="c1">// It is the **global** one, as expected.</span>
<span class="na">.other-local-scope</span><span class="o">::</span><span class="n">before</span> <span class="p">{</span>
  <span class="na">content</span><span class="o">:</span> <span class="nv">$variable</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Initialize a global variable at root level.</span>
<span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">initial value'</span>

<span class="c1">// Create a mixin that overrides that global variable.</span>
<span class="k">@mixin</span><span class="nf"> global-variable-overriding</span>
  <span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">mixin value'</span> <span class="nv">!global</span>

<span class="na">.local-scope</span><span class="o">::</span><span class="n">before</span>
  <span class="c1">// Create a local variable that shadows the global one.</span>
  <span class="nv">$variable</span><span class="o">:</span> <span class="s1">'</span><span class="s2">local value'</span>

  <span class="c1">// Include the mixin: it overrides the global variable.</span>
  <span class="nd">+global-variable-overriding</span>

  <span class="c1">// Print the variable’s value.</span>
  <span class="c1">// It is the **local** one, since it shadows the global one.</span>
  <span class="na">content</span><span class="o">:</span> <span class="nv">$variable</span>

<span class="c1">// Print the variable in another selector that does no shadowing.</span>
<span class="c1">// It is the **global** one, as expected.</span>
<span class="na">.other-local-scope</span><span class="o">::</span><span class="n">before</span>
  <span class="na">content</span><span class="o">:</span> <span class="nv">$variable</span></code></pre></div>

  </div>
</div>

<h2 id="default-flag"><code>!default</code> flag</h2>

<p>When building a library, a framework, a grid system or any piece of Sass that is intended to be distributed and used by external developers, all configuration variables should be defined with the <code>!default</code> flag so they can be overwritten.</p>

<p>Thanks to this, a developer can define his own <code>$baseline</code> variable <em>before</em> importing your library without seeing his value redefined.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Developer’s own variable</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span><span class="p">;</span>

<span class="c1">// Your library declaring `$baseline`</span>
<span class="k">@import</span> <span class="s1">'</span><span class="s2">your-library'</span><span class="p">;</span>

<span class="c1">// $baseline == 2em;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Developer’s own variable</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span>

<span class="c1">// Your library declaring `$baseline`</span>
<span class="k">@import</span> <span class="s">your-library</span>

<span class="c1">// $baseline == 2em</span></code></pre></div>

  </div>
</div>

<h2 id="global-flag"><code>!global</code> flag</h2>

<p>The <code>!global</code> flag should only be used when overriding a global variable from a local scope. When defining a variable at root level, the <code>!global</code> flag should be omitted.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span><span class="p">;</span>

<span class="c1">// Nope</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span> <span class="nv">!global</span><span class="p">;</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span>

<span class="c1">// Nope</span>
<span class="nv">$baseline</span><span class="o">:</span> <span class="mi">2</span><span class="kt">em</span> <span class="nv">!global</span></code></pre></div>

  </div>
</div>

<h2 id="multiple-variables-or-maps">Multiple variables or maps</h2>

<p>There are advantages of using maps rather than multiple distinct variables. The main one is the ability to loop over a map, which is not possible with distinct variables.</p>

<p>Another pro of using a map is the ability to create a little getter function to provide a friendlier API. For instance, consider the following Sass code:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Z-indexes map, gathering all Z layers of the application</span>
<span class="c1">/// @access private</span>
<span class="c1">/// @type Map</span>
<span class="c1">/// @prop {String} key - Layer's name</span>
<span class="c1">/// @prop {Number} value - Z value mapped to the key</span>
<span class="nv">$z-indexes</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">modal'</span><span class="o">:</span> <span class="mi">5000</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">dropdown'</span><span class="o">:</span> <span class="mi">4000</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">default'</span><span class="o">:</span> <span class="mi">1</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">below'</span><span class="o">:</span> <span class="mi">-1</span><span class="o">,</span>
<span class="p">);</span>

<span class="c1">/// Get a z-index value from a layer name</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $layer - Layer’s name</span>
<span class="c1">/// @return {Number}</span>
<span class="c1">/// @require $z-indexes</span>
<span class="k">@function</span> <span class="nt">z</span><span class="o">(</span><span class="err">$</span><span class="nt">layer</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@return</span> <span class="nt">map-get</span><span class="o">(</span><span class="err">$</span><span class="nt">z-indexes</span><span class="o">,</span> <span class="err">$</span><span class="nt">layer</span><span class="o">);</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Z-indexes map, gathering all Z layers of the application</span>
<span class="c1">/// @access private</span>
<span class="c1">/// @type Map</span>
<span class="c1">/// @prop {String} key - Layer’s name</span>
<span class="c1">/// @prop {Number} value - Z value mapped to the key</span>
<span class="na">$z-indexes</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">modal'</span><span class="o">:</span> <span class="mi">5000</span><span class="o">,</span> <span class="s1">'</span><span class="s2">dropdown'</span><span class="o">:</span> <span class="mi">4000</span><span class="o">,</span> <span class="s1">'</span><span class="s2">default'</span><span class="o">:</span> <span class="mi">1</span><span class="o">,</span> <span class="s1">'</span><span class="s2">below'</span><span class="o">:</span> <span class="mi">-1</span><span class="o">,</span><span class="p">)</span>

<span class="c1">/// Get a z-index value from a layer name</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $layer - Layer's name</span>
<span class="c1">/// @return {Number}</span>
<span class="c1">/// @require $z-indexes</span>
<span class="k">@function</span> <span class="nt">z</span><span class="o">(</span><span class="err">$</span><span class="nt">layer</span><span class="o">)</span>
  <span class="k">@return</span> <span class="nt">map-get</span><span class="o">(</span><span class="err">$</span><span class="nt">z-indexes</span><span class="o">,</span> <span class="err">$</span><span class="nt">layer</span><span class="o">)</span></code></pre></div>

  </div>
</div>

<h1 id="extend">Extend</h1>

<p>The <code>@extend</code> directive has to be one of the features that made Sass so popular a couple of years ago. As a reminder, it makes it possible to tell Sass to style an element A exactly as though it also matched selector B. Needless to say this can end up being a valuable ally when writing modular CSS.</p>

<p>However I feel like I must warn you against this feature. As clever as it is, <code>@extend</code> still is a tricky concept that might do more harm than good, especially when poorly used. The thing is, when extending a selector, you have little to no way to answer these questions without having an in-depth knowledge of the whole codebase:</p>

<ul>
  <li>where is my current selector going to be appended?</li>
  <li>am I likely to be causing undesired side-effects?</li>
  <li>how large is the CSS generated by this single extend?</li>
</ul>

<p>For all you know, the result could range from doing nothing to causing disastrous side-effects. Because of this, my first advice would be to avoid the <code>@extend</code> directive altogether. It might sound brutal, but at the end of the day it can save you some headaches and troubles.</p>

<p>That being said, you know the saying:</p>

<blockquote>
  <p>Never say never.<br/>
— Apparently, <a href="https://github.com/HugoGiraudel/sass-guidelines/issues/31#issuecomment-69112419">not Beyonce</a>.</p>
</blockquote>

<p>There are scenarios where extending selectors might be helpful and worthwhile. Yet, always keep in mind those rules so you don’t get yourself into trouble:</p>

<ul>
  <li>Use extend from within a module, not across different modules.</li>
  <li>Use extend on placeholders exclusively, not on actual selectors.</li>
  <li>Make sure the placeholder you extend is present as little as possible in the stylesheet.</li>
</ul>

<p>If you are going to use extend, let me also remind you that it does not play well with <code>@media</code> blocks. As you may know, Sass is unable to extend an outer selector from within a media query. When doing so, the compiler simply crashes, telling you that you cannot do such a thing. Not great. Especially since media queries are almost all we do know.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">foo'</span><span class="p">;</span>
<span class="p">}</span>

<span class="k">@media</span> <span class="nt">print</span> <span class="p">{</span>
  <span class="nc">.bar</span> <span class="p">{</span>
    <span class="c1">// This doesn't work. Worse: it crashes.</span>
    <span class="k">@extend</span> <span class="nc">.foo</span><span class="o">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">foo'</span>

<span class="k">@media</span> <span class="nt">print</span>
  <span class="nc">.bar</span>
    <span class="c1">// This doesn't work. Worse: it crashes.</span>
    <span class="k">@extend</span> <span class="nc">.foo</span></code></pre></div>

  </div>
</div>

<blockquote>
  <p>You may not @extend an outer selector from within @media.<br/>
You may only @extend selectors within the same directive.</p>
</blockquote>

<div class="note">
  <p>It is often said that <code>@extend</code> helps with the file size since it combines selectors rather than duplicated properties. That is true, however the difference is negligible once <a href="http://en.wikipedia.org/wiki/Gzip">Gzip</a> has done its compression.</p>
  <p>That being said, if you cannot use Gzip (or any equivalent) then switching to a <code>@extend</code> approach might not be that bad as long as you know what you are doing.</p>
</div>

<p>To sum up, I would <strong>advise against using the <code>@extend</code> directive</strong>, unless under some specific circumstances, but I would not go as far as to forbid it.</p>

<h6 id="further-reading-23">Further reading</h6>

<h1 id="mixins">Mixins</h1>

<p>Mixins are one of the most used features from the whole Sass language. They are the key to reusability and DRY components. And for good reason: mixins allow authors to define styles that can be reused throughout the stylesheet without needing to resort to non-semantic classes such as <code>.float-left</code>.</p>

<p>They can contain full CSS rules and pretty much everything that is allowed anywhere in a Sass document. They can even take arguments, just like functions. Needless to say, the possibilities are endless.</p>

<p>But I feel I must warn you against abusing the power of mixins. Again, the keyword here is <em>simplicity</em>. It might be tempting to build extremely powerful mixins with massive amounts of logic. It’s called over-engineering and most developers suffer from it. Don’t over think your code, and above all keep it simple. If a mixin ends up being longer than 20 lines or so, then it should be either split into smaller chunks or completely revised.</p>

<h2 id="basics">Basics</h2>

<p>That being said, mixins are extremely useful and you should be using some. The rule of thumb is that if you happen to spot a group of CSS properties that always appear together for a reason (i.e. not a coincidence), you can put them in a mixin instead. The <a href="http://nicolasgallagher.com/micro-clearfix-hack/">micro-clearfix hack from Nicolas Gallagher</a> deserves to be put in a (argumentless) mixin for instance.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Helper to clear inner floats</span>
<span class="c1">/// @author Nicolas Gallagher</span>
<span class="c1">/// @link http://nicolasgallagher.com/micro-clearfix-hack/ Micro Clearfix</span>
<span class="k">@mixin</span><span class="nf"> clearfix</span> <span class="p">{</span>
  <span class="na">&amp;</span><span class="o">::</span><span class="n">after</span> <span class="p">{</span>
    <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">'</span><span class="p">;</span>
    <span class="na">display</span><span class="o">:</span> <span class="n">table</span><span class="p">;</span>
    <span class="na">clear</span><span class="o">:</span> <span class="no">both</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Helper to clear inner floats</span>
<span class="c1">/// @author Nicolas Gallagher</span>
<span class="c1">/// @link http://nicolasgallagher.com/micro-clearfix-hack/ Micro Clearfix</span>
<span class="k">@mixin</span><span class="nf"> clearfix</span>
  <span class="na">&amp;</span><span class="o">::</span><span class="n">after</span>
    <span class="na">content</span><span class="o">:</span> <span class="s1">'</span><span class="s2">'</span>
    <span class="na">display</span><span class="o">:</span> <span class="n">table</span>
    <span class="na">clear</span><span class="o">:</span> <span class="no">both</span></code></pre></div>

  </div>
</div>

<p>Another valid example would be a mixin to size an element, defining both <code>width</code> and <code>height</code> at the same time. Not only would it make the code lighter to type, but also easier to read.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Helper to size an element</span>
<span class="c1">/// @author Hugo Giraudel</span>
<span class="c1">/// @param {Length} $width</span>
<span class="c1">/// @param {Length} $height</span>
<span class="k">@mixin</span><span class="nf"> size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span> <span class="p">{</span>
  <span class="na">width</span><span class="o">:</span> <span class="nv">$width</span><span class="p">;</span>
  <span class="na">height</span><span class="o">:</span> <span class="nv">$height</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Helper to size an element</span>
<span class="c1">/// @author Hugo Giraudel</span>
<span class="c1">/// @param {Length} $width</span>
<span class="c1">/// @param {Length} $height</span>
<span class="nf">=size</span><span class="p">(</span><span class="nv">$width</span><span class="o">,</span> <span class="nv">$height</span><span class="o">:</span> <span class="nv">$width</span><span class="p">)</span>
  <span class="na">width</span><span class="o">:</span> <span class="nv">$width</span>
  <span class="na">height</span><span class="o">:</span> <span class="nv">$height</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-24">Further reading</h6>

<h2 id="arguments-list">Arguments list</h2>

<p>When dealing with an unknown number of arguments in a mixin, always use an <code>arglist</code> rather than a list. Think of <code>arglist</code> as the 8th hidden undocumented data type from Sass that is implicitly used when passing an arbitrary number of arguments to a mixin or a function whose signature contains <code>...</code>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@mixin</span><span class="nf"> shadows</span><span class="p">(</span><span class="nv">$shadows</span><span class="o">...</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// type-of($shadows) == 'arglist'</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nf">=shadows</span><span class="p">(</span><span class="nv">$shadows</span><span class="o">...</span><span class="p">)</span>
  <span class="c1">// type-of($shadows) == 'arglist'</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<p>Now, when building a mixin that accepts a handful of arguments (understand 3 or more), think twice before merging them out as a list or a map thinking it will be easier than passing them all one by one.</p>

<p>Sass is actually pretty clever with mixins and function declarations, so much so that you can actually pass a list or a map as an arglist to a function/mixin so that it gets parsed as a series of arguments.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@mixin</span><span class="nf"> dummy</span><span class="p">(</span><span class="nv">$a</span><span class="o">,</span> <span class="nv">$b</span><span class="o">,</span> <span class="nv">$c</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>

<span class="c1">// Yep</span>
<span class="k">@include</span><span class="nd"> dummy</span><span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">);</span>

<span class="c1">// Yep but nope</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">);</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nf">dummy</span><span class="p">(</span><span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">1</span><span class="p">)</span><span class="o">,</span> <span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">2</span><span class="p">)</span><span class="o">,</span> <span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">3</span><span class="p">));</span>

<span class="c1">// Yep</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">);</span>
<span class="k">@include</span><span class="nd"> dummy</span><span class="p">(</span><span class="nv">$params</span><span class="o">...</span><span class="p">);</span>

<span class="c1">// Yep</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">c'</span><span class="o">:</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">a'</span><span class="o">:</span> <span class="n-Pseudo">true</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">b'</span><span class="o">:</span> <span class="mi">42</span><span class="o">,</span>
<span class="p">);</span>
<span class="k">@include</span><span class="nd"> dummy</span><span class="p">(</span><span class="nv">$params</span><span class="o">...</span><span class="p">);</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nf">=dummy</span><span class="p">(</span><span class="nv">$a</span><span class="o">,</span> <span class="nv">$b</span><span class="o">,</span> <span class="nv">$c</span><span class="p">)</span>
  <span class="c1">// ...</span>

<span class="c1">// Yep</span>
<span class="nd">+dummy</span><span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">)</span>

<span class="c1">// Yep but nope</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">)</span>
<span class="nv">$value</span><span class="o">:</span> <span class="nf">dummy</span><span class="p">(</span><span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">1</span><span class="p">)</span><span class="o">,</span> <span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">2</span><span class="p">)</span><span class="o">,</span> <span class="nf">nth</span><span class="p">(</span><span class="nv">$params</span><span class="o">,</span> <span class="mi">3</span><span class="p">))</span>

<span class="c1">// Yep</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span><span class="n-Pseudo">true</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="p">)</span>
<span class="nd">+dummy</span><span class="p">(</span><span class="nv">$params</span><span class="o">...</span><span class="p">)</span>

<span class="c1">// Yep</span>
<span class="nv">$params</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">c'</span><span class="o">:</span> <span class="s1">'</span><span class="s2">kittens'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">a'</span><span class="o">:</span> <span class="n-Pseudo">true</span><span class="o">,</span> <span class="s1">'</span><span class="s2">b'</span><span class="o">:</span> <span class="mi">42</span><span class="o">,</span><span class="p">)</span>
<span class="nd">+dummy</span><span class="p">(</span><span class="nv">$params</span><span class="o">...</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<h6 id="further-reading-25">Further reading</h6>

<h2 id="mixins-and-vendor-prefixes">Mixins and vendor prefixes</h2>

<p>It might be tempting to define custom mixins to handle vendor prefixes for unsupported or partially supported CSS properties. But we do not want to do this. First, if you can use <a href="https://github.com/postcss/autoprefixer">Autoprefixer</a>, use Autoprefixer. It will remove Sass code from your project, will always be up-to-date and will necessarily do a much better job than you at prefixing stuff.</p>

<p>Unfortunately, Autoprefixer is not always an option. If you use either <a href="http://bourbon.io/">Bourbon</a> or <a href="http://compass-style.org/">Compass</a>, you may already know that they both provide a collection of mixins that handle vendor prefixes for you. Use those.</p>

<p>If you cannot use Autoprefixer and use neither Bourbon nor Compass, then and only then, you can have your own mixin for prefixing CSS properties. But. Please do not build a mixin per property, manually printing each vendor.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Nope</span>
<span class="k">@mixin</span><span class="nf"> transform</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span> <span class="p">{</span>
  <span class="na">-webkit-transform</span><span class="o">:</span> <span class="nv">$value</span><span class="p">;</span>
  <span class="na">-moz-transform</span><span class="o">:</span> <span class="nv">$value</span><span class="p">;</span>
  <span class="na">transform</span><span class="o">:</span> <span class="nv">$value</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Nope</span>
<span class="nf">=transform</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span>
  <span class="na">-webkit-transform</span><span class="o">:</span> <span class="nv">$value</span>
  <span class="na">-moz-transform</span><span class="o">:</span> <span class="nv">$value</span>
  <span class="na">transform</span><span class="o">:</span> <span class="nv">$value</span></code></pre></div>

  </div>
</div>

<p>Do it the clever way.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Mixin helper to output vendor prefixes</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @author HugoGiraudel</span>
<span class="c1">/// @param {String} $property - Unprefixed CSS property</span>
<span class="c1">/// @param {*} $value - Raw CSS value</span>
<span class="c1">/// @param {List} $prefixes - List of prefixes to output</span>
<span class="k">@mixin</span><span class="nf"> prefix</span><span class="p">(</span><span class="nv">$property</span><span class="o">,</span> <span class="nv">$value</span><span class="o">,</span> <span class="nv">$prefixes</span><span class="o">:</span> <span class="p">())</span> <span class="p">{</span>
  <span class="k">@each</span> <span class="err">$</span><span class="nt">prefix</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">prefixes</span> <span class="p">{</span>
    <span class="nt">-</span><span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">prefix</span><span class="p">}</span><span class="nt">-</span><span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">property</span><span class="p">}</span><span class="nd">:</span> <span class="err">$</span><span class="nt">value</span><span class="o">;</span>
  <span class="p">}</span>

  <span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">property</span><span class="p">}</span><span class="nd">:</span> <span class="err">$</span><span class="nt">value</span><span class="o">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Mixin helper to output vendor prefixes</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @author HugoGiraudel</span>
<span class="c1">/// @param {String} $property - Unprefixed CSS property</span>
<span class="c1">/// @param {*} $value - Raw CSS value</span>
<span class="c1">/// @param {List} $prefixes - List of prefixes to output</span>
<span class="nf">=prefix</span><span class="p">(</span><span class="nv">$property</span><span class="o">,</span> <span class="nv">$value</span><span class="o">,</span> <span class="nv">$prefixes</span><span class="o">:</span> <span class="p">())</span>
  <span class="k">@each</span> <span class="err">$</span><span class="nt">prefix</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">prefixes</span>
    <span class="na">-#{$prefix}-#{$property}</span><span class="o">:</span> <span class="nv">$value</span>

  <span class="na">#{$property}</span><span class="o">:</span> <span class="nv">$value</span></code></pre></div>

  </div>
</div>

<p>Then using this mixin should be very straightforward:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="nc">.foo</span> <span class="p">{</span>
  <span class="k">@include</span><span class="nd"> prefix</span><span class="p">(</span><span class="n">transform</span><span class="o">,</span> <span class="nf">rotate</span><span class="p">(</span><span class="mi">90</span><span class="kt">deg</span><span class="p">)</span><span class="o">,</span> <span class="p">(</span><span class="s1">'</span><span class="s2">webkit'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">ms'</span><span class="p">));</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="nc">.foo</span>
  <span class="nd">+prefix</span><span class="p">(</span><span class="n">transform</span><span class="o">,</span> <span class="nf">rotate</span><span class="p">(</span><span class="mi">90</span><span class="kt">deg</span><span class="p">)</span><span class="o">,</span> <span class="p">(</span><span class="s1">'</span><span class="s2">webkit'</span><span class="o">,</span> <span class="s1">'</span><span class="s2">ms'</span><span class="p">))</span></code></pre></div>

  </div>
</div>

<p>Please keep in mind this is a poor solution. For instance, it cannot deal with complex polyfills such as those required for Flexbox. In that sense, using Autoprefixer would be a far better option.</p>

<h6 id="further-reading-26">Further reading</h6>

<h1 id="conditional-statements">Conditional statements</h1>

<p>You probably already know that Sass provides conditional statements via the <code>@if</code> and <code>@else</code> directives. Unless you have some medium to complex logic in your code, there is no need for conditional statements in your everyday stylesheets. Actually, they mainly exist for libraries and frameworks.</p>

<p>Anyway, if you ever find yourself in need of them, please respect the following guidelines:</p>

<ul>
  <li>No parentheses unless they are necessary;</li>
  <li>Always an empty new line before <code>@if</code>;</li>
  <li>Always a line break after the opening brace (<code>{</code>);</li>
  <li><code>@else</code> statements on the same line as previous closing brace (<code>}</code>).</li>
  <li>Always an empty new line after the last closing brace (<code>}</code>) unless the next line is a closing brace (<code>}</code>).</li>
</ul>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="nv">$support-legacy</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span> <span class="k">@else</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="p">(</span><span class="nv">$support-legacy</span> <span class="o">==</span> <span class="n-Pseudo">true</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>
<span class="k">@else</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="nv">$support-legacy</span>
  <span class="c1">// ...</span>
<span class="k">@else</span>
  <span class="c1">// ...</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="p">(</span><span class="nv">$support-legacy</span> <span class="o">==</span> <span class="n-Pseudo">true</span><span class="p">)</span>
  <span class="c1">// ...</span>
<span class="k">@else</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<p>When testing for a falsy value, always use the <code>not</code> keyword rather than testing against <code>false</code> or <code>null</code>.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="ow">not</span> <span class="nf">index</span><span class="p">(</span><span class="nv">$list</span><span class="o">,</span> <span class="nv">$item</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="nf">index</span><span class="p">(</span><span class="nv">$list</span><span class="o">,</span> <span class="nv">$item</span><span class="p">)</span> <span class="o">==</span> <span class="n">null</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="ow">not</span> <span class="nf">index</span><span class="p">(</span><span class="nv">$list</span><span class="o">,</span> <span class="nv">$item</span><span class="p">)</span>
  <span class="c1">// ...</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="nf">index</span><span class="p">(</span><span class="nv">$list</span><span class="o">,</span> <span class="nv">$item</span><span class="p">)</span> <span class="o">==</span> <span class="n">null</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<p>Always put the variable part on the left side of the statement, and the (un)expected result on the right. Reversed conditional statements often are more difficult to read, especially to unexperienced developers.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="nv">$value</span> <span class="o">==</span> <span class="mi">42</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="mi">42</span> <span class="o">==</span> <span class="nv">$value</span> <span class="p">{</span>
  <span class="c1">// ...</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="k">@if</span> <span class="nv">$value</span> <span class="o">==</span> <span class="mi">42</span>
  <span class="c1">// ...</span>

<span class="c1">// Nope</span>
<span class="k">@if</span> <span class="mi">42</span> <span class="o">==</span> <span class="nv">$value</span>
  <span class="c1">// ...</span></code></pre></div>

  </div>
</div>

<p>When using conditional statements within a function to return a different result based on some condition, always make sure the function still has a <code>@return</code> statement outside of any conditional block.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">// Yep</span>
<span class="k">@function</span> <span class="nt">dummy</span><span class="o">(</span><span class="err">$</span><span class="nt">condition</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@if</span> <span class="nv">$condition</span> <span class="p">{</span>
    <span class="k">@return</span> <span class="nt">true</span><span class="o">;</span>
  <span class="p">}</span>

  <span class="k">@return</span> <span class="nt">false</span><span class="o">;</span>
<span class="p">}</span>

<span class="c1">// Nope</span>
<span class="k">@function</span> <span class="nt">dummy</span><span class="o">(</span><span class="err">$</span><span class="nt">condition</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@if</span> <span class="nv">$condition</span> <span class="p">{</span>
    <span class="k">@return</span> <span class="nt">true</span><span class="o">;</span>
  <span class="p">}</span> <span class="k">@else</span> <span class="p">{</span>
    <span class="k">@return</span> <span class="nt">false</span><span class="o">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">// Yep</span>
<span class="k">@function</span> <span class="nt">dummy</span><span class="o">(</span><span class="err">$</span><span class="nt">condition</span><span class="o">)</span>
  <span class="k">@if</span> <span class="nv">$condition</span>
    <span class="k">@return</span> <span class="nt">true</span>

  <span class="k">@return</span> <span class="nt">false</span><span class="o">;</span>

<span class="c1">// Nope</span>
<span class="k">@function</span> <span class="nt">dummy</span><span class="o">(</span><span class="err">$</span><span class="nt">condition</span><span class="o">)</span>
  <span class="k">@if</span> <span class="nv">$condition</span>
    <span class="k">@return</span> <span class="nt">true</span>
  <span class="k">@else</span>
    <span class="k">@return</span> <span class="nt">false</span></code></pre></div>

  </div>
</div>

<h1 id="loops">Loops</h1>

<p>Because Sass provides complex data structures such as <a href="#lists">lists</a> and <a href="#maps">maps</a>, it is no surprise that it also gives a way for authors to iterate over those entities.</p>

<p>However, the presence of loops usually implies moderately complex logic that probably does not belong to Sass. Before using a loop, make sure it makes sense and that it actually solves an issue.</p>

<h2 id="each">Each</h2>

<p>The <code>@each</code> loop is definitely the most-used out of the three loops provided by Sass. It provides a clean API to iterate over a list or a map.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@each</span> <span class="err">$</span><span class="nt">theme</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">themes</span> <span class="p">{</span>
  <span class="nc">.section-</span><span class="si">#{</span><span class="nv">$theme</span><span class="si">}</span> <span class="p">{</span>
    <span class="na">background-color</span><span class="o">:</span> <span class="nf">map-get</span><span class="p">(</span><span class="nv">$colors</span><span class="o">,</span> <span class="nv">$theme</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@each</span> <span class="err">$</span><span class="nt">theme</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">themes</span>
  <span class="nc">.section-</span><span class="si">#{</span><span class="nv">$theme</span><span class="si">}</span>
    <span class="na">background-color</span><span class="o">:</span> <span class="nf">map-get</span><span class="p">(</span><span class="nv">$colors</span><span class="o">,</span> <span class="nv">$theme</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>When iterating on a map, always use <code>$key</code> and <code>$value</code> as variable names to enforce consistency.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span> <span class="p">{</span>
  <span class="nc">.section-</span><span class="si">#{</span><span class="nv">$key</span><span class="si">}</span> <span class="p">{</span>
    <span class="na">background-color</span><span class="o">:</span> <span class="nv">$value</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@each</span> <span class="err">$</span><span class="nt">key</span><span class="o">,</span> <span class="err">$</span><span class="nt">value</span> <span class="nt">in</span> <span class="err">$</span><span class="nt">map</span>
  <span class="nc">.section-</span><span class="si">#{</span><span class="nv">$key</span><span class="si">}</span>
    <span class="na">background-color</span><span class="o">:</span> <span class="nv">$value</span></code></pre></div>

  </div>
</div>

<p>Also be sure to respect those guidelines to preserve readability:</p>

<ul>
  <li>Always an empty new line before <code>@each</code>;</li>
  <li>Always an empty new line after the closing brace (<code>}</code>) unless the next line is a closing brace (<code>}</code>).</li>
</ul>

<h2 id="for">For</h2>

<p>The <code>@for</code> loop might be useful when combined with CSS’ <code>:nth-*</code> pseudo-classes. Except for these scenarios, prefer an <code>@each</code> loop if you <em>have to</em> iterate over something.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@for</span> <span class="nv">$i</span> <span class="ow">from</span> <span class="mi">1</span> <span class="ow">through</span> <span class="mi">10</span> <span class="p">{</span>
  <span class="nc">.foo</span><span class="nd">:nth-of-type</span><span class="o">(</span><span class="nn">#</span><span class="p">{</span><span class="err">$</span><span class="nt">i</span><span class="p">}</span><span class="o">)</span> <span class="p">{</span>
    <span class="na">border-color</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span><span class="nv">$i</span> <span class="o">*</span> <span class="mi">36</span><span class="o">,</span> <span class="mi">50</span><span class="kt">%</span><span class="o">,</span> <span class="mi">50</span><span class="kt">%</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@for</span> <span class="nv">$i</span> <span class="ow">from</span> <span class="mi">1</span> <span class="ow">through</span> <span class="mi">10</span>
  <span class="nc">.foo</span><span class="nd">:nth-of-type</span><span class="o">(</span><span class="nn">#</span><span class="err">{$</span><span class="nt">i</span><span class="err">}</span><span class="o">)</span>
    <span class="na">border-color</span><span class="o">:</span> <span class="nf">hsl</span><span class="p">(</span><span class="nv">$i</span> <span class="o">*</span> <span class="mi">36</span><span class="o">,</span> <span class="mi">50</span><span class="kt">%</span><span class="o">,</span> <span class="mi">50</span><span class="kt">%</span><span class="p">)</span></code></pre></div>

  </div>
</div>

<p>Always use <code>$i</code> as a variable name to stick to the usual convention and unless you have a really good reason to, never use the <code>to</code> keyword: always use <code>through</code>. Many developers do not even know Sass offers this variation; using it might lead to confusion.</p>

<p>Also be sure to respect those guidelines to preserve readability:</p>

<ul>
  <li>Always an empty new line before <code>@for</code>;</li>
  <li>Always an empty new line after the closing brace (<code>}</code>) unless the next line is a closing brace (<code>}</code>).</li>
</ul>

<h2 id="while">While</h2>

<p>The <code>@while</code> loop has absolutely no use case in a real Sass project, especially since there is no way to break a loop from the inside. <strong>Do not use it</strong>.</p>

<h1 id="warnings-and-errors">Warnings and Errors</h1>

<p>If there is a feature that is often overlooked by Sass developers, it is the ability to dynamically output warnings and errors. Indeed, Sass comes with three custom directives to print content in the standard output system (CLI, compiling app…):</p>

<p>Let’s put <code>@debug</code> aside since it is clearly intended to debug SassScript, which is not our point here. We are then left with <code>@warn</code> and <code>@error</code> which are noticeably identical except that one stops the compiler while the other does not. I’ll let you guess which does what.</p>

<p>Now, there is a lot of room in a Sass project for warnings and errors. Basically any mixin or function expecting a specific type or argument could throw an error if something went wrong, or display a warning when doing an assumption.</p>

<h6 id="further-reading-27">Further reading</h6>

<h2 id="warnings">Warnings</h2>

<p>Take this function from <a href="https://github.com/sass-mq/sass-mq">Sass-MQ</a> attempting to convert a <code>px</code> value to <code>em</code>, for instance:</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="k">@function</span> <span class="nt">mq-px2em</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span><span class="o">,</span> <span class="err">$</span><span class="nt">base-font-size</span><span class="nd">:</span> <span class="err">$</span><span class="nt">mq-base-font-size</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@if</span> <span class="nf">unitless</span><span class="p">(</span><span class="nv">$px</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">@warn</span> <span class="s1">'</span><span class="s2">Assuming </span><span class="si">#{</span><span class="nv">$px</span><span class="si">}</span><span class="s2"> to be in pixels, attempting to convert it into pixels.'</span><span class="p">;</span>
    <span class="k">@return</span> <span class="nt">mq-px2em</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span> <span class="o">+</span> <span class="nt">0px</span><span class="o">);</span>
  <span class="p">}</span> <span class="k">@else</span> <span class="nt">if</span> <span class="nt">unit</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span><span class="o">)</span> <span class="o">==</span> <span class="nt">em</span> <span class="p">{</span>
    <span class="k">@return</span> <span class="err">$</span><span class="nt">px</span><span class="o">;</span>
  <span class="p">}</span>

  <span class="k">@return</span> <span class="o">(</span><span class="err">$</span><span class="nt">px</span> <span class="o">/</span> <span class="err">$</span><span class="nt">base-font-size</span><span class="o">)</span> <span class="o">*</span> <span class="nt">1em</span><span class="o">;</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="k">@function</span> <span class="nt">mq-px2em</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span><span class="o">,</span> <span class="err">$</span><span class="nt">base-font-size</span><span class="nd">:</span> <span class="err">$</span><span class="nt">mq-base-font-size</span><span class="o">)</span>
  <span class="k">@if</span> <span class="nf">unitless</span><span class="p">(</span><span class="nv">$px</span><span class="p">)</span>
    <span class="k">@warn</span> <span class="s1">'</span><span class="s2">Assuming </span><span class="si">#{</span><span class="nv">$px</span><span class="si">}</span><span class="s2"> to be in pixels, attempting to convert it into pixels.'</span>
    <span class="k">@return</span> <span class="nt">mq-px2em</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span> <span class="o">+</span> <span class="nt">0px</span><span class="o">)</span>
  <span class="k">@else</span> <span class="nt">if</span> <span class="nt">unit</span><span class="o">(</span><span class="err">$</span><span class="nt">px</span><span class="o">)</span> <span class="o">==</span> <span class="nt">em</span>
    <span class="k">@return</span> <span class="err">$</span><span class="nt">px</span>

  <span class="k">@return</span> <span class="o">(</span><span class="err">$</span><span class="nt">px</span> <span class="o">/</span> <span class="err">$</span><span class="nt">base-font-size</span><span class="o">)</span> <span class="o">*</span> <span class="nt">1em</span></code></pre></div>

  </div>
</div>

<p>If the value happens to be unitless, the function assumes the value is meant to be expressed in pixels. At this point, an assumption may be risky so the user should be warned that the software did something that could be considered unexpected.</p>

<h2 id="errors">Errors</h2>

<p>Errors, unlike warnings, prevent the compiler from going any further. Basically, they stop the compilation and display a message in the output stream as well as the stack trace, which is handy for debugging. Because of this, errors should be thrown when there is no way for the program to keep running. When possible, try to work around the issue and display a warning instead.</p>

<p>As an example, let’s say you build a getter function to access values from a specific map. You could throw an error if the requested key does not exist in the map.</p>

<div class="code-block">
  <div class="code-block__wrapper" data-syntax="scss">

<div class="highlight"><pre><code class="language-scss" data-lang="scss"><span class="c1">/// Z-indexes map, gathering all Z layers of the application</span>
<span class="c1">/// @access private</span>
<span class="c1">/// @type Map</span>
<span class="c1">/// @prop {String} key - Layer’s name</span>
<span class="c1">/// @prop {Number} value - Z value mapped to the key</span>
<span class="nv">$z-indexes</span><span class="o">:</span> <span class="p">(</span>
  <span class="s1">'</span><span class="s2">modal'</span><span class="o">:</span> <span class="mi">5000</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">dropdown'</span><span class="o">:</span> <span class="mi">4000</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">default'</span><span class="o">:</span> <span class="mi">1</span><span class="o">,</span>
  <span class="s1">'</span><span class="s2">below'</span><span class="o">:</span> <span class="mi">-1</span><span class="o">,</span>
<span class="p">);</span>

<span class="c1">/// Get a z-index value from a layer name</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $layer - Layer's name</span>
<span class="c1">/// @return {Number}</span>
<span class="c1">/// @require $z-indexes</span>
<span class="k">@function</span> <span class="nt">z</span><span class="o">(</span><span class="err">$</span><span class="nt">layer</span><span class="o">)</span> <span class="p">{</span>
  <span class="k">@if</span> <span class="ow">not</span> <span class="nf">map-has-key</span><span class="p">(</span><span class="nv">$z-indexes</span><span class="o">,</span> <span class="nv">$layer</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">@error</span> <span class="s1">'</span><span class="s2">There is no layer named `</span><span class="si">#{</span><span class="nv">$layer</span><span class="si">}</span><span class="s2">` in $z-indexes. '</span>
         <span class="o">+</span> <span class="s1">'</span><span class="s2">Layer should be one of </span><span class="si">#{</span><span class="nf">map-keys</span><span class="p">(</span><span class="nv">$z-indexes</span><span class="p">)</span><span class="si">}</span><span class="s2">.'</span><span class="o">;</span>
  <span class="p">}</span>

  <span class="k">@return</span> <span class="nt">map-get</span><span class="o">(</span><span class="err">$</span><span class="nt">z-indexes</span><span class="o">,</span> <span class="err">$</span><span class="nt">layer</span><span class="o">);</span>
<span class="p">}</span></code></pre></div>

  </div>
  <div class="code-block__wrapper" data-syntax="sass">

<div class="highlight"><pre><code class="language-sass" data-lang="sass"><span class="c1">/// Z-indexes map, gathering all Z layers of the application</span>
<span class="c1">/// @access private</span>
<span class="c1">/// @type Map</span>
<span class="c1">/// @prop {String} key - Layer's name</span>
<span class="c1">/// @prop {Number} value - Z value mapped to the key</span>
<span class="na">$z-indexes</span><span class="o">:</span> <span class="p">(</span><span class="s1">'</span><span class="s2">modal'</span><span class="o">:</span> <span class="mi">5000</span><span class="o">,</span> <span class="s1">'</span><span class="s2">dropdown'</span><span class="o">:</span> <span class="mi">4000</span><span class="o">,</span> <span class="s1">'</span><span class="s2">default'</span><span class="o">:</span> <span class="mi">1</span><span class="o">,</span> <span class="s1">'</span><span class="s2">below'</span><span class="o">:</span> <span class="mi">-1</span><span class="o">,</span><span class="p">)</span>

<span class="c1">/// Get a z-index value from a layer name</span>
<span class="c1">/// @access public</span>
<span class="c1">/// @param {String} $layer - Layer's name</span>
<span class="c1">/// @return {Number}</span>
<span class="c1">/// @require $z-indexes</span>
<span class="k">@function</span> <span class="nt">z</span><span class="o">(</span><span class="err">$</span><span class="nt">layer</span><span class="o">)</span>
  <span class="k">@if</span> <span class="ow">not</span> <span class="nf">map-has-key</span><span class="p">(</span><span class="nv">$z-indexes</span><span class="o">,</span> <span class="nv">$layer</span><span class="p">)</span>
    <span class="k">@error</span> <span class="s1">'</span><span class="s2">There is no layer named `</span><span class="si">#{</span><span class="nv">$layer</span><span class="si">}</span><span class="s2">` in $z-indexes. '</span>
         <span class="o">+</span> <span class="s1">'</span><span class="s2">Layer should be one of </span><span class="si">#{</span><span class="nf">map-keys</span><span class="p">(</span><span class="nv">$z-indexes</span><span class="p">)</span><span class="si">}</span><span class="s2">.'</span>

  <span class="k">@return</span> <span class="nt">map-get</span><span class="o">(</span><span class="err">$</span><span class="nt">z-indexes</span><span class="o">,</span> <span class="err">$</span><span class="nt">layer</span><span class="o">)</span></code></pre></div>

  </div>
</div>

<p>What’s nice about a CSS preprocessor as popular as Sass is that it comes with a whole ecosystem of frameworks, plugins, libraries and tools. After 8 years of existence, we are getting closer and closer to the point where <a href="http://hugogiraudel.com/2014/10/27/rethinking-atwoods-law/">everything that can be written in Sass has been written in Sass</a>.</p>

<p>However my advice would to be to lower the number of dependencies to the strict minimum. Managing dependencies is some sort of hell you don’t want to be part of. Plus, there is little to no need for external dependencies when it comes to Sass.</p>

<h2 id="compass">Compass</h2>

<p><a href="http://compass-style.org/">Compass</a> is the main Sass framework out there. Developed by <a href="https://twitter.com/chriseppstein">Chris Eppstein</a>, one of the two core designers of Sass, I don’t see it dramatically losing in popularity for a while, if you want my opinion.</p>

<p>Still, I do not use Compass anymore, the main reason is that it slows Sass down a lot. Ruby Sass is quite slow in itself, so adding more Ruby and more Sass on top of it doesn’t really help.</p>

<p>The thing is, we use very little from the whole framework. Compass is huge. Cross-browser compatibility mixins is just the tip of the iceberg. Math functions, image helpers, spriting… There is so much that can be done with this great piece of software.</p>

<p>Unfortunately, this is all sugar and there is no killer feature in there. An exception could be made of the sprite builder which is <em>really great</em>, but <a href="https://github.com/filamentgroup/grunticon">Grunticon</a> and <a href="http://grumpicon.com/">Grumpicon</a> do the job as well, and have the benefit of being pluggable in the build process.</p>

<p>Anyway, I do not forbid the use of Compass although I would not recommend it either, especially since it is not LibSass-compatible (even if efforts have been made in that direction). If you feel better using it, fair enough, but I don’t think you’ll get much from it at the end of the day.</p>

<div class="note">
  <p>Ruby Sass is currently going under some outstanding optimizations that are specifically targeted at logic-heavy styles with many functions and mixins. They should dramatically improve performance to the point where Compass and other frameworks might not be slowing Sass anymore.</p>
</div>

<h6 id="further-reading-28">Further reading</h6>

<h2 id="grid-systems">Grid systems</h2>

<p>Not using a grid system is not an option now that Responsive Web Design is all over the place. To make designs look consistent and solid across all sizes, we use some sort of grid to lay out the elements. To avoid having to code this grid work over and over again, some brilliant minds made theirs reusable.</p>

<p>Let me put this straight: I am not a big fan of grid systems. Of course I do see the potential, but I think most of them are completely overkill and are mostly used to draw red columns on a white background in nerdy designers’ speaker decks. When is the last time you thought <em>thank-God-I-have-this-tool-to-build-this-2-5-3.1-π-grid</em>? That’s right, never. Because in most cases, you just want the usual regular 12-columns grid, nothing fancy.</p>

<p>If you are using a CSS framework for your project like <a href="http://getbootstrap.com/">Bootstrap</a> or <a href="http://foundation.zurb.com/">Foundation</a>, chances are high it includes a grid system already in which case I would recommend to use it to avoid having to deal with yet another dependency.</p>

<p>If you are not tied to a specific grid system, you will be pleased to know there are two top-notch Sass powered grid engines out there: <a href="http://susy.oddbird.net/">Susy</a> and <a href="http://singularity.gs/">Singularity</a>. Both do much more than you will ever need so you can pick the one you prefer between these two and be sure all your edge cases—even the most nifty ones—will be covered. If you ask me, Susy has a slightly better community, but that’s my opinion.</p>

<p>Or you can head over to something a bit more casual, like <a href="https://github.com/csswizardry/csswizardry-grids">csswizardry-grids</a>. All in all, the choice will not have much of an impact on your coding style, so this is pretty much up to you at this point.</p>

<h6 id="further-reading-29">Further reading</h6>

<h2 id="scss-lint">SCSS-lint</h2>

<p>Linting code is very important. Usually, following guidelines from a styleguide helps reducing the amount of code quality mistakes but nobody’s perfect and there are always things to improve. So you could say that linting code is as important as commenting it.</p>

<p><a href="https://github.com/causes/scss-lint">SCSS-lint</a> is a tool to help you keep your SCSS files clean and readable. It is fully customisable and easy to integrate with your own tools.</p>

<p>Fortunately, SCSS-lint recommendations are very similar to those described in this document. In order to configure SCSS-lint according to Sass Guidelines, may I recommend the following setup:</p>

<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="c1"># For SCSS-Lint v0.32.0</span>

<span class="l-Scalar-Plain">linters</span><span class="p-Indicator">:</span>

  <span class="l-Scalar-Plain">BangFormat</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">space_before_bang</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">space_after_bang</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">BorderZero</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">ColorKeyword</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">Comment</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">DebugStatement</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">DeclarationOrder</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">DuplicateProperty</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">ElsePlacement</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">same_line</span>

  <span class="l-Scalar-Plain">EmptyLineBetweenBlocks</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">ignore_single_line_blocks</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">EmptyRule</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">FinalNewline</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">present</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">HexLength</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">short</span>

  <span class="l-Scalar-Plain">HexNotation</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">lowercase</span>

  <span class="l-Scalar-Plain">HexValidation</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">IdSelector</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">ImportPath</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">leading_underscore</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
    <span class="l-Scalar-Plain">filename_extension</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">Indentation</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">character</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">space</span>
    <span class="l-Scalar-Plain">width</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">2</span>

  <span class="l-Scalar-Plain">LeadingZero</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">include_zero</span>

  <span class="l-Scalar-Plain">MergeableSelector</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
    <span class="l-Scalar-Plain">force_nesting</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">NameFormat</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">convention</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">hyphenated_lowercase</span>
    <span class="l-Scalar-Plain">allow_leading_underscore</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">NestingDepth</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">max_depth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">3</span>

  <span class="l-Scalar-Plain">PlaceholderInExtend</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">PropertySortOrder</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
    <span class="l-Scalar-Plain">ignore_unspecified</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">PropertySpelling</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">extra_properties</span><span class="p-Indicator">:</span> <span class="p-Indicator">[]</span>

  <span class="l-Scalar-Plain">QualifyingElement</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">allow_element_with_attribute</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
    <span class="l-Scalar-Plain">allow_element_with_class</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
    <span class="l-Scalar-Plain">allow_element_with_id</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">SelectorDepth</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">max_depth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">3</span>

  <span class="l-Scalar-Plain">SelectorFormat</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">convention</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">hyphenated_lowercase</span>
    <span class="l-Scalar-Plain">class_convention</span><span class="p-Indicator">:</span> <span class="s">'^(?:u|is|has)\-[a-z][a-zA-Z0-9]*$|^(?!u|is|has)[a-zA-Z][a-zA-Z0-9]*(?:\-[a-z][a-zA-Z0-9]*)?(?:\-\-[a-z][a-zA-Z0-9]*)?$'</span>

  <span class="l-Scalar-Plain">Shorthand</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">SingleLinePerProperty</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">allow_single_line_rule_sets</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">SingleLinePerSelector</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">SpaceAfterComma</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">SpaceAfterPropertyColon</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">one_space</span>

  <span class="l-Scalar-Plain">SpaceAfterPropertyName</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">SpaceBeforeBrace</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">space</span>
    <span class="l-Scalar-Plain">allow_single_line_padding</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">SpaceBetweenParens</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">spaces</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>

  <span class="l-Scalar-Plain">StringQuotes</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">style</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">single_quotes</span>

  <span class="l-Scalar-Plain">TrailingSemicolon</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">TrailingZero</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">UnnecessaryMantissa</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">UnnecessaryParentReference</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">UrlFormat</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>

  <span class="l-Scalar-Plain">UrlQuotes</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>

  <span class="l-Scalar-Plain">VendorPrefixes</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
    <span class="l-Scalar-Plain">identifier_list</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">base</span>
    <span class="l-Scalar-Plain">include</span><span class="p-Indicator">:</span> <span class="p-Indicator">[]</span>
    <span class="l-Scalar-Plain">exclude</span><span class="p-Indicator">:</span> <span class="p-Indicator">[]</span>

  <span class="l-Scalar-Plain">ZeroUnit</span><span class="p-Indicator">:</span>
    <span class="l-Scalar-Plain">enabled</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span></code></pre></div>

<div class="note">
  <p>If you want to plug SCSS lint into your Grunt build process, you will be pleased to know there is a Grunt plugin for that called <a href="https://github.com/ahmednuaman/grunt-scss-lint">grunt-scss-lint</a>.</p>
  <p>Also, if you are on the hunt for a neat application that works with SCSS-lint and the like, the guys at <a href="http://thoughtbot.com/">Thoughtbot</a> (Bourbon, Neat...) are working on <a href="https://houndci.com/">Hound</a>.</p>
</div>

<h6 id="further-reading-30">Further reading</h6>

<h1 id="too-long-didnt-read">Too Long; Didn’t read</h1>

<p>To sum up, we want:</p>

<ul>
  <li>Two (2) spaces indents, no tabs;</li>
  <li>80-characters wide lines;</li>
  <li>Properly written multi-line CSS;</li>
  <li>Meaningful use of whitespaces;</li>
  <li>Quoted strings (single quotes) &amp; URLs;</li>
  <li>No trailing 0, mandatory leading 0;</li>
  <li>Calculations wrapped in parentheses;</li>
  <li>No magic numbers;</li>
  <li>Colors expressed in keywords &gt; HSL &gt; RGB &gt; hexadecimal;</li>
  <li>Lists separated with commas;</li>
  <li>No trailing comma in lists (since they are inlined);</li>
  <li>Trailing comma in maps;</li>
  <li>No selector nesting except for pseudo-classes and pseudo-elements;</li>
  <li>Hyphen-delimited naming;</li>
  <li>Extensive comments;</li>
  <li>SassDoc-powered API comments;</li>
  <li>Limited usage of <code>@extend</code>;</li>
  <li>Simple mixins;</li>
  <li>As few loops as possible, no <code>@while</code>;</li>
  <li>Reduced number of dependencies;</li>
  <li>Meaningful use of warnings and errors.</li>
</ul>
  </article>
</section>


<nav id="jumpto">
  <p>
    <a href="/david/blog/">Accueil du blog</a> |
    <a href="http://sass-guidelin.es/">Source originale</a> |
    <a href="/david/stream/2019/">Accueil du flux</a>
  </p>
</nav>

<footer>
  <div>
    <img src="/static/david/david-larlet-avatar.jpg" loading="lazy" class="avatar" width="200" height="200">
    <p>
      Bonjour/Hi!
      Je suis <a href="/david/" title="Profil public">David&nbsp;Larlet</a>, je vis actuellement à Montréal et j’alimente cet espace depuis 15 ans. <br>
      Si tu as apprécié cette lecture, n’hésite pas à poursuivre ton exploration. Par exemple via les <a href="/david/blog/" title="Expériences bienveillantes">réflexions bimestrielles</a>, la <a href="/david/stream/2019/" title="Pensées (dés)articulées">veille hebdomadaire</a> ou en t’abonnant au <a href="/david/log/" title="S’abonner aux publications via RSS">flux RSS</a> (<a href="/david/blog/2019/flux-rss/" title="Tiens c’est quoi un flux RSS ?">so 2005</a>).
    </p>
    <p>
      Je m’intéresse à la place que je peux avoir dans ce monde. En tant qu’humain, en tant que membre d’une famille et en tant qu’associé d’une coopérative. De temps en temps, je fais aussi des <a href="https://github.com/davidbgk" title="Principalement sur Github mais aussi ailleurs">trucs techniques</a>. Et encore plus rarement, <a href="/david/talks/" title="En ce moment je laisse plutôt la place aux autres">j’en parle</a>.
    </p>
    
    <p>
      Voici quelques articles choisis :
      <a href="/david/blog/2019/faire-equipe/" title="Accéder à l’article complet">Faire équipe</a>,
      <a href="/david/blog/2018/bivouac-automnal/" title="Accéder à l’article complet">Bivouac automnal</a>,
      <a href="/david/blog/2018/commodite-effondrement/" title="Accéder à l’article complet">Commodité et effondrement</a>,
      <a href="/david/blog/2017/donnees-communs/" title="Accéder à l’article complet">Des données aux communs</a>,
      <a href="/david/blog/2016/accompagner-enfant/" title="Accéder à l’article complet">Accompagner un enfant</a>,
      <a href="/david/blog/2016/senior-developer/" title="Accéder à l’article complet">Senior developer</a>,
      <a href="/david/blog/2016/illusion-sociale/" title="Accéder à l’article complet">L’illusion sociale</a>,
      <a href="/david/blog/2016/instantane-scopyleft/" title="Accéder à l’article complet">Instantané Scopyleft</a>,
      <a href="/david/blog/2016/enseigner-web/" title="Accéder à l’article complet">Enseigner le Web</a>,
      <a href="/david/blog/2016/simplicite-defaut/" title="Accéder à l’article complet">Simplicité par défaut</a>,
      <a href="/david/blog/2016/minimalisme-esthetique/" title="Accéder à l’article complet">Minimalisme et esthétique</a>,
      <a href="/david/blog/2014/un-web-omni-present/" title="Accéder à l’article complet">Un web omni-présent</a>,
      <a href="/david/blog/2014/manifeste-developpeur/" title="Accéder à l’article complet">Manifeste de développeur</a>,
      <a href="/david/blog/2013/confort-convivialite/" title="Accéder à l’article complet">Confort et convivialité</a>,
      <a href="/david/blog/2013/testament-numerique/" title="Accéder à l’article complet">Testament numérique</a>,
      et <a href="/david/blog/" title="Accéder aux archives">bien d’autres…</a>
    </p>
    <p>
      On peut <a href="mailto:david%40larlet.fr" title="Envoyer un courriel">échanger par courriel</a>. Si éventuellement tu souhaites que l’on travaille ensemble, tu devrais commencer par consulter le <a href="http://larlet.com">profil dédié à mon activité professionnelle</a> et/ou contacter directement <a href="http://scopyleft.fr/">scopyleft</a>, la <abbr title="Société coopérative et participative">SCOP</abbr> dont je fais partie depuis six ans. Je recommande au préalable de lire <a href="/david/blog/2018/cout-site/" title="Attention ce qui va suivre peut vous choquer">combien coûte un site</a> et pourquoi je suis plutôt favorable à une <a href="/david/pro/devis/" title="Discutons-en !">non-demande de devis</a>.
    </p>
    <p>
      Je ne traque pas ta navigation mais mon
      <abbr title="Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33.184162340">hébergeur</abbr>
      conserve des logs d’accès.
    </p>
  </div>
</footer>
<script type="text/javascript">
  ;(_ => {
    const jumper = document.getElementById('jumper')
    jumper.addEventListener('click', e => {
      e.preventDefault()
      const anchor = e.target.getAttribute('href')
      const targetEl = document.getElementById(anchor.substring(1))
      targetEl.scrollIntoView({behavior: 'smooth'})
    })
  })()
</script>