Sass Setup

Headstart uses Sass to compile stylesheets, and doesn't force you to use predefined styles or class names. Only a few mixins and functions are included by default, and with them you can make any kind of design come alive in your own way, and with your own styles. Whether you use them or not is entirely up to you. Remember that you can customize the boilerplate to get rid of (almost) everything you don't like.


Folder Structure

Great Sass comes with great responsibility. By separating your styles into named chunks, finding out where a certain style might be getting applied becomes a lot easier. The default setup that you'll find inside of the assets/sass folder, is loosely based on SMACSS and OOCSS.

Note: Files prefixed with an underscore will be excluded from the build process.


Prefixing

With the help of Autoprefixer you will never have to write a single prefix again. Ever! Generator functions are also a thing of the past. Start writing real CSS3.


Base files

_config_global.scss

The global config file imports all mixins and functions to make them available for usage, and contains the following top-level variables:

_config_site.scss

This file defines project specific variables, such as colors, and the default font-stack:

$font-stack: Helvetica Neue, Helvetica, Verdana, Roboto, sans-serif;

This is also a good place to put spacing values and easing functions in variables.

_functions.scss

Handy functions that are also being used by the default mixins:

Note 1: em() should be used with care (due to its inherative nature), and works best for font sizes (use pixels for borders and defined dimensions, rem for all the rest).

Note 2: rem() outputs only rem units, limiting browser support to IE9+. If you need to or want to support older versions, it is advised to use the rem() mixin, rather than the function. More on that further down the page.

_state.scss

A collection of silent classes that make it easy to keep your stylesheets DRY by extending from them:

If you prefer using classes over extending, you can extend a regular class to use it in your HTML, eg.:

.capslock { @extend %is-uppercase; } 

Tip: It is still advised to use <strong></strong> for bold and <em></em> for italic.


Library files

If you plan on using libraries, put them in here, and import them in the _config_global.scss.

A few examples:

Note: These haven't been tested yet. Please file an issue on Github if things break, or even if they work just fine (so I can remove this notice).


Mixins

The default mixins provide core functionalities such as the grid-system, media queries, etc. The Gzipping—enabled by the .htaccess file—will cache and strip out strings with multiple occurences, so file size is never an issue.

_all.scss

Imports all the other mixins. It is imported itself into _config_global.scss.

_baseline.scss

A mixin to make baseline alignment easier to implement. Works great together with the Basehold.it stylesheet.

_grid.scss

The grid module allows you to define auto-collapsing columns:

section {
    /* Make the parent clearfix */
    @extend %is-cf;
}

/*
Mixin:
column(
    $columns, // How many columns to span
    $end: false, // Is it the end of a row
    $break: $default-column-breakpoint, // Where it collapses
    $context: $total-columns // The context
)
*/

aside {
    /* Make it float left and take up 4 out of 12 columns */
    @include column(4);
}
article {
    /* Make it close the row by floating right
       and taking in the remaining 8 columns */
    @include column(8, true);
}

A column starts being a column when the available width is at least the defined $break, which defaults to $default-column-breakpoint or 650px (as defined in the base files).

12 columns
6 columns
6 columns
4 columns
4 columns
4 columns
3 columns
3 columns
3 columns
3 columns
2
2
2
2
2
2
1
1
1
1
1
1
1
1
1
1
1
1

You can also have multiple column settings by wrapping the column includes in media queries (more on those in the next chapter). As long as the defined breakpoint is larger than the column breakpoint, the media-queries will delay it from floating.

div {
    /* Setup a 2 column layout up to 1049px */
    @include media-max(1049px)
    {
        /* Odd columns (1,3,5,...) will float left */
        &:nth-child(odd) { @include column(6); }
        /* Even columns (2,4,6,...) will float right */
        &:nth-child(even) { @include column(6,true); }
        /* First two blocks push down */
        &:nth-child(-n + 2) { @include rem(margin-bottom, 50); }
    }

    /* Set up a 4 column layout */
    /* Starting at 1050px */
    @include media-min(1050px)
    {
        /* All but the last column float left */
        &:not(:last-child) { @include column(3); }
        /* Last column floats right */
        &:last-child { @include column(3,true); }
    }
}

