Upgrading to Susy 0.9

Eric Meyer released Susy 0.9 yesterday. For those who don't know, Susy is a plugin for the Compass CSS framework that facilitates the implementation (and maintenance) of grid-based designs. (You're using grid-based designs, right? Right?)

The subtext in version 0.9 of Susy seems to be making the plugin much more lightweight and focussed. In version 0.8, Susy offered a slew of default styles, utilities, and conventions that have been dropped completely in 0.9. Now, the plugin focusses exclusively on the grid aspect and thus sheds a lot of weight.

Major changes like this, naturally, come at a price. While new projects will have their own challenges now that there's no nice baseline to start from (which has its own issues), I'd like to focus on upgrading a Susy 0.8 project to 0.9 while keeping most of the old defaults intact.

Preparations

Susy 0.9 requires Compass 0.11.1 per definition. One thing you may want to do apart from adjusting your version dependency in your project's Gemfile is to remove the old initializer that was required in previous versions of Compass, usually stored in config/initializers/compass.rb. Compass has a Railtie now and thus initializes itself magically without your help.

The resulting entries in your Gemfile should now be:

gem 'compass', '0.11.1'
gem 'compass-susy-plugin', '0.9'

After a regular run of bundle update compass compass-susy-plugin you should be good to go. However, the Sass templates of your application will need adjusting from version 0.8 of Susy.

Updating your templates

Disclaimer: I'm using the Sass variant of the templates as opposed to the SCSS variant, but the changes are near identical. Adjust accordingly if you're using SCSS. All of the templates should be stored in app/stylesheets/ in your Rails application.

_base.sass

Here, just the import of susy/susy needs adjustments. It has been simplified to just susy:

@import susy/susy

_defaults.sass

This template is no longer included in new apps generated with Susy 0.9. However, you can still make use of your existing copy with a few adjustments.

First of all, Susy used to ship with its (her?) own reset style. This has now been folded into Compass' version and as such your template needs to include it instead of susy/reset:

@import compass/reset

Additionally, Susy also shed most of the typographic calculations and other utilities that _defaults.sass was based upon. The heavy-lifting, however, has also been added to Compass itself as the "vertical rhythm" module. To use it, add the following lines near the top (but after the @import base line) of _defaults.sass:

@import compass/typography/vertical_rhythm
+establish_baseline

More documentation about the (very powerful) functionality provided by this module can be found at compass-style.org.

screen.sass

This is the actual template you're including in the <head> of your website template. It only needs one minor adjustment to adjust for the fact that there no longer is a susy mix-in. So remove the following line:

+susy mixin

And that's it!

A word on Haml/Sass 3.1 and kaminari

I've switched to Haml/Sass version 3.1 along with the update to Compass/Susy, which has some amazing new features in store. On a related note, Sass will also be included in Rails 3.1 along with jQuery (and CoffeeScript).

However, if you're using Akira Matsuda's excellent pagination plugin kaminari, please be aware that there is currently an unresolved issue with Haml 3.1 that I believe is only related to Ruby 1.8 installs. I'm running kaminari 0.12.1 and Haml 3.1.1 on this very blog without issues, but I have seen problems on Ruby 1.8 installs.

Update: kaminari 0.12.3 fixes the issue.