haml--haml/doc-src/SCSS_FOR_SASS_USERS.md

Intro to SCSS for Sass Users

Sass 3 introduces a new syntax known as SCSS which is fully compatible with the syntax of CSS3, while still supporting the full power of Sass. This means that every valid CSS3 stylesheet is a valid SCSS file with the same meaning. In addition, SCSS understands most CSS hacks and vendor-specific syntax, such as IE's old filter syntax.

Since SCSS is a CSS extension, everything that works in CSS works in SCSS. This means that for a Sass user to understand it, they need only understand how the Sass extensions work. Most of these, such as variables, parent references, and directives work the same; the only difference is that SCSS requires semicolons and brackets instead of newlines and indentation. For example, a simple rule in Sass:

#sidebar
  width: 30%
  background-color: #faa

could be converted to SCSS just by adding brackets and semicolons:

#sidebar {
  width: 30%;
  background-color: #faa;
}

In addition, SCSS is completely whitespace-insensitive. That means the above could also be written as:

#sidebar {width: 30%; background-color: #faa}

There are some differences that are slightly more complicated. These are detailed below. Note, though, that SCSS uses all the {file:SASS_CHANGELOG.md#3-0-0-syntax-changes syntax changes in Sass 3}, so make sure you understand those before going forward.

Nested Selectors

To nest selectors, simply define a new ruleset inside an existing ruleset:

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

Of course, white space is insignificant and the last trailing semicolon is optional so you can also do it like this:

#sidebar { a { text-decoration: none } }

Nested Properties

To nest properties, simply create a new property set after an existing property's colon:

#footer {
  border: {
    width: 1px;
    color: #ccc;
    style: solid;
  }
}

This compiles to:

#footer {
  border-width: 1px;
  border-color: #cccccc;
  border-style: solid; }

Mixins

A mixin is declared with the @mixin directive:

@mixin rounded($amount) {
  -moz-border-radius: $amount;
  -webkit-border-radius: $amount;
  border-radius: $amount;
}

A mixin is used with the @include directive:

.box {
  border: 3px solid #777;
  @include rounded(0.5em);
}

This syntax is also available in the indented syntax, although the old = and + syntax still works.

This is rather verbose compared to the = and + characters used in Sass syntax. This is because the SCSS format is designed for CSS compatibility rather than conciseness, and creating new syntax when the CSS directive syntax already exists adds new syntax needlessly and could create incompatibilities with future versions of CSS.

Comments

Like Sass, SCSS supports both comments that are preserved in the CSS output and comments that aren't. However, SCSS's comments are significantly more flexible. It supports standard multiline CSS comments with /* */, which are preserved where possible in the output. These comments can have whatever formatting you like; Sass will do its best to format them nicely.

SCSS also uses // for comments that are thrown away, like Sass. Unlike Sass, though, // comments in SCSS may appear anywhere and last only until the end of the line.

For example:

/* This comment is
 * several lines long.
 * since it uses the CSS comment syntax,
 * it will appear in the CSS output. */
body { color: black; }

// These comments are only one line long each.
// They won't appear in the CSS output,
// since they use the single-line comment syntax.
a { color: green; }

is compiled to:

/* This comment is
 * several lines long.
 * since it uses the CSS comment syntax,
 * it will appear in the CSS output. */
body {
  color: black; }

a {
  color: green; }

@import

The @import directive in SCSS functions just like that in Sass, except that it takes a quoted string to import. For example, this Sass:

@import themes/dark
@import font.sass

would be this SCSS:

@import "themes/dark";
@import "font.sass";