Upgrade from 1 to 2

As you many have notices, Skeleton Sass 2 differs greatly from Skeleton Sass 1. Among the changes include removal of Compass, Bourbon, and vanilla Sass versions of Skeleton Sass, mandatory dependency on Sass 3.3 and above, introduction of themes, introduction of updating, and many more features/fixes.

Requirements

Skeleton Sass 2 has only a single requirements to run: Sass 3.3 and above. We use functions that are only available in Sass 3.3+ so using legacy version of Sass won't work.

Note: Compass currently does not have a stable release that supports Sass 3.3 and above. Using Compass 0.12.x is NOT supported and WILL cause issues. Do not use Compass 0.12.x. If you wish to download the alpha/beta builds of Compass 1, you may do so. This project does not officially support Compass 1 yet.

The Upgrade

Upgrading to Skeleton Sass 2 requires a little effort from you. Unfortunately, this process cannot be automated completely.

1. Make a copy of Skeleton Sass 1 to a safe location. We don't want your hard work unintentionally removed or altered
2. Download Skeleton Sass 2 and place it in a separate directory
3. Open _vars.scss in your Skeleton Sass 1 installation and open the _MYconfig.scss file in Skeleton Sass 2. Copy the contents of _vars.scss into _MYconfig.scss.
4. In Skeleton Sass 2 rename _MYconfig.scss to the name of your project (e.g. _atomicpages_config.scss) and append a new import statement to the end of skeleton/core/_config.scss (e.g. @import "../../_atomicpages_config.scss").
   • Note: if you're running a Mac, Linux, Unix, or Windows with cygwin, you can optionally run bin/setup.sh which does the above steps for you.

Note: If you wish to see the new options for Skeleton Sass 2, scroll to the bottom of this document to see the differences.

Now that we have our configuration state updated, we need to migrate all changes to the grid, base styles, and layout files from Skeleton Sass 1. Let's begin with migrating changes from the layout file:

Migrating layout.scss

Since layout.scss was removed in Skeleton Sass 2, we can place all those changes in skeleton_template.scss (located in the root directory of Skeleton Sass 2).

1. Copy and paste the contents of layout.scss at the end of skeleton_template.scss.
2. Rename skeleton_template.scss to skeleton.scss

Migrating base.scss

Before we are able to migrate base.scss a few questions need to be asked:

1. Has base.scss been changed?
2. Has base.scss been changed with Compass functions/mixins?
3. Has base.scss been changed with third party functions/mixins?

If all of the above questions are no then you don't need to do anything and may skip to the next section.

If you answer yes to any of these, then continue to the sub-sections.

For all changes

Again, we need to identify what exactly has been changed. Since we don't want to tamper with the structural elements of _base.scss in Skeleton Sass 2, this is important to identify.

In either case, we need to setup a new theme so we don't have our hard work overridden when we update Skeleton Sass 2. Follow the guide to create a new theme here or run bin/theme_setup.rb in your console window.

Windows users can double-click on the ruby executable if ruby is installed on your system Unix/OS X/Linux users may have to navigate to the file in terminal depending how your path is set up.

Once we have our shiny new theme created, let's begin by opening skeleton/themes/[theme]/_base.scss (replacing [theme] with your theme name) in Skeleton Sass 2 and opening base.scss in Skeleton Sass 1 in your favorite text editor or diff the files.

Font sizes, line heights, and heading margins

If you have changed any of the font-sizes:

font-size: round($fontSize * 3.8333);
line-height: round($fontSize * 4.1666);
margin-bottom: round($fontSize * 1.1666);

you should change the number that the variable is multiplied by or by adjusting the value stored in the variable.

@include font-size($font-size * 2.8333); // adjusted multiplier
line-height: relative($font-size * 3.1666); // adjusted multiplier
margin-bottom: relative($font-size * 1.3333); // adjusted multiplier

New selectors & styles

If you have any custom selectors that don't exist in Skeleton Sass 2, append them to the _base.scss partial and continue on!

Links & anchors

Any changes to variables should be values that are overridden in your global configuration file located in the root of Skeleton Sass 2. For example:

// Editing _atomicpages.config.scss
$link-color: #ccc;
$link-hover: darken($link-color, 5%);

Refrain from changing the default values in skeleton/core/_config.scss since your changes will be overridden if you update Skeleton Sass 2.

Custom mixins & functions

Not a problem!

1. Under the marrow folder located in skeleton/themes/[theme] (replacing [theme] with the name of your theme)
2. Create a new file (e.g. _MYmixins.scss) and copy your custom mixins and/or functions in the newly created file(s)
3. Open _vars.scss located in skeleton/themes/[theme] (replacing [theme] with the name of your theme) and import your newly created file(s) in _vars.scss before the variables you see in that file

Changes with Compass

If you changed anything using Compass functions/mixins then all of those changes will need to be removed or you may install the latest alpha/beta builds of Compass 1 that supports Sass 3.3. View the built-in functions/mixins to see what is supported out of the box.

Changed with third party mixins/functions

If these functions/mixins support Sass 3.3 (meaning they won't break if you use Sass 3.3) then migrate all changes under the marrow folder located in skeleton/themes/[theme] (replacing [theme] with the name of your theme).

Migrating skeleton.scss

If you've made any edits to skeleton.scss (the grid) then we have to ask ourselves two questions:

1. Are the edits minor (i.e. fixes)?
2. Are the edits major?

Minor edits

If you found a few bugs in the version of Skeleton Sass 1, there's a good chance they were fixed in Skeleton Sass 2. We recommending diffing skeleton.scss in Skeleton Sass 1 and _skeleton.scss located in skeleton/themes/[theme] (replacing [theme] with the name of your theme) in Skeleton Sass 2.

If you find a bug that still exists in Skeleton Sass 2, please submit a pull request with the patch.

Major edits

Major edits are not an issue. You can replace the grid entirely if you wish. Simply replace the contents of your modified grid with the contents in _skeleton.scss located in skeleton/themes/[theme] (replacing [theme] with the name of your theme) in Skeleton Sass 2.

Note: be sure to copy all functions/mixins required to make your grid work. If you made changes to any core mixins/functions please do not alter the framework mixins/functions. Instead add your custom code to the marrow folder in your theme root and import those mixins/functions in _vars.scss located in your theme root.