Code in this book will be displayed using a fixed-width font, like so:

<h1>A Perfect Summer’s Day</h1>
<p>It was a lovely day for a walk in the park. The birds 
were singing and the kids were all back at school.</p>

If additional code is to be inserted into an existing example, the new code will be displayed in bold:

function animate() {
  new_variable = "Hello";
}

Where existing code is required for context, rather than repeat all the code, a vertical ellipsis will be displayed:

function animate() {
  …
  return new_variable;
}

Some lines of code are intended to be entered on one line, but we’ve had to wrap them because of page constraints. A ↵ indicates a line break that exists for formatting purposes only, and should be ignored:

URL.open("http://www.sitepoint.com/blogs/2015/05/28/user-style-she
↵ets-come-of-age/");

https://www.sitepoint.com/premium/books/jssass1

The book’s website, containing links, updates, resources, and more.

http://community.sitepoint.com/

SitePoint’s forums, for help on any tricky web problems.

books@sitepoint.com

Our email address, should you need to contact us for support, to report a problem, or for any other reason.

1. Sass, also known as the indented syntax

2. SCSS, or Sassy CSS, a CSS-like syntax

On Mac OS, Ruby comes preinstalled so there’s nothing further to do.

On Debian or Ubuntu Linux distributions, you need to install Ruby manually like so:

sudo apt-get install ruby-full

For other less common Linux distributions, I recommend you check the Ruby official documentation to see how to install it properly.

On a Windows machine, you’ll have to go through the Ruby Installer setup, a simple program that helps install and run Ruby. It’s slightly less straightforward than other operating systems, but what can you do?

Once Ruby is correctly set up, you can start installing gems, in particular the one we care about: sass. To install it, open a terminal window (on Mac OS, it would be the Terminal application, while on Windows, it would be Ruby prompt). Then type the following command:

gem install sass

And that’s it! Sass is now installed on your machine and you can use the sass command to compile your stylesheets. You have to admit it was very simple, wasn’t it?

Now that you’ve installed the Sass gem, let’s try to use it.

The Sass gem provides a sass command that accepts a lot of options. For the sake of simplicity, we won’t be covering them all, although we’ll still address how to use the basics. See the official documentation for more advanced usages.

In its simplest form, the sass command accepts an input file and an output file, like so:

sass input.scss output.css

When working on stylesheets, it’s tedious to execute the former command every time we make a change to the input file. To work around this, we can use what we call a watcher. A watcher is a program that detects when a file is being changed, executing a task when it happens.

Sass comes with a built-in watch feature: the --watch option. Every time the input file is being modified, Sass will recompile it and override the output file:

sass --watch input.scss output.css

As we’ll discuss in great length in Chapter 9, it is quite uncommon to have just one single Sass file to compile. More often than not, styles are written across a plethora of files gathered in a folder. You will want Sass to compile the whole folder without having to specify a list of files manually. This is how you do it:

sass --watch sass/:stylesheet/.

To be able to use node-sass, we’ll obviously require Node.js. The easiest way to install Node.js is by using one of the installers on the home page of the project. Once done, you’ll be able to install node packages, which leads us to the next step.

Node-sass is a Node package distributed through npm. It provides both a command-line interface and a JavaScript API to interact with the inner program. Your first task is to install it—either locally in the project with --save or globally with -g:

npm install node-sass -g

The command-line interfaces (CLI) of Ruby Sass and node-sass are similar but not entirely compatible so if in doubt, refer to the documentation of the relevant library.

Compiling a single file to CSS is the same as with Ruby Sass:

node-sass input.scss output.css

You can also add the --watch flag in the same fashion to tell Sass to automatically recompile the file on change:

node-sass --watch input.scss output.css

However, it’s slightly different when you want to watch a folder:

node-sass --watch sass/ --output stylesheets/

• string (e.g. "Hello world", kittens)

• number (e.g. 42, 1337px)

• color (e.g. hotpink, rgb(1, 33, 7), #BADA55)

• list (e.g. (a, b, c), a b c)

• map (e.g. (a: 1, b: 2))

• bool (true or false)

• null (null)

The string data type has to be the most basic type there is since we use it in our life so much, even outside of any computer-related activity. A string is nothing more than a series of characters, such as Hello world!:

$my-variable: 'Hello world!';

In most languages, a string needs to be quoted, meaning it should be wrapped with quotes, either double (") or simple ('). In Sass, however, strings do not have to be quoted. It is perfectly fine for a string to live by itself without being wrapped within quotes, as long as non-indentifier characters (latin alphabet, numbers, hyphens, underscores, and spaces) are escaped. Moreover, an unquoted string is—thankfully—strictly equivalent to its quoted counterpart, so that "abc" (or 'abc') is the same as abc. Quoting strings is usually considered best practice, however; not only because it sticks to the syntax of most languages, but because there are some classic gotchas with unquoted strings in Sass when they map with a CSS color keyword (such as red).

String variables are useful for storing some CSS values, property names, or identifiers, such as sans-serif, left, or margin-bottom. When storing string content that maps one-to-one with CSS (such as the three aforementioned examples), we usually omit the quotes because CSS requires them unquoted:

$font-name: 'Helvetica';
$font-type: sans-serif;

.foo {
  font-family: $helvetica, $font-type;
}

Note that it is still possible to quote or unquote a string using the quote(..) and unquote(..) native functions. For more information about how functions work, refer to Chapter 4.

Strings can be concatenated (joined together) using the plus symbol (+). You can thus create a new string from several chunks:

$base-path: '/images/';
$file-name: 'kittens';
$extension: 'png';
$file-path: $base-path + $file-name + '.' + $extension;
// -> '/images/kittens.png'

As with strings, numbers are a very basic type of content. I would not dare explain to you what a number is, although I’ll point out a very important specificity about Sass numbers before going any further: a number in Sass can—but does not necessarily—have a unit, like 42px.

This behavior, while unconventional at first glance, actually makes sense: you need to be able to perform operations on numbers with a unit just as you run calculations on numbers without. In other words, both 42 and 42px are numbers, while 42 px and px42 are strings.

Returning to CSS, numbers are typically the sort of items you want to store in variables because they’re likely to be the moving parts of your application. Think of the maximum width of the container (for example, 1180px), or the number of columns in the grid system in use (such as 12). You want to make those values easily configurable in order to keep the codebase clean and maintainable:

$container-max-width: 1180px;

.container {
  width: 100%;
  margin: 0 auto;
  max-width: $container-max-width;
}

Obviously, you can perform operations on numerical values. Sass supports the five basic operators: plus (+), minus (-), multiply (*), divide (/), and modulo (%). Some Sass third-party tools such as Compass or SassyMath add extra math features; for example, power (pow(..)), square root (sqrt(..)), Pi (pi()), and so on.

In the following example, we used the $element-width variable as the value for the width property, as well as a way to compute the negative left margin required to horizontally center the element:

$element-width: 400px;

/**
 * 1. Size the element
 * 2. Horizontally center the element in its container
 *    @TODO: move to CSS transforms once we drop support for IE 8
 */
.foo {
  width: $element-width; /* 1 */
  position: absolute; /* 2 */
  left: 50%; /* 2 */
  margin-left: ($element-width / -2); /* 2 */
}

Before going any further, you might be interested to know that division in Sass is a bit more complex than first expected: the slash symbol (/) actually has a meaning in CSS (think of the font shorthand property) . As a result, there are three scenarios in which Sass does perform division instead of leaving the / as authored:

The following code snippet illustrates these scenarios:

.foo {
  $gap: 20px;
  // No variable nor parentheses: no division performed
  font: 16px / 2 sans-serif; 
  // Wrapping parentheses: division returning 8px
  padding: (16px / 2); 
  // Member as variable: division returning 10px
  margin: $gap / 2; 
  // Arithmetic expression: calculation returning 308px
  width: 300px + 16px / 2; 
}

$value: 42;
$good: $value * 1px;
$bad: $value + px;

$initial-value: 42;
$value-in-px: ($initial-value * 1px); // 42px 
$unitless-value: ($value-in-px / 1px); // 42

Colors occupy a major position in the CSS language. Sass ends up being a valuable ally when it comes to manipulating colors, mostly by providing a handful of powerful functions, yet there’s more it can do.

For starters, a color in Sass—as in CSS— can be expressed in three to four different ways, using:

Any of those notations will make the value a color, thus eligible to be manipulated as a color by Sass.

Storing colors is probably the best use case for Sass variables, as maintaining a strict and consistent color chart has proven to be a difficult challenge, especially in large projects. By keeping frequently-used colors in variables, we save ourselves from guessing and inventing new colors:

$brand-color: #BADA55;

.logo {
  color: $brand-color;
}

It improves more so once you start using Sass native color-manipulation functions, such as darken(..), lighten(..), and mix(..). Let’s now consider an alert module with different themes depending on the type of message (information, warning, confirm):

.message {
  padding: 10px;
  border: 1px solid currentcolor;
}

.message-info {
  $color: blue;
  color: $color;
  background-color: lighten($color, 20%);
}

.message-danger {
  $color: red;
  color: $color;
  background-color: lighten($color, 20%);
}

.message-confirm {
  $color: green;
  color: $color;
  background-color: lighten($color, 20%);
}

Thanks to the lighten(..) function, it is not only possible but also very easy to create a tint of our color to compute the background color of our message. If you already have an idea on how to optimize this code, hold your horses because we will tackle this in the next chapter!

Booleans (or bools, for short) are specific values that exist in almost any programming language. There are only two boolean values: true and false (written slightly differently depending on the language). Sass sticks to these writing conventions.

Because there is no such thing as a boolean value in CSS, booleans are quite worthless on their own. They become interesting when coupled with conditional statements, introduced in Chapter 5. In the meantime, here’s a short example:

$support-legacy-browsers: true;

@if $support-legacy-browsers {
  .clearfix {
    *zoom: 1;
  }
}

.clearfix:after {
  content: '';
  display: table;
  clear: both;
}

As you can see, booleans are perfect to handle toggle-like options, such as shall we support old browsers?, shall we output vendor prefixes?, shall we include this module?, and so on.

$bool: false;

// "if not false"
// which can be rewritten as: "if true"
@if not $bool {
  // We get in there
}

$value: 'Hello world!';
$coerced-value: not not $value; // true

We’re dealing with a particular scenario here because there is one single value that has null as a data type: null. Indeed, null is both the value and its type, making it a very specific element of the Sass language.

Note that it has to be lowercase and unquoted for it to be from null type; NULL or any variant containing uppercase letters is from type string:

$type: type-of(null); // null
$type: type-of(NULL); // string
$type: type-of('null'); // string
$type: type-of('n' + 'u' + 'LL'); // string

null is commonly used to describe an empty value that will be filled later on, or an empty state that’s neither true nor false. Because of this, null has a very handy behavior: when evaluated as a CSS value, Sass will omit the declaration altogether:

$value: null;

.foo {
  // This declaration will not be output since
  // the variable is evaluated as `null`
  color: $value;
}

While it may seem odd at first, this behavior is actually very helpful when building mixins (see Chapter 4) with optional arguments. Instead of testing each argument to see if it has a value, we can take advantage of a null value not being output:

@mixin absolute($top: null, $right: null, $bottom: null, $left:
↵ null) {
  position: absolute;
  top: $top;
  right: $right;
  bottom: $bottom;
  left: $left;
}

Here’s an example:

.foo {
  @include absolute($top: 13px, $left: 37px);
}

This Sass snippet would be compiled to:

.foo {
  position: absolute;
  top: 13px;
  left: 37px;
}

We’ve just seen the five primary data types of Sass, leaving just lists and maps. These two types are atypical as they mostly act as containers.

Take lists, for instance: they are basically what other languages call arrays. Arrays are often used to store a collection of related values, usually to iterate over them in order to perform a repeated action.

A Sass list is a collection of zero or more values separated by either spaces or commas. Values from a list can be of any type, including list, leading to nested lists (which can be quite complex to deal with later on):

$list: (42, hotpink, 'kittens');

From there, it is possible—and likely—to iterate over the values from the list in order to perform a task with them, such as outputting similar CSS rule sets. To do so, we need to use a loop (introduced in Chapter 5).

The first point to know about lists is that it’s the delimiter (either spaces or commas, known thanks to the list-separator(..) function) that makes a list, not the wrapping parentheses. Actually, parentheses are optional unless the list is empty (thus having no apparent delimiter).

$empty-list: ();

That being said, we highly recommend always using parentheses as they make the code easier to read. Any two or more values separated by a space or a comma form a list:

$value: Hello world;
$type: type-of($value); // list
$length: length($value); // 2
$separator: list-separator($value); // space

While the previous example might look like a string, it actually is a two-item list (note the length(..) function call), because of the space delimiter. To make it an explicit string, wrap it in (single or double) quotes. Here’s another—preferred—way of describing the previous list:

$value: ('Hello', 'world');
$type: type-of($value); // list
$length: length($value); // 2
$separator: list-separator($value); // comma

Although more verbose, it’s clear from first glance that the value is indeed a list, and that both values are strings.

While it’s possible to call list-related functions on single values (such as length(..), for instance), it does not make the value an actual list:

$value: 'foo';
$length: length($value); // 1
$type: type-of($value); // string

And since wrapping parentheses do not help to make a value a list, making it ('foo')will also fail. Yet there is a way to create a single item list: Sass allows lists that use a comma as a separator to have a trailing comma after the last value. By adding a trailing comma to any value, Sass coerces it into a list:

$value: ('foo',); 
$length: length($value); // 1
$type: type-of($value); // list

In some ways, maps are similar to lists. Broadly speaking, a map is a series of pairs of associated keys and values where keys are unique to each map. While a list is usually tied to a specific order—as it is basically the only way to find a value within it—a map uses its keys to find their associated value.

In other words, you would use a list when you need an index (for instance, for the :nth-child(..) selector), and a map when you need a key (such as a string):

$message-themes: (
  'info': deepskyblue,
  'danger': tomato,
  'warning': gold,
  'confirm': lightgreen,
);

From there, you either iterate on the map—in which case you will need a loop, see Chapter 5—or you can pick a specific value from the map based on its key using the map-get(..) function:

.message-info    { color: map-get($message-themes, 'info');    }
.message-danger  { color: map-get($message-themes, 'danger');  }
.message-warning { color: map-get($message-themes, 'warning'); }
.message-confirm { color: map-get($message-themes, 'confirm'); }

You have to know that in Sass—unlike JavaScript, for instance—keys of a map can be of any type and not just strings. Yes, lists and maps as well, although they have to remain unique:

$color-names: (
  #ff0000: 'blood',
  #00ff00: 'grass',
  #0000ff: 'ocean',
);

In the previous example, keys are colors. Be aware that using anything other than strings as map keys might confuse developers coming from a background where hash / associative arrays / map keys have to be strings. In my opinion, this is unnecessary and can be avoided by using clean (or less) logic and sticking to string keys.

For more information, be sure to have a look at Using Sass Maps by yours truly.

To definitely override a global variable from a local scope, we use the !global flag. By definitely, I mean that the variable is not shadowed but effectively replaced by a new value.

Let’s have a look at our previous example using the global flag to update the $padding value, instead of simply shadowing it:

$padding: 10px;

.module {
  $padding: 20px !global;
  padding: $padding;
}

.foo {
  padding: $padding;
}

Can you guess what the result will be? Have a look at this if you’re stuck:

.module {
  padding: 20px;
}

.foo {
  padding: 20px;
}

In line four, the !global flag actually reassigns the $padding variable to the new value, making it 20px for the .foo {} rule set as well.

Last but not least when it comes to variable assignment is that there’s a mechanism that makes it possible to assign a variable if it doesn’t have a value yet—the !default flag:

$padding: 10px;
$padding: 20px !default;

.foo {
  padding: $padding; // 10px
}

Because of this, it’s recommended that you use !default when declaring default configuration variables. Not only does it make it clear that the variable is a default value, it also makes reassigning easier.

The !default flag is incredibly useful when building third-party libraries and modules. It enables users to configure the library, but still provide defaults if they don’t:

// Your configuration of the third party library
$third-party-output-prefix: false;

// The third party library has some default values such as
// $third-party-output-prefix: true !default;
// In this case, the value is `false` thanks to `!default`.
@import 'third-party-library';

The !default flag also comes in handy when dealing with dynamically created Sass files from user input, such as theme files:

// User theme stylesheet containing:
// $brand-color: hotpink;
@import 'user-theme';

// Default configuration
$brand-color: grey !default;

.foo {
  color: $brand-color; // hotpink
}

Bear in mind that variables with null value are treated as unassigned by default, which means that a variable assignment with !default will override a variable assignment to null:

$padding: null;
$padding: 20px !default;

.foo {
  padding: $padding; // 20px
}

As there is little to no interest in using a function in place of a variable when no parameter is involved, let’s move on to functions with parameters. These are defined in the function signature as variables, separated with commas. Let’s have a look at a (not-so-useful, yet simple) example, a multiplication function:

@function multiply($a, $b) {
  @return ($a * $b);
}

Parameters can also have a default value—in which case they are called optional parameters. To define an optional parameter, do as if you were declaring a variable in the function signature (without the closing semicolon):

// `$a` is mandatory and `$b` is optional (default value being 2)
@function multiply($a, $b: 2) {
  @return ($a * $b);
}

Note that optional parameters must come after any non-optional parameter. If you try the following, it will throw an error:

// Throws an error:
// > `Required argument $b must come before any optional arguments.`
@function multiply($a: 2, $b) {
  @return ($a * $b);
}

Before going any further, let’s try our new function. When calling a Sass function, you can either pass arguments in the order they are defined, or you can use what we call named arguments or keyword arguments,^[1] in which case you are not entitled to follow the defined order. To use named arguments, do as if you were defining variables in the function call (again, without the closing semicolon):

$element-width: 400px;

.foo {
  // Calling `multiply(..)` with arguments in the defined order
  width: multiply($element-width, 3); // 1200px
  // Calling `multiply(..)` relying on default value 
  // for second parameter
  padding: multiply(10px); // 20px
}

.bar {
  // Calling `multiply(..)` using keyword arguments
  width: multiply($b: 3, $a: $element-width); // 1200px
}

There are three benefits of using named arguments over definition order:

Here’s an example:

@function set-color-theme(
  $primary, 
  $secondary: darken($primary, 10%), 
  $tertiary: lighten($primary, 10%)
) {
  // Do something
}

$color-theme: set-color-theme(hotpink, $tertiary: pink);

In this example:

More often than not, functions are used as CSS values; however, they can be useful in other circumstances. Actually, functions can be used anywhere variables can so within selectors, media queries, properties, values, and inside variables, functions, mixins, and so on. Although, like variables, they might need to be interpolated (see Chapter 3) when used in unconventional places:

// Just for the sake of demonstration, here's a function declaration
@function my-function() {
  @return 'foo';
}

// Calling the function in itself does not work and throws an error:
// > `Invalid CSS after "  my-function()": expected "{", was ";"`
.foo {
  my-function();
}

// Calling the function in place of a property works as long as it 
// is properly interpolated. See chapter 3.
.foo {
  #{my-function()}: 'bar';
}

// Calling the function in place of a selector works as long as it 
// is properly interpolated. See chapter 3.
.foo, #{my-function()} {
  content: 'bar';
}

// Calling the function inside a variable value works perfectly.
$foo: my-function();

// Calling the function in place of a media query value works 
// perfectly.
@media (min-width: my-function()) { .. }

// Calling the function in place of a feature query value works 
// perfectly.
@supports (content: my-function()) { .. }

Finally, functions can have an unknown number of parameters if ever needed. To do so, simply add an ellipsis (...) to the last parameter of the signature:

// `map-deep-get` intends to help getting values 
// deeply nested in maps
// The first parameter is the map to browse
// Any parameter after that are keys nested within each others
@function map-deep-get($map, $keys...) {
  @each $key in $keys {
    $map: map-get($map, $key);
  }

  @return $map;
}

This type of argument is often referred to as arg-list (short for arguments list) and is sometimes referred to as variable arguments. The name is obviously inspired by the actual type of this variable: arglist (as you can see with type-of(..)). If you read this book in chapter order and just finished the chapter about variables, you might recall that I failed to mention the arglist data type. The truth is I wanted to go easy on you to begin with!

arglist is in fact a valid Sass data type that only comes up when dealing with arguments lists. As far as I can tell, an arglist behaves the same way a list does, so I’m not entirely sure why a distinction between the two was needed. Basically, you can loop on an arguments list the way you would a list, and access its items with the nth(..) function the same way:

@function dummy($mandatory, $extra-arguments...) {
  // Do something
}

$foo: dummy('Hello', 'how', 'are', 'you', '?');
// -> $mandatory: 'Hello'
// -> $extra-arguments: 'how', 'are', 'you', '?'

So why bother adding the ellipsis to make this parameter an arguments list when we could use a regular list? Although this is subjective, I feel it clearly indicates there can be as many arguments as needed—possibly a lot.

There is a specific scenario where I do like using arguments lists: when creating aliases. Let’s say you have a function with a long name, such as ns-get-media-context:

// `ns` stands for namespace, which is usually the short name for 
// the app/site/lib.
// Namespacing variables, functions, mixins and placeholders is 
// usually a good idea in order to prevent naming conflicts.
@function ns-get-media-context($media, $options) {
  // Do something
}

Now, depending on how your code is built, it might be tedious to type the name of this function every time. Consequently, you would prefer a shorter name. So we’ll create a get-context alias for ns-get-media-context:

// Alias for `ns-get-media-context`.
@function get-context($arguments...) {
  @return ns-get-media-context($arguments...);
}

Instead of repeating the signature of ns-get-media-context, we used a dummy $arguments parameter with an ellipsis indicating that we accept an unknown amount of arguments. If the signature of ns-get-media-context ever changes, there’s no need to update the alias!

Arguments lists are much more powerful than simply creating aliases, as they can be used to expand a list or a map of values into a series of arguments passed to a function or mixin. Consider the following $media-context-arguments variable containing the media and the options passed to our ns-get-media-context function:

// The first value is the media, the second is the map of options
$media-context-arguments: ('screen', ());

If you had to call the function with these arguments, you’d probably do the following:

$media-context: get-context(
  nth($media-context-arguments, 1), 
  nth($media-context-arguments, 2)
);

Using the nth(..) function, we can grab specific values from a list. This example is fine as there are only two arguments, but what if there were four or five? Surely we can do better than this tedious way. Indeed we can, using arguments lists! When calling the function, we can pass our $media-context-arguments list as a series of arguments using ...:

$media-context: get-context($media-context-arguments...);

In this case, the first argument from the list will be used for the first parameter of the function, the second one for the second parameter, and so on. It’s much more concise and definitely more elegant.

This works exactly the same with a map. Let’s rewrite our $media-context-arguments variable using a map:

$media-context-arguments: (
  'media': 'screen',
  'options': ()
);

By naming our map keys exactly like the parameters from the get-context function, we make it possible to pass the map as a series of arguments, where it will just work™:

$media-context: get-context($media-context-arguments...);

At this point, you know almost everything there is to know about functions—although I must say it’s usually quite hard to find a legitimate use case for Sass functions unless you build a framework or complex architecture. As you’ll soon discover, mixins are typically much more useful.

One task I do like using functions for, though, is asset management. Let’s say we have an assets/ folder containing a subfolder per asset type, such as images/, fonts/, and so on. In order to prevent typing url('assets/images/...') every time we want to refer to an image asset, we can use functions to enhance the CSS url(..) function.

I added SassDoc (see Chapter 10) comments to this example to make it even clearer (and directly usable in your own projects):

/// CDN URL where all assets are served from
/// @type String
$base-url: 'http://cdn.example.com/assets/';

/// Native `url(..)` function wrapper
/// @param {String} $base - base URL for the asset
/// @param {String} $type - asset type folder (e.g. `fonts/`)
/// @param {String} $path - asset path
/// @return {Url}
@function asset($base, $type, $path) {
  @return url($base + $type + $path);
}

/// Returns URL to an image based on its path
/// @param {String} $path - image path
/// @param {String} $base [$base-url] - base URL
/// @return {Url}
@function image($path, $base: $base-url) {
  @return asset($base, 'images/', $path);
}

/// Returns URL to a font based on its path
/// @param {String} $path - font path
/// @param {String} $base [$base-url] - base URL
/// @return {Url}
@function font($path, $base: $base-url) {
  @return asset($base, 'fonts/', $path);
}

This very lightweight system is actually a wrapper for the url(..) CSS function. Instead of manually typing the whole path in the url(..) function, we can use image(..) and font(..) shortcut functions to make it both more elegant and readable:

@font-face {
  font-family: 'My Awesome Font';
  font-weight: normal;
  font-style: normal;
  src: font('my-awesome-font.eot?#iefix') format('embedded-
↵opentype'),
       font('my-awesome-font.woff') format('woff'),
       font('my-awesome-font.woff2') format('woff2'),
       font('my-awesome-font.ttf') format('truetype');
}

.foo {
  background-image: image('kittens.png');
}

This code will be compiled to:

@font-face {
  font-family: 'My Awesome Font';
  font-weight: normal;
  font-style: normal;
  src: url('http://cdn.example.com/assets/fonts/my-awesome-font.eot?
↵#iefix') format('embedded-opentype'), url('http://cdn.example.com/
↵assets/fonts/my-awesome-font.woff') format('woff'), url('http://
↵cdn.example.com/assets/fonts/my-awesome-font.woff2') format
↵('woff2'), url('http://cdn.example.com/assets/fonts/my-awesome-
↵font.ttf') format('truetype');
}

.foo {
  background-image: url('http://cdn.example.com/assets/images/
↵kittens.png');
}

Sass provides a lot of built-in functions to make writing styles an easier task. In the previous chapter, we saw how we could use some functions to manipulate colors such as lighten(..) and darken(..), or lists and maps with length(..). This is only the tip of the iceberg.

There are a lot of math, strings, lists, maps, and colors functions that are usable out of the box. Listing them all here would take too much time (and ink!), so if you’re interested to know more about the native tools Sass provides, I recommend you have a look at the official documentation.

Most of the time, mixins will accept parameters since this is where they really kick in. These parameters can have a default value, as we saw with functions. Let’s add a little embellishment to this: the default value of a parameter can be the value of another parameter defined before it (this is also true for functions). Like in this example, the default value of the $height parameter is the value of the $width argument:

/// Sizing mixin from width and height
/// If height is omitted, same as width
/// @param {Length} $width - element width
/// @param {Length} $height [$width] - element height
@mixin size($width, $height: $width) {
  width: $width;
  height: $height;
}

// Usage
.foo {
  @include size(100%, 42px);
}

.bar {
  @include size(100px);
}

When compiling this code, Sass will render:

.foo {
  width: 100%;
  height: 42px;
}

.bar {
  width: 100px;
  height: 100px;
}

As mixins behave exactly the same as functions regarding arguments, let’s move on to a feature very specific to mixins: the @content directive.

The @content directive—which has no other form than simply @content—allows authors to pass block of styles to their mixins. When a mixin has one or more @content directives defined in its core, it can be given custom content between braces ({ and }), like so:

@mixin my-mixin {
  @content;
}

.foo {
  @include my-mixin {
    // We can add stuff here
  }
}

As is, this mixin has absolutely no purpose; however, being able to pass dynamic content to a mixin turns out to be very handy when you want to define abstractions relating to the construction of selectors and directives. For instance:

@mixin on-event {
  &:hover,
  &:active,
  &:focus {
    @content;
  }
}

.foo {
  color: blue;

  @include on-event {
    color: red;
  }
}

In the previous example, we want .foo to be blue, but red when hovered, active or focused. For more information about the selector reference variable (&), please refer to Chapter 6. Anyway, here is the CSS output:

.foo {
  color: blue;
}

.foo:hover, .foo:active, .foo:focus {
  color: red;
}

As you can see, the @content directive is especially useful when building dynamic selectors or context blocks, such as @media or @supports.

In addition, variables local to a mixin such as those defined in the mixin signature or the mixin scope cannot be used in passed style blocks. They only exist within the mixin scope and not anywhere else. If you try to use one of those variables in a passed style block, it will either default to the global variable if any, or will simply throw an error:

@mixin my-mixin($argument) {
  @content;
}

// Does not work and throws an error
// > `Undefined variable: "$argument".`
.foo {
  @include my-mixin('foo') {
    content: $argument;
  }
}

Life is not all black or all white. Sometimes, there are shades of gray. Sometimes, you need to do it differently, or pull out all stops, and if everything fails eventually you do whatever needs to be done. For instance, “if the weather is good, we’ll have a barbecue; otherwise we can go to Miriam’s and still cook; or else, I’ll stay home.”

Sass does provide a way to handle these scenarios. Put simply, you can place extra conditions between the first @if and the optional @else statement. These are written using a combination of both keywords, like so: @else if <condition>.

Be aware that as soon as a condition is evaluated to true, its code is executed and no other condition in the chain can be matched. Remember that this is basically a switch: in total, either zero or one condition can be matched, not more.

Let’s illustrate this with a dummy example, printing a sentence depending on the value of a number:

$number: 42;

.foo {
  @if ($number > 1337) {
    content: 'Value is greater than 1337px.';
  } @else if ($number >= 0) {
    content: 'Value is between 0 and 1337.'
  } @else {
    content: 'Value is lower than 0.';
  }
}

In this code snippet, our conditional structure allows three outcomes:

We could have gone more granular if we needed to. There is no limit to the number of chained conditional statements, although having too many of them conveys a poorly constructed code and is likely to hurt readability and maintainability.

All right! Now that we know how to use conditions, we can dive a little further and learn how to express advanced statements composed of several expressions. Think about it: choices do not always rely on a single condition; sometimes it is several conditions that, when all matched, will lead to an event such as “if the weather is good enough and I can find some charcoal, I’ll have a barbecue.” Then there’s the case of at least one condition being true, for example: “if I receive a negative answer, or worse, no answer at all, I’ll be disappointed.”

You might be familiar with && (logical AND) and || (logical OR) operators from various languages such as JavaScript or PHP. Sass aims to be a human-friendly language, so it provides and and or keywords respectively, which have to be written in lowercase.

The resolution of an expression involving one or many operators behaves like so: each component of the expression is evaluated on its own, then the results of these evaluations interact with the and and or keywords. For instance:

$apple: true;
$cherry: false;

// This statement is evaluated as such:
// @if true and false { .. }
// Because `false` isn't a truthy value, the statement doesn't match
@if $apple and $cherry { .. }

// This statement is evaluated as such:
// @if true or false { .. }
// Because `true` is a truthy value, the statement does match
@if $apple or $cherry { .. }

Beware when mixing and and or keywords in a single statement. Expressions are evaluated from left to right, and in some cases you might encounter unexpected results. For instance, compare these two identical statements where only the parentheses differ:

.foo {
  @if $apple and ($cherry or $orange) {
    color: "$apple must be truthy and either $cherry or $orange (or 
↵both) must be truthy.";
  }
  
  @if ($apple and $cherry) or $orange {
    color: "Both $apple and $cherry, or $orange (or all of them) 
↵must be truthy.";
  }
}

In the first case, $apple has to be truthy and either $cherry or $orange (or both) must be truthy as well for the condition to match. In the second case, both $apple and $cherry, or $orange (or the three values) must be truthy for the condition to match. Now consider those values:

$apple: false;
$cherry: true;
$orange: true;

$apple is falsy so the first condition is discarded right away; however, since $orange is truthy, the second condition matches. As you can see, parentheses are not always optional and can have a decisive impact on the outcome of a conditional statement.

You might have already heard the expression ternary operator. In computer science, a ternary operator takes three arguments, as the name suggest. The first one is usually a condition that is evaluated, depending on whether its result is truthy or falsy; the second or third argument is returned respectively.

Most languages use a syntax borrowed from C, using a question mark (?) after the condition and a colon (:) between the two possible outcomes.

Let’s take a JavaScript example to illustrate. In this scenario, we define a backgroundColor variable to be red if an error variable is truthy, or green if otherwise:

var backgroundColor = error ? 'red' : 'green';

We now come back to Sass, which is without a ternary operator; however, it does have a ternary function. It’s basically the same except it’s an actual built-in function rather than operator-like syntax. This function is appropriately named if(..).

The first argument of the if(..) function is the condition, the second one is the result if the condition is truthy, and the third one is the returned value if the condition is falsy. This function is useful when wanting to shorten an @if/@else statement to a single line:

$background-color: if($error, red, green);

Here, if the $error variable is truthy, $background-color will be red, otherwise it will be green. We could have written this using a regular condition as well:

$background-color: green;

@if $error {
  $background-color: red;
}

The for-loop is a logical structure that iterates a given number of times. In Sass (as in any other language), the for-loop expects a starting index and an ending index, and runs as many times as needed from start to end. Inside the content the index variable is provided, making it the ideal ally when wanting to iterate over a set while knowing the current index of iteration.

A for-loop is witten as follows:

Let’s look at a few basic examples. First, iterating from 1 through 5 (inclusive), then looping from 2 to 4 (exclusive):

// Using direct numbers and `through`
@for $i from 1 through 5 {
  // Code to execute 5 times, where `$i` equals:
  // 1
  // 2
  // 3
  // 4
  // 5
}
 
// Using variables and `to`
$start: 2;
$end: 4;
 
@for $index from $start to $end {
  // Code to execute 2 times, where `$index` equals:
  // 2
  // 3
}

For-loops are especially handy when used with :nth-child(..) and :nth-of-type(..) (as well as the less popular :nth-last-child(..) and :nth-last-of-type(..)) pseudo-classes as they rely on numeric indexes.

For instance, let’s imagine that you have a fade-in animation that you apply to all items of a container with an increasing delay to make them appear one after the other. Without a loop, you could end up writing:

.item:nth-child(1)  { animation-delay: 0.0s; }
.item:nth-child(2)  { animation-delay: 0.1s; }
.item:nth-child(3)  { animation-delay: 0.2s; }
.item:nth-child(4)  { animation-delay: 0.3s; }
.item:nth-child(5)  { animation-delay: 0.4s; }
.item:nth-child(6)  { animation-delay: 0.5s; }
.item:nth-child(7)  { animation-delay: 0.6s; }
.item:nth-child(8)  { animation-delay: 0.7s; }
.item:nth-child(9)  { animation-delay: 0.8s; }
.item:nth-child(10) { animation-delay: 0.9s; }

A bit tedious, isn’t it? Especially if you have to update the gap between two arrivals, or the number of items. This is typically where a for-loop can kick in and save the day:

@for $i from 1 through 10 {
  .item:nth-child(#{$i}) {
    animation-delay: ($i - 1) * 0.1s;
  }
}

Let’s go through this piece of code one line at a time to fully understand what is happening. In the first iteration, the value of $i is 1. We open a rule set with .item:nth-child(1) as a selector, to which we apply the animation-delay property. The value for this property is 0s (because, 1 - 1 * 0.1 = 0). Then the $i is increased by 1 and we go through the loop again. This is repeated until $i reaches 10, in which case the loops plays one last time and then stops running.

Note how we need to escape the $i variable (#{$i}) in the pseudo-class to print it correctly as part of the selector. Then, we subtract one to the $i variable (so that there is no delay on the first item) and multiply this with 0.1s to have the correct delay for each item.

Similarly, we could make use of the CSS hsl(..) color function and how it expects a number as a hue. We could apply a slightly different border color (or background color, or whatever) to all items of our list so as to generate a rainbow list:

@for $i from 1 through 10 {
  .item:nth-child(#{$i}) {
    border: 1px solid hsl($i * 15, 75%, 75%);
  }
}

As in our previous example, the first loop iteration’s value of $i is 1. We create the same selector as earlier—.item:nth-child(1)—to which we apply the border property with a value of 1px solid hsl(15, 75%, 75%). Then the loop starts over with $i being incremented by one.

In this case, 15 is really just an arbitrary delta. The first item will have a hue of 15, the second one 30, and so on. As we have ten items, the hue will spread from 15 to 150 (a little less than half the color wheel). Depending on the number of items and the amplitude you want for the rainbow effect, you might increase or decrease this value.

Our last example before moving on to the next loop will be to apply different font sizes to the six levels of headings we have in HTML. We could loop through a list of six sizes and apply them respectively to each level of heading:

$sizes: (2em, 1.75em, 1.5em, 1.25em, 1em, 0.75em);

@for $i from 1 through length($sizes) {
  h#{$i} {
    font-size: nth($sizes, $i);
  }
}

This code would compile to:

h1 { font-size: 2em; }
h2 { font-size: 1.75em; }
h3 { font-size: 1.5em; }
h4 { font-size: 1.25em; }
h5 { font-size: 1em; }
h6 { font-size: 0.75em; }

If we want to be a bit more secure, we could make sure that we limit it to six in order not to generate any undesired selector.

To do so, we can use the min(..) function from Sass. In the following scenario, the $sizes list has seven values. We want to loop through the values of the list, but only up to six values. We therefore need to take the minimum number between six and the length of the list as the end index of the loop:

$sizes: (2em, 1.75em, 1.5em, 1.25em, 1em, 0.75em, 0.5em); // 7 value
↵s!

@for $i from 1 through min(length($sizes), 6) {
  h#{$i} {
    font-size: nth($sizes, $i);
  }
}

The each-loop is a logical structure aiming at iterating over a collection, which is either a list or a map in Sass. Therefore, an each-loop runs as many times as the number of elements in a collection (items in a list, key/value pairs in a map). You could imagine a scenario where you store aliases for font sizes in a map such as xs for 0.75em, s for 1em, and so on. By iterating on the map, you could possibly generate selectors to which you would apply a specific font-size value.

There are a few variations of the each-structure, so we will start with the simplest and most popular one: looping through a list. Then we’ll slowly move towards iterating over nested lists and maps.

A simple each-loop is written as follows:

As an example, consider the following code aimed at going through the alphabet, one letter after the other. We first define a list of 26 letters. Then we loop through it with an each-loop, accessing the current letter in the loop with $letter:

$alphabet: (a b c d e f g h i j k l m n o p q r s t u v w x y z);

@each $letter in $alphabet {
  // Do something with `$letter`
}

A good use case would be applying a specific background image to a series of elements, such as a photo for each author in a list:

$authors: ('hugo', 'miriam');

@each $author in $authors {
  .section-#{$author} {
    background-image: url('/images/authors/#{$author}.jpg');
  }
}

Here again, we interpolate the variable to correctly print it as part of a selector. We do the same inside the URL as it lives inside quotes (hence, it would be printed as $author without a proper variable interpolation).

In such a scenario, we rely on the image file being named after the class used for the section. This is a fine assumption and way of doing if we actually can name the files the way we want (which is not always the case when using a CMS, for instance).

If we know the filenames but they don’t quite match the section names, we can create sublists and rely on what is called the multi-assignment feature from the @each directive to rewrite our example.

To put it simply, multi-assignment is a feature from Sass each-loops that allows authors to define several variables that can then be accessed in the loop content. It is especially useful when iterating on maps, or, as you’ll notice in the next code snippet, nested lists:

$authors: (
  ('hugo', 'hugo_giraudel.jpg'),
  ('miriam', 'suzanne-miriam.png')
);

@each $author, $filename in $authors {
  .section-#{$author} {
    background-image: url('/images/authors/#{$filename}');
  }
}

In this example, we first define a two-dimensional list where the top level contains authors and the sublists contain everything we need for each author. Then we use multi-assignment in the loop definition to define a variable per column. The word “column” is actually fictive here, and only means that the $author variable will serve for the first value of each sublist, and the $filename variable will serve for the second value of each sublist. This code would compile to:

.section-hugo {
  background-image: url("/images/authors/hugo_giraudel.jpg");
}

.section-miriam {
  background-image: url("/images/authors/suzanne-miriam.png");
}

We are not limited to two-item lists, of course! Let’s say we want to have a color per author. Using multi-assignment, it ends up being very easy to do:

$authors: (
  ('hugo', 'hugo_giraudel.jpg', deeppink),
  ('miriam', 'suzanne-miriam.png', hotpink)
);

@each $author, $filename, $color in $authors {
  .section-#{$author} {
    background-image: url('/images/authors/#{$filename}');
    color: $color;
  }
}

To add a custom color to each author, we simply add a third item in each author’s list, and a third variable in the loop definition. The code would compile like this:

.section-hugo {
  background-image: url("/images/authors/hugo_giraudel.jpg");
  color: deeppink;
}

.section-miriam {
  background-image: url("/images/authors/suzanne-miriam.png");
  color: hotpink;
}

The problem with this solution is that it quickly becomes unreadable and unmaintainable when there are more than three or four parameters. This usually indicates that it’s time to switch to a map. Often, a map is a more robust solution than nested lists as it allows you to name values (the purpose of map keys), making the code easier to read and maintain.

In our current scenario, we actually need a list of maps. This will comprise a list of authors where each author is a map with three key/value pairs: a section name, a filename, and a color. Then, we’ll use the map-get(..) function to access individual author properties inside the loop:

$authors: (
  (
    'name': 'hugo',
    'filename': 'hugo_giraudel.jpg',
    'color': deeppink
  ),
  (
    'name': 'miriam',
    'filename': 'suzanne-miriam.png',
    'color': hotpink
  )
);

@each $author in $authors {
  $author: map-get($author, 'name');
  $filename: map-get($author, 'filename');
  $color: map-get($author, 'color');

  .section-#{$author} {
    background-image: url('/images/authors/#{$filename}');
    color: $color;
  }
}