If you want to stray from the $default-column-breakpoint, you can use the $break parameter of the mixin to define a custom one:

/* The default value of 650px will be dropped in favour of 800px */
div { @include column(6, false, 800px); }

_media.scss

Headstart comes with 4 media query mixins that make it a painless process to tie styles to certain dimensions.

/* Up until given value */
@include media-max($value) {
    /* ... */
}

/* Starting from given value */
@include media-min($value) {
    /* ... */
}

/* Between given min and max */
@include media-min-max($valueMin, $valueMax) {
    /* ... */
}

/* On retina screens */
@include highres() {
    /* ... */
}

_rem.scss

Not to be confused with the likewise named function, this mixin outputs rem values with pixel fallbacks for a given property. Great for paddings and margins!

/* For example, using: */

div {
    @include rem(margin-top, 20);
    @include rem(padding, 10, 20, 10, 30);
}

/* Will result in */

div {
    margin-top: 20px;
    margin-top: 1.25rem;
    padding: 10px 20px 10px 30px;
    padding: 0.625rem 1.25rem 0.625rem 1.875rem;
}

_triangle.scss

CSS triangles, we all love them, but setting them up isn't really straightforward. This mixin makes it easier.

/*
Mixin:
triangle(
    $width: 10px,
    $height: 10px,
    $direction: up,
    $color: red
)
*/

.tooltip:before {
    content: '';
    display: block;
    @include triangle(15px, 10px, down, #fff);
    /* ... */
}

Modules

Modules are grouped chunks of styles that are separated to lighten up your main files, and that make finding styles easier in larger projects.

_button.scss

Everything "button" goes in here. The placeholder class %button normalizes some default properties of the most commonly used button-elements, such as <a></a> or <button></button>. This is an example of how %button--stroked class could be defined:

/* For usage in HTML, you can use a regular class,
or extend a regular class from this placeholder */
%button--stroked {
    @extend %button;
    border: 1px solid #000;
}

/* Somewhere in your main styles */
.contact-submit-button {
    @extend %button--stroked;
}

_container.scss

Containers are centered blocks with a maximum width. When the available width is less than their defined maximum, they get padded on both sides. Images inside of these type of blocks are made fluid by default so they scale along. Extend your selectors from the placeholder as following:

/* This could be any class */
.header__container {
    @extend %container;
}

_font.scss

A place to put your @font-face configuration.

_form.scss

All form related styles go in here. Normalizes some default styles for form elements.

_normalize.scss

This is the Normalize.css library. It is imported into main.scss to avoid an extra GET request.

_print.scss

The print module is limited to just a few styles that will improve the "printing experience" of your website, eg. making all the text black, removing background-images and shadows, etc. This file is also imported into the main stylesheet to avoid an extra GET request.

_reporting.scss

This module makes it easy to add reporting paragraphs and lists.

Add a info-block with the class .report--info.

Add a warning-block with the class .report--warning.

Add a success-block with the class .report--success.

_text.scss

Everything text-related is contained in this module:


Vendor files

The vendor folder is where you can put the stylesheets that sometimes come with plugins. SCSS stylesheets support regular CSS as well, so just change the .css extension to .scss and you're ready to start @importing them.


Root files

Main styles

The main.scss file gets included in every page. The styles of, for example, a <header>, <menu> or <footer> are best defined here. If you plan on using modules, this is also the best place to import them.

View specific styles

When working on a large scale project, somes styles will be limited to individual pages. This is when the view-specific files come in handy, as they will lighten up the main stylesheet and thus speed up the individual pages of your website.

The default boilerplate contains an example file for the index page, _view-index.sass. To use it, just remove the leading underscore.

IE<9 styles

If you need to use CSS hacks for older IE browser, you can put them in the _ie.scss file. To use this stylesheet, remove the leading underscore to get it compiled and enable the conditional comments in the header layout:

templates/layout/header.html:

<!--[if lt IE 9]
<link rel="stylesheet" href="assets/css/ie.min.css">
<![endif]-->

Next step: Javascript Setup