SCSS, Indented Syntax & Comments

Sass has two ways of writing the same language. SCSS looks like CSS with braces and semicolons. The indented syntax drops the braces and semicolons and uses indentation instead, a bit like Python. Both compile to exactly the same CSS.

In this lesson you will compare the two syntaxes, learn why almost every project today uses SCSS, and learn the three kinds of comments Sass understands, including which ones end up in the CSS that visitors download.

SCSS: CSS with superpowers

SCSS stands for Sassy CSS. Files end in .scss. The most important fact about SCSS is that every valid CSS file is also a valid SCSS file. You can rename style.css to style.scss, compile it, and get the same CSS back. Then you can add Sass features one at a time.

Run this example. It is plain CSS with no Sass features at all, and Sass accepts it happily:

.notice {
  padding: 1rem;
  border-left: 4px solid #0e7490;
  background: oklch(96% 0.02 220);
}

.notice:hover {
  background: oklch(92% 0.04 220);
}

@media (width >= 40rem) {
  .notice { padding: 1.5rem 2rem; }
}

.notice {
  padding: 1rem;
  border-left: 4px solid #0e7490;
  background: oklch(96% 0.02 220deg);
}

.notice:hover {
  background: oklch(92% 0.04 220deg);
}

@media (width >= 40rem) {
  .notice {
    padding: 1.5rem 2rem;
  }
}

Sass understands modern CSS such as oklch() colours and range media queries (width >= 40rem) and passes them through. Notice one small change: Sass reformatted the short rule inside @media onto several lines. The default output style, called expanded, puts every declaration on its own line.

The indented syntax

The indented syntax is the original Sass syntax, and its files end in .sass. Instead of braces, indentation shows which rules sit inside which. Instead of semicolons, each declaration ends at the end of its line. It also has two shortcuts: = defines a mixin and + includes one.

Here is a small stylesheet for a Kochi travel agency written in the indented syntax. The editor on this site compiles SCSS only, so this one is shown with the CSS that Dart Sass produced for it:

$sea: #0e7490

=soft-shadow($size: 8px)
  box-shadow: 0 2px $size rgb(0 0 0 / 0.15)

// a silent comment
.site-header
  background: $sea
  color: white

  a
    color: #fde68a

    &:hover
      text-decoration: underline

.ticket
  +soft-shadow(12px)

.site-header {
  background: #0e7490;
  color: white;
}
.site-header a {
  color: #fde68a;
}
.site-header a:hover {
  text-decoration: underline;
}

.ticket {
  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.15);
}

The same stylesheet in SCSS looks like this. Compare the two line by line:

$sea: #0e7490;

@mixin soft-shadow($size: 8px) {
  box-shadow: 0 2px $size rgb(0 0 0 / 0.15);
}

// a silent comment
.site-header {
  background: $sea;
  color: white;

  a {
    color: #fde68a;

    &:hover {
      text-decoration: underline;
    }
  }
}

.ticket {
  @include soft-shadow(12px);
}

.site-header {
  background: #0e7490;
  color: white;
}
.site-header a {
  color: #fde68a;
}
.site-header a:hover {
  text-decoration: underline;
}

.ticket {
  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.15);
}

The output is identical. Also notice that Sass changed rgb(0 0 0 / 0.15) into rgba(0, 0, 0, 0.15): when a colour is written with the classic rgb(), hsl() or hwb() functions, Sass works it out and writes it back in the form that the widest range of browsers accept.

Which syntax should you use?

Use SCSS. It is what you will meet in jobs, frameworks and documentation, and any CSS snippet you copy from your own notes works in it straight away. Learn to read the indented syntax so an old .sass file does not surprise you.

The compiler chooses the syntax from the file extension: .scss is SCSS, .sass is indented and .css is plain CSS. A project may mix them: an SCSS file can load a .sass partial and the other way round.

Comments in Sass

Sass has three kinds of comments, and the difference matters because one kind is shipped to every visitor and the others are not.

• Silent comments start with // and run to the end of the line. Sass removes them. Use them for notes to your team.
• Loud comments are CSS comments, /* ... */. Sass keeps them in the expanded output, but the compressed output style used for production removes them.
• Preserved comments start with /*!. Sass keeps them even in compressed output. Use them for licence or version notices.

There is also a fourth style, documentation comments, which start with ///. Sass treats them as silent, but documentation tools such as SassDoc read them to build reference pages for your mixins and functions.

$version: "2.4";
/*! Kochi Travels theme v#{$version} */

// Brand colours: only the team sees this note
$sea: #0e7490;

/* Header styles */
.site-header {
  background: $sea; // dark teal
  color: white; /* text on teal */
}

/// Adds a soft shadow.
/// @param {Length} $size - blur size
@mixin soft-shadow($size: 8px) {
  box-shadow: 0 2px $size rgb(0 0 0 / 0.15);
}

.ticket { @include soft-shadow; }

/*! Kochi Travels theme v2.4 */
/* Header styles */
.site-header {
  background: #0e7490;
  color: white; /* text on teal */
}

.ticket {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
}

The silent // comments and the /// documentation have gone. The two loud comments stayed, and #{$version} inside the preserved comment was replaced by its value, which is handy for stamping a version number into the file. Compiled with --style=compressed (see Compiling & Watch Mode), the same file becomes one line, and only the /*! comment survives:

/*! Kochi Travels theme v2.4 */.site-header{background:#0e7490;color:#fff}.ticket{box-shadow:0 2px 8px rgba(0,0,0,.15)}

The compressed style also shortened white to #fff and 0.15 to .15, because they mean the same thing in fewer characters.

Common mistakes

• Using // comments in a plain .css file. // is a Sass feature. In real CSS it is not a comment and breaks the next rule.
• Putting secrets or rude notes in /* */ comments. Loud comments can reach the published file. Use // for internal notes.
• Mixing tabs and spaces in a .sass file. The indented syntax needs consistent indentation, or compiling fails.
• Expecting a semicolon in the indented syntax. Semicolons after declarations are an error in .sass files.

Key points

• Sass has two syntaxes that compile to the same CSS: SCSS (.scss, braces and semicolons) and the indented syntax (.sass, indentation).
• Every valid CSS file is valid SCSS, which is why SCSS is the standard choice.
• The compiler picks the syntax from the file extension, and a project can mix both.
• // comments are silent and never reach the CSS; /* */ comments stay in expanded output; /*! */ comments stay even when compressed.
• /// documentation comments are silent but can be read by documentation tools.

$sand: #d6a65a
.product
  border: 2px solid $sand
  h2
    color: $sand

/*! Jaipur Handicrafts */
// Sandstone colour taken from the logo
$sand: #d6a65a;

.product {
  border: 2px solid $sand;

  h2 {
    color: $sand;
  }
}