Here we’ve started the loop content by storing all properties from the author map in variables, but this, of course, is not required. We could have directly put the map-get(..) calls in the rule set, although it would have made the code slightly harder to read.

Finally, we could also write our code using nested maps instead of nested lists, or a list of maps. In this case, we’d map an author name (e.g. miriam) to a map of properties (filename and color). Then, we’d use the map-specific multi-assignment of the @each directive to iterate over it:

$authors: (
  'hugo': (
    'filename': 'hugo_giraudel.jpg', 
    'color': deeppink
  ),
  'miriam': (
    'filename': 'suzanne-miriam.png', 
    'color': hotpink
  )
);

@each $author, $properties in $authors {
  $filename: map-get($properties, 'filename');
  $color: map-get($properties, 'color');

  .section-#{$author} {
    background-image: url('/images/authors/#{$filename}');
    color: $color;
  }
}

When using an each-loop to iterate over a map, the first variable in the loop definition contains the current key, and the second one contains the current value. In this case, $properties contains a map with filename and color keys.

The while-loop is, as the name suggests, a way to execute a chunk of code as long as a condition remains true. While-loops are frequently used in low levels of software applications, especially to simulate threads, a process that we want to run permanently until there is some form of change.

In Sass, it is very hard to find a decent use case for a while-loop. Both the @each and @for directives cover close to 100% of cases, so it is highly unlikely for you to find a while-loop in a Sass file—unless a library is doing crazy stuff (which should be avoided in a live project).

Nevertheless, here is how a while-loop is described in Sass:

$number: 4;

@while ($number > 0) {
  // Do something with `$number`
  $number: $number - 1;
}

Take care to ensure that the condition ends up being falsy at some point or you’ll get stuck in an infinite loop.

It’s difficult to find a single good example for a while-loop in Sass. A not-so-bad one would be to build a str-replace(..) function, but it turns out that creating a recursive function is actually easier and just as—if not more—efficient.

We often put selector nesting and variable scoping together, and for good reason. Because of the way variables work in Sass, when defining variables inside a rule set, all the nested rule sets will have access to them. Consider our previous example:

.container {
  margin: 0 auto;
  max-width: 42em;
  padding: 0 1em;

  p {
    text-indent: 1em;
  }
}

Let’s assume we want the horizontal padding of the container and the text indentation of paragraphs to be a shared value (here, 1em). A variable is a smart and simple way to do this. Now, depending on where we declare it, its access will be restricted to some selectors and not others.

In the following code snippet, the $rhythm variable is defined at the root level, which means it’s available for the entire stylesheet. This includes other (imported / importing) files. That might be what you’re after. Or not:

$rhythm: 1em;

.container {
  margin: 0 auto;
  max-width: 42em;
  padding: 0 $rhythm;

  p {
    text-indent: $rhythm;
  }
}

What if we want to restrict $rhythm to the .container selector? We have seen how to do this in the chapter dedicated to variables: we move the variable declaration two lines down:

.container {
  $rhythm: 1em;

  margin: 0 auto;
  max-width: 42em;
  padding: 0 $rhythm;

  p {
    text-indent: $rhythm;
  }
}

What’s nice about this is that the p rule set is still able to access $rhythm because it’s been defined in a parent scope. We get the best of both worlds: our variable is scoped to a specific context (not global), and we can use it to share a value between several rule sets. Win-win.

Ah, the almighty ampersand selector! It’s actually quite an informal nickname for the parent selector reference. (You have to admit that’s a bit less catchy.)

When nesting rules within each other, it might be useful to dynamically access the parent selector from an inner rule. The & selector does precisely this. Again, it’s a tough concept to explain without jumping on a piece of code. Consider a classic link styling:

a {
  color: deeppink;
}

a:hover,
a:active {
  color: hotpink;
}

How would we handle it if we wanted to nest the second rule set inside the first? It’s not really a child per se, more like a state. Let’s try something that won’t work first, just for the sake of our explanation:

a {
  color: deeppink;

  // This is not the selector you are looking for.
  :hover,
  :active {
    color: hotpink
  }
}

Can you guess what will be the CSS output for this code sample? It might be a bit tricky if you are unfamiliar with Sass nesting. If you guessed a :hover and a :active with a space, you’d be right! When doing this, Sass treats :hover, :active like children, creating the selector from both parts (a, and :hover, :active) just like before.

So how do we prevent Sass from adding this extra space between a and :hover? We use the ampersand selector to reference the parent selector inside the nested one. Let’s see:

a {
  color: deeppink;

  &:hover,
  &:active {
    color: hotpink
  }
}

In this extremely simple scenario, & literally represents a once the selectors have been “unfolded”. Sass will therefore create the intended CSS, as described at the beginning of this section.

This is, of course, one of the many use cases for the parent selector reference. For instance, if we come back to our paragraph example from earlier, we could also write a rule set for all paragraphs, and then restrict a part of it (with a nested rule set) to paragraphs that live inside a .container:

p {
  margin: 1em 0;

  .container & {
    text-indent: 1em;
  }
}

Once Sass unfolds all the nested selectors, it ends up with a first selector that is p, and then another that is .container p. As you might have guessed, the & represents p in this scenario.

The & reference is replaced with the parent selector as it appears in the CSS. This means that when dealing with a deeply nested rule, the parent selector will be fully resolved before the & is replaced:

.container {
  margin: 0 auto;
  max-width: 42em;
  padding: 0 1em;

  p {
    text-indent: 1em;

    a {
      color: deeppink;

      &:hover,
      &:active {
        color: hotpink;
      }
    }
  }
}

The previous code snippet will be compiled to:

.container {
  margin: 0 auto;
  max-width: 42em;
  padding: 0 1em;
}

.container p {
  text-indent: 1em;
}

.container p a {
  color: deeppink;
}

.container p a:hover,
.container p a:active {
  color: hotpink;
}

The ampersand selector can also be followed by a suffix that will be added to the parent selector. Consider a scenario where we have a base class—let’s say .component—that is slightly modified when the component is hidden—let’s say .component-hidden:

.component {
  display: block;

  &-hidden {
    display: none;
  }
}

In this scenario, the resulting selector will not be a selector with several parts. It will be a new class made from the initial one, thanks to the ampersand and the suffix:

.component {
  display: block;
}

.component-hidden {
  display: none;
}

The @at-root directive was introduced so as to be able to emit a style block at the root of the document, rather than nest it beneath its parent selectors. Admittedly, the use cases for this feature are difficult to come by. Either Sass is clever enough so that we don’t have to use it, or the cognitive overhead of a solution involving @at-root is usually not worth the trouble.

Actually, there is one simple yet not that uncommon use case: qualifying a class from within its rule set. Let’s say that you style buttons with .button, but want to apply different styles when buttons are links (a elements). You might be tempted to write:

.button {
  display: inline-block;

  a& {
    text-decoration: none;
  }
}

Unfortunately, this will fail to work, with Sass giving the following error:

Invalid CSS after "a": expected "{", was "&" "&" may only be used at
↵ the beginning of a compound selector.

When faced with such an error, we can try to interpolate the ampersand selector:

.button {
  display: inline-block;

  a#{&} {
    text-decoration: none;
  }
}

This does prevent the compilation from failing but yields an unexpected result, even though it’s quite close to the desired one:

.button {
  display: inline-block;
}

.button a.button {
  text-decoration: none;
}

To avoid having the a#{&} selector actually nested within the .button rule set, we can make good use of the @at-root directive and have Sass output this rule set at the root of the document:

.button {
  color: red;

  @at-root a#{&} {
    color: blue;
  }
}

Our final CSS looks like this:

.button {
  display: inline-block;
}

a.button {
  text-decoration: none;
}

My main complaint is that @extend messes with the cascade, changing the specificity of styles in ways that are not obvious or easy to control. While mixins inject code where you call them, @extend injects code somewhere else entirely—adding selectors to the original extended code block, which might be in a different file or even hidden inside a third-party package. While that may not be a big issue for a utility such as clearfix, it can cause major issues when used recklessly. Don’t try this at home:

%large {
  font-size: 4rem;
}

%small {
  font-size: 0.75rem;
}

.message {
  @extend %small;
}

.important {
  @extend %large;
}

Which class has a higher specificity, .message or .important? Usually, in a conflict the class defined second will take priority over any preceding classes. In this case it doesn’t matter what order we defined the classes, only the order we defined our initial placeholders. No matter how you define your classes later in the document, an extension of %small will never override an extension of %large. The specificity isn’t determined by the order in which you use extensions, but the order in which they’re defined:

.important {
  font-size: 4rem;
}

.message {
  font-size: 0.75rem;
}

If there is any chance that specificity will be an issue, @extend should be off the table.

Because a selector can appear multiple times in a stylesheet, extended selectors are replaced everywhere they appear. You might be altering code you haven’t considered. Using our initial message example, what happens if we want the .message class to look different in other contexts?

// in one file…
.message {
  background-color: gray;
  border: 1px solid black;
  margin: 1em;
}

.warning {
  @extend .message;
  background-color: red;
}

// in another file…
.dark-theme {
  .message {
    background-color: black;
  }
}

We never explicitly asked for .dark-theme .warning to get a different style, but now there’s one that completely overrides the original purpose:

.message, .warning {
  background-color: gray;
  border: 1px solid black;
  margin: 1em;
}

.warning {
  background-color: red;
}

.dark-theme .message, .dark-theme .warning {
  background-color: black;
}

Many teams avoid this problem by only extending placeholder selectors and only defining placeholders in one location. That’s a great rule of thumb, and helps to make extensions clear and controllable.

You’ll remember that the entire purpose of @extend was to cut down on bloat. In some cases, this can work in your favor, but sometimes it can backfire once you account for gzip—the best practice for serving CSS files. Gzip uses recurring patterns to improve compression. Even though it is clear that our mixin output is larger than our extended output for the clearfix above, various people have reported that mixins can outperform extensions after zipping.

But even before gzip, there’s a chance that you’re causing unexpected bloat and confusing output. Consider the following bad idea, which tries to extend a bold-text selector:

.typography {
  .bold {
    font-weight: bold;
  }
}

.widget-warning strong {
  @extend .bold;
}

.widget-info strong {
  @extend .bold;
}

.alert-error .important {
  @extend .bold;
}

This looks great in Sass, but the CSS output is hard to read. You’d want to avoid seeing this in your browser inspector:

.typography .bold,
.typography .widget-warning strong,
.widget-warning .typography strong,
.typography .widget-info strong,
.widget-info .typography strong,
.typography .alert-error .important,
.alert-error .typography .important {
  font-weight: bold;
}

Instead of repeating a relatively short string (font-weight: bold;), we’ve started repeating long selector chains. We’ve also triggered the nesting feature, which forces Sass to output multiple selector options for each extension. Do we always want .typography first in the chain, or do we sometimes want it in the middle? There’s no way to state that explicitly, so Sass is designed to cover all the possibilities.

When you see that long list of selectors in your browser inspector, it can be difficult to trace back to your original code—or hard to know your original intention. Suffice it to say, you should look at the output CSS to make sure it means what you intended. But that’s true for any feature, @extend or otherwise. If you’re using a preprocessor, you should be checking the output for unexpected issues.

Last but not least, @extend fails to work at all across media queries. Selectors inside one media query cannot extend selectors outside that same query (and vice versa). The following will result in an error:

%clearfix::after {
  content: '';
  display: table;
  clear: both;
}

@media (min-width: 40em) {
  .container {
    @extend %cleafix;
  }
}

Various people have proposed using mixins that will wrap extends, so you can choose between the two options on the fly:

// Defining a Mixtend:
@mixin clearfix($mixin: false) {
  @if $mixin {
    &::after {
      content: '';
      display: table;
      clear: both;
    }
  } @else {
    @extend %clearfix;
  }
}

%clearfix {
  @include clearfix(mixin);
}

// Using a Mixtend:
.container {
  @include clearfix;
}

@media (min-width: 48em) {
  .grid-row {
    @include clearfix(mixin);
  }
}

It’s a clever solution, but I’m unsure whether it’s worth the effort, and hiding @extend inside a mixin might just make it more dangerous. If it’s better for your situation, just use a mixin.

While the media query issue may get fixed down the road, the other issues are here to stay. It’s nothing to do with how @extend is implemented in Sass; rather it’s from basic problems with trying to represent inheritance in CSS. The current hold-up with @media is that every proposal fixing that issue would make the other issues worse.

In the end, we’re unwilling to say that @extend is always bad. Many people put it to good use, and you can too. But it’s true that mixins are often easier to understand, with little or no downside in most cases.

• informing the user of an assumption made about the code in order to avoid surprise and hard-to-track bugs

• advising about a deprecated function or mixin as part of a library or framework

You may or may not be familiar with the @debug directive, which prints the value of a SassScript expression to the standard output stream in the same fashion as @warn. You might be wondering why there are two features performing the same task, and what could possibly be the difference between the two.

Well, there are two major differences between warning about a value and debugging a value. The first one is that warnings can be turned off using the quiet option. Debugs, on the other hand, will always be printed so that you remember to remove them when you’re done using them.

The second difference is that warnings come with a stack trace—a report of the active stack frames at a certain point in time during the execution of a program. As a result, you know from where they’re being emitted. Debugs only print the value, along with the line they were called in, but they offer no extra information.

The @debug directive can really come in handy when you want to know what’s inside a variable, for instance:

@debug $base-font-size;

As mentioned, the CSS @import directive allows you to reference one CSS file from another. Importing is handled by the browser and requires additional HTTP requests—since the importing file has to be parsed before the @import directive is discovered. If you have a chain of files importing each other, those imports will happen in sequence, blocking the document from rendering until all the CSS has loaded. For that reason, most people avoid CSS imports entirely.

Using CSS imports, you can reference another CSS file using relative or absolute paths, even adding a media query rule for conditional imports. Even though Sass provides different functionality under the same at-rule, there are various cases in which Sass will fall back to the vanilla CSS output, such as when:

The following will compile to standard CSS imports, even in Sass:

@import 'relative/styles.css';
@import 'http://absolute.com/styles.css';
@import url('landscape.css') screen and (orientation: landscape);

Sass imports look similar to CSS imports, but the imported files are compiled into one single output file, as though their contents (including variables, mixins, functions, and placeholders) were copied and pasted into place before compilation. This type of Sass import will only work on files with .sass or .scss extensions, but you can leave the extension off when importing (as long as there are no similarly named files). In fact, we recommend dropping the extension whenever you can, for simplicity. It’s also possible to import multiple files in one command, or import files into a nested context:

// Import an explicit file relative to the current directory
@import 'path/to/explicit.scss';

// Import a file with either the .sass or .scss extension
@import 'implicit';

// Import multiple files...
@import 'path/to/emory.scss',
        'miko',
        'path/to/gracie';

// Import a file into a nested context...
// (imagine the file copied and pasted into this context)
.latte {
  @import 'espresso';
}

The most common use of Sass importing is for partial files—Sass files that are not compiled on their own but are for importing into other files. If you want a Sass file to remain uncompiled until it’s imported, add an underscore (_) to the start of the filename. Sass files that start with _ won’t compile on their own, but can be imported into other files. When importing partials, Sass allows you to leave the _ off, which is similar to leaving off an extension. For example:

// _authors.scss
.miriam { background: blue; }

// jumpstartsass.scss
@import 'authors'; // Shorthand for importing '_authors.scss'

// jumpstartsass.css (compiled CSS)
.miriam { background: blue; }

Running Sass in this directory (sass --update .) compiles jumpstartsass.scss to jumpstartsass.css; however, it won’t create an _authors.css file, since it has a leading underscore.

Sass partials form the basis of any Sass architecture. Because all Sass imports are handled at compile time and never interrupt the browser, it’s perfectly safe (and recommended) to use as many partials as necessary, compiling them into a single stylesheet for production. For the sake of being organized we recommend breaking out partials liberally, sorting them into folders, and importing them all back into one single master file for compilation. A common Sass directory for a project might look like this:

sass/
|
|– config/
|   |– _colors.scss      # Color palettes
|   |– _webfonts.scss    # Webfont information
|   …                    # Etc.
|
|– layout/
|   |– _navigation.scss  # Navigation
|   |– _banner.scss      # Site Banner
|   …                    # Etc.
|
|– modules/
|   |– _calendar.scss    # Calendar widget styles
|   |– _contact.scss     # Contact form styles
|   …                    # Etc.
|
|– patterns/
|   |– _buttons.scss     # Buttons
|   |– _dropdown.scss    # Dropdown
|   …                    # Etc.
|
|- main.scss             # The primary Sass file to be compiled

After organizing all your partials, they can be imported into the single primary main.scss file for compilation:

// Primary Sass File: main.scss
@import 'config/colors';
@import 'config/webfonts';

@import 'patterns/buttons';
@import 'patterns/dropdown';

@import 'layout/navigation';
@import 'layout/banner';

@import 'modules/calendar';
@import 'modules/contact';

1. Break your code into the smallest logical component partials.

2. Organize your partials into grouped folders based on specificity.

3. Import those partials into one master file in order of specificity.

OOCSS is one of the original front-end architectures, and the initial inspiration for adding the @extend directive to Sass. A project from Nicole Sullivan, it places a strong emphasis on finding the right granularity for CSS objects, a theme that comes up in most of the systems we’ll look at here.

Sullivan argues that rather than trying to match back-end objects, a CSS object should look for more granular design patterns that might be used across a variety of content types. A prime example is what she calls the media object—a fixed-size media element (such as an image or video) alongside fluid content such as text.

Figure 9.1. Facebook media object

If you look at Facebook, which Sullivan helped refactor, you’ll see one media-object design used across the site to display a wide range of back-end objects—from stories and comments, to notifications, advertisements, and profile details. You can see an example in Figure 9.1. By defining objects at a granular level, a small amount of CSS can be used to style large swathes of the application.

At its best, OOCSS is a powerful tool for simplifying CSS and perfecting the performance of large-scale applications. But taken to extremes, the OOCSS approach can leave you with a mess of single-purpose utility classes (such as .padding-left-10px) that couple your HTML and CSS too tightly, and eliminate any maintainability you might get from more semantic code. You’ll have to find the right balance for each project.

Whatever else you do, the two main principles of OOCSS are worth keeping in mind (indeed, committing to memory) while you work out your own architecture:

There is no organizational structure built into OOCSS, but there is a framework available on GitHub that provides a number of common objects, as well as documentation on customizing the framework to your needs.

Atomic Design is also driven by questions of granularity. Initially devised by Brad Frost, an atomic project is broken down into five stages: atoms, molecules, organisms, templates, and pages. The idea is to style the stages in order, starting granular and working outwards, with each stage building on the one before.

According to Atomic Design, atoms can be abstract information such as color palettes, fonts, and typographic scales; they can also be default styles for tags such as form labels, buttons, and paragraphs. Since I can never remember the scientific terms, I break these two ideas down further and refer to the former as “configuration” or “settings” (having no output on their own), and the latter “base” or “initial” styles (having output).

Atoms can be put together to form molecules. Combine an image with a paragraph and button (all atoms), and you have a simple product-listing molecule. Molecules are small components that do one task well. Group a number of these molecules together, and you have an organism (in this case, a gallery of products). Organisms are larger grouped components that form a section of the interface. Your site banner might also be an organism, combining a logo, navigation, and search form. I call these next two stages “patterns” and “components,” but it’s recommended that you work with your team to find terms you all understand clearly.

At this point, the developers of Atomic Design abandon their biochemical analogy, and move to templates. Templates combine the smaller molecules and organisms into actual layout structures. If you run a news site, you might have a list template and a detail template for your articles. Each specific instance of a template is called a page. The home page and archive page of your news site may both use the article-list template, but they have different content. Pages are the most specific combination of all the other stages.

A standard Atomic Design directory will be organized into these five stage-based folders:

sass/
|
|– atoms/
|   |– _colors.scss
|   |– _buttons.scss
|   …
|
|– molecules/
|   |– _navigation.scss
|   |– _search.scss
|   …
|
|– organisms/
|   |– _banner.scss
|   |– _gallery.scss
|   …
|
|– templates/
|   |– _list.scss
|   |– _detail.scss
|   …
|
|– pages/
|   |– _home.scss
|   |– _archive.scss
|   …
|
|- main.scss

Atomic Design also provides a framework called Pattern Lab. As with OOCSS, avoid confusing the framework with the design system philosophy. You can apply the philosophy anywhere, but the tools are still available if you need them. Frameworks can be a great way to keep code consistent across a large team or project, but always remember that you know your project better than Brad Frost, Nicole Sullivan, or the authors of this book. If there’s a conflict between your needs and the framework you’re using, always put your project first.

BEM is a system developed by the Yandex team. This is a much more extensive system, with its fingers in every aspect of your code—from JSON data structures, to templates, as well as CSS.

The BEM CSS architecture is built around the three ideas in its title. Blocks are components of any size, and can be nested inside each other. The header block might contain a logo block, a navigation block, and a search block. Blocks are reusable, independent, and mobile—so they can be put anywhere on the page, and repeated as often as necessary. Elements are the constituent parts that belong to a specific block. A menu block might be made up of four tab elements. Modifiers are flags on blocks or elements that change their appearance, behavior, or state.

The most immediately recognizable aspect of BEM syntax is an intricate naming convention that uses long class names instead of nesting selectors. Rather than targeting .block .element, you would target .block__element. There are variations on the exact syntax, but the formal documentation allow hyphens (-) within a block, element, or modifier name; double underscore (__) between block and element names; and single underscore (_) before a boolean (true/false) modifier, or between a key-value modifier name and its given value.

Here’s an example straight from the BEM documentation that defines a form block with a _login boolean modifier, a _theme_forest key-value modifier, and two elements:

<form class="form form_login form_theme_forest">
  <input class="form__input">
  <input class="form__submit form__submit_disabled">
</form>

A related Sass partial would look like this:

.form {}
.form_theme_forest {}
.form_login {}
.form__input {}
.form__submit {}
.form__submit_disabled {}

When BEM naming became popular, people started using the Sass parent selector (&) to automatically generate their BEM class names with less repetition in the code:

.form {
  border: 1px solid black;

  &__submit {
    background-color: green;

    &_disabled {
      background-color: gray;
    }
  }
}

.form {
  border: 1px solid black;
}
.form__submit {
  background-color: green;
}
.form__submit_disabled {
  background-color: gray;
}

On the surface, this works great—but it comes at the cost of searchability, as was pointed out in Chapter 6. If another developer has to find the .form__submit_disabled Sass in order to make a change, searching your Sass files for .form__submit_disabled will fail to return any results.

The BEM file structure goes beyond CSS and Sass, organizing all assets (JavaScript, CSS, images, and so on) into shared directories by block. Elements and modifiers have their own subdirectories using the same underscore-driven naming conventions:

blocks/
|- input/
|  |- _type/
|  |  |- input_type_search.css
|  |
|  |- __box/
|  |  |- input__box.css
|  |
|  |- input.css
|  |- input.js
|
|- button/
|  |- button.css
|  |- button.js
|  |- button.png

SMACSS is a book, workshop, and philosophy by Jonathan Snook. Like Atomic Design, this architecture uses five categories for organizing your CSS, except that they aren’t organized from small to large. Detailed naming patterns are provided to help keep class names consistent. It’s one of the most popular brand-name architectures, and may even be the most comprehensive.

The five categories here are base, layout, module, state, and theme. Base rules define the default style of elements, which work similarly to the atoms of Atomic Design. Layout styles are used to break the document into sections that can contain modules, the individual components of a design. State rules define different JavaScript-dependent states for a module or layout; that is, how does it change when it is active or inactive, collapsed or expanded? Most sites have no need for themes, but they can be used to describe multiple style options for the same modules.

In order to help keep CSS and HTML modules small and mobile, SMACSS pays special attention to what Snook calls the depth of applicability. You may know of the Sass “inception rule,” which states that you should never nest selectors more than three layers deep. That rule helps to keep selectors short (no more than three layers), but the depth of applicability is a bit different. Rather than counting the number of layers, it counts the total DOM distance between the first and last layers.

Let’s look at a simple example. Since .mammalia > .primates > .hominidae > .sapiens > .rollsman > .erin has a depth of six, the same basic selector written as .mammalia .sapiens .erin would still have a depth of six. By shortening the selector, we’ve lowered the specificity (a good thing!), but we still have a large depth of applicability. The problem with so much depth is that it makes our CSS more dependent on a particular HTML structure. This is generally solved by keeping our HTML and CSS components small and independent from their containers.

Hugo uses a variation of SMACSS for organizing Sass partials. He calls it the “7-1” system, because it uses seven folders of partials and one master file to pull them all together.

The base/ folder contains broad standards across a site—such as a reset, default styles for common HTML tags, common animations, and basic typography. The layout folder includes everything one might need for laying out the structure of a site; for example, boilerplate-like headers, footers, and navigation, as well as your grid system and layout helpers. The components folder is organized into partials by component; the pages folder contains any page-specific styles; and a themes folder holds any theme-related styles (if your project has multiple themes).

7-1 also includes an abstracts folder for Sass tools and helpers, which is organized into partials for global variables, functions, mixins, and placeholders. Nothing in this folder should output any CSS if compiled on its own.

Hugo leaves the possibility of organizing these partials by topic (typography, colors, etc.) rather than type (variables, mixins, functions) for larger projects, but I recommend that across the board. The topic is always the more important distinction in my mind. Placeholders are the only type that I treat in any special way, because their output remains in the location they are defined—while variables, functions, and mixins create output where they are used.

Finally, there is a vendors folder for third-party libraries, frameworks, and toolkits such as Normalize, Bootstrap, jQueryUI, FancyButtonsOMG, and so on. These are often kept separate so as to not edit them should they need upgrading later.

Put it all together, and you have a Sass directory similar to this:

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
|   …                    # 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 & placeholders helpers
|
|– vendors/
|   |– _bootstrap.scss   # Bootstrap
|   |– _jquery-ui.scss   # jQuery UI
|   …                    # Etc.
|
`– main.scss             # Main Sass file

ITCSS is a new architecture that is just starting to gain attention. This system from Harry Roberts does a great job defining the problem of CSS architecture and proposing a solution that comes directly out of the CSS language. Rather than working around inheritance and specificity, Roberts puts them at the center of his methodology.

ITCSS organizes all your Sass and CSS based on three metrics: reach, specificity, and explicitness—visualized as an inverted triangle, as shown in Figure 9.2:

Figure 9.2. ITCSS’s inverted triangle

Code should be organized from least to most explicit, starting with general catch-all rules (such as a reset) and moving up to more explicit styles (such as .contact-form). Similarly, code is organized from broadest to narrowest reach—so that styles affecting more HTML come early in the code, and styles with a more localized application come later. Finally, code is organized from lowest to highest specificity, so that later code can always override earlier code.

With those metrics in mind, the triangle is broken down into seven layers. Each layer is more specific, explicit, and narrow-reaching than the layer before it, as shown in Figure 9.3:

Figure 9.3. ITCSS’s layers

Let’s explore what these layers are in detail. Settings contains global Sass configuration that can be accessed anywhere in the project, such as font sizes, colors, and other project configuration. Tools are global functions and mixins that are helpful across the project and not specific to one component. Generic is the first layer with CSS output of its own, which includes browser resets or normalization, global box-sizing, and any other broad-scoped rules. The elements layer provides default styles for bare HTML elements such as links and paragraphs. It’s similar to the generic layer, except that it provides a more opinionated style.

ITCSS objects are similar to OOCSS objects, and are defined in class-based selectors. They define reusable patterns that have a consistent structure no matter what content or cosmetic style is applied, just like the OOCSS media object does. Components are recognizable pieces of an interface, such as a contact form or a product listing. After the initial setup, this is where the majority of a project’s feature-building work takes place. Finally, trump styles can be used to override any other layer. Trumps should be used sparingly, and have as narrow a scope as possible.

All these layers can be organized into groups of partials. Roberts uses a multilevel file-naming convention (layer-name.partial-name.scss), but we’d recommend using folders instead. The results could look like this:

@import “settings/global”;
@import “settings/colors”;

@import “tools/functions”;
@import “tools/mixins”;

@import “generic/box-sizing”;
@import “generic/normalize”;

@import “elements/headings”;
@import “elements/links”;

@import “objects/wrappers”;
@import “objects/grid”;

@import “components/site-nav”;
@import “components/buttons”;
@import “components/carousel”;

@import “trumps/clearfix”;
@import “trumps/utilities”;
@import “trumps/ie8”;

All that is well and good, but I’m writing this chapter and I think my own architecture is way cooler than anything else we’ve discussed. I’m yet to give it a name, but I will as soon as I decide to tour the universe giving workshops to all my adoring fans. A girl can dream, right?

To tell you the truth, I love parts of all these systems—especially ITCSS. I take what works for my team, and make adjustments as needed from one project to the next. For me, it all starts with one rule: follow the cascade. In practice it looks a lot like ITCSS or Atomic Design (though I find the latter’s biochemical metaphor confusing). I use the same metrics, but break down the categories in slightly different ways.

I start with Sass config files that have no output but define all the parameters of a design: colors, fonts, sizes, media-queries, z-indexes, and so on. In my case, it’s almost entirely Sass map variables accessed with a powerful set of functions and mixins I take from project to project: OddBird’s Accoutrement toolkits. Chris Sauvé refers to this approach as a “Sass Central Nervous System”—a consistent system for maintaining and accessing abstract meta-patterns and style guidelines. Ours look something like this:

// Accoutrement Config
// -------------------

$colors: (
  // base color palette
  'brand-blue': hsl(195, 100%, 43%),
  'brand-red': hsl(0, 100%, 50%),
  'brand-pink': hsl(330, 100%, 45%),

  // color style guide
  'background': hsl(0, 0%, 100%),
  'text': 'brand-blue' ('shade': 80%),
  'action': 'brand-pink',
  'focus': 'brand-blue',
);

$sizes: (
  // base font size
  'body-text': 22px,

  // type sizes
  'rhythm': 'body-text' ('minor-third': 2),
  'h1': 'body-text' ('minor-third': 3),
  'h2': 'body-text' ('minor-third': 2),
  'h3': 'body-text' ('minor-third': 1),

  // other
  'corners': 3px,
  'page': 30rem,
);

$fonts: (
  // hosted web font
  'body': (
    'name': 'CenturyOldStyle',
    'stack': ('Baskerville', 'Palatino', 'Cambria', 'Georgia',
↵ 'serif'),
    'regular': 'CenturyOldStyle-regular', // webfont file names...
    'italic': 'CenturyOldStyle-italic',
    'bold': 'CenturyOldStyle-bold',
  ),

  // web-safe font stack
  'code': (
    'name': 'Consolas',
    'stack': ('Menlo', 'Monaco', 'Lucida Console', 'Liberation Mono'
↵, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Courier New', 
↵'monospace', 'serif')
  ),
);

The toolkit layer is prebuilt, and moves with us from project to project. It includes functions and mixins that put our configuration to work: automating @font-face imports, font-stacks, and typographical rhythms, as well as applying our color palette. It also helps with accessible color contrasts, and automatically generates a visual style guide, so we can see the fonts, colors, and sizes in action.

The next level up is what I call initial styles—resets, web font imports, global defaults, and so on. This is the first layer of code with actual CSS output, and it’s a thin layer. At this point we’re not styling any real patterns, just trying to establish a slightly more beautiful and branded version of the browser defaults.

From there I often establish the site layout, adding patterns as needed. The layout partials are similar to Hugo’s, describing all the primary structures of the site. Patterns are design objects, similar to objects in OOCSS and ITCSS. They’re not related to specific content, and might be used anywhere, for anything. For example, buttons and form elements are always some of my first design patterns on a project.

Patterns are abstract, and have no real meaning until they’re used in a component—the actual bits of user interface that appear on a site. Components should follow all the rules described earlier in the chapter: reusable, repeatable, and able to fit in any container. What others systems call page and theme styles are usually defined either as layout templates or components that just happen to be full screen. Any vendor code that I use will come through a packaging system such as npm, and live outside my visible Sass directory:

sass/
|
|– config/
|   |– _colors.scss      # Color palettes
|   |– _fonts.scss       # Font palettes
|   …                    # Etc.
|
|– initial/
|   |– _init.scss        # reset/normalization
|   |– _root.scss        # global defaults (mostly :root, html, body)
|   |– _webfonts.scss    # @font-face imports
|   …                    # Etc.
|
|– layout/
|   |– _navigation.scss  # Navigation
|   |– _banner.scss      # Site Banner
|   …                    # Etc.
|
|– patterns/
|   |– _buttons.scss     # Buttons
|   |– _dropdown.scss    # Dropdown
|   …                    # Etc.
|
|– components/
|   |– _calendar.scss    # Calendar widget styles
|   |– _contact.scss     # Contact form styles
|   …                    # Etc.
|
|- main.scss             # The primary Sass file to be compiled

Lately, I’ve also included a styleguide folder, and an extra styleguide.scss root Sass file to be compiled separately. These files contain any styleguide-specific components not required by the main app—styles for the color palette, font specimens, and so on.

With the current Sass import system, variables, mixins, and functions live in a global namespace across all files; conflicts are common. It’s impossible to tell by looking at a single Sass file what already exists in that global space; however, with modular imports, nothing is made global unless I explicitly request it. The @use directive will be visible at the top of any importing file, giving me a complete list of available APIs and the power to namespace each however I see fit.

If you @use 'example/grids' as 'grid' at the top of a file, and the example/grids.scss file contains a span() mixin and a gutter() function, then they become available in your file as grid.span() and grid.gutter() (the . syntax is still under discussion). The same will be possible with variables, so a $columns variable would be available to as $grid.columns.

// example/grids.scss
@mixin span(…) { … }
@function gutter(…) { … }
$columns: 12;

// my-file.scss
@use 'example/grids' as 'grid';

.column {
  @include grid.span(5 of $grid.columns);
  margin-bottom: grid.gutter();
}

Sass will default to using the filename as a prefix if none is provided, and also allow you to remove the prefix when you need to. It’s still not clear if prefixing will work with placeholder selectors.

In addition to using a file with or without a given prefix, it might be possible to use an entire file as a mixin, so you can apply the code of that file anywhere you want—even in a nested context. The syntax is still under consideration, but it would make the entire CSS contents (that are not wrapped in a mixin) available to you as a single mixin.

Modular imports will also give developers—especially library authors—more power over their public API. Currently, when you load a Sass library such as Susy, you gain access to pages and pages of undocumented functions that you’ll never use. I’ve done my best to hide those functions behind long names like _susy-valid-column-math, but they still clutter the global namespace unnecessarily. With encapsulation, you’ll have control over which mixins, functions, variables, and (possibly) placeholders should be made public. Adding - or _ to the start of a name will define it as private.

There is also talk of a @forward directive that would allow authors to pass the API from one module along as part of another. If you wanted to build a Susy flexbox extension, for example, you could tell your extension to forward the Susy API along to your users.

All of this, of course, is still in the works, and likely to change before it becomes available later in the year. I can’t wait to see how it turns out—in what ways it changes Sass architecture, and helps the Sass ecosystem.