Smurfville is the home of SMURF: Scalable, Modular, re*Usable **Rails **F*rontends

SMURF is a new and modular approach to Rails frontend development based on the SMACSS approach for CSS. It is mainly comprised of 2 parts:

  1. SMURF Philosopy describing a modular approach an establishing coding conventions
  2. Smurfville Gem aid in following the SMURF conventions by rendering a nice "living styleguide"

SMURF presentation from ArrrrCamp 2012


Build Status

SMURF Philosophy

The name and the philosophy of SMURF are heavily influenced by the SMACSS approach by Jonathan Snook (@snookca) which stands for Scalable Modular Architecture for CSS.

These are the main goals behind SMURF:

Goal 1: Conventions

Analogous to what SMACSS does for modular CSS we want to establish conventions for naming, structure, and filenames of all modular frontend code. There should be a specific partial, helper or similar for each frontend module and it should be immediately clear how it needs to be named and where the files should be put.

This goal is achieved when it is completely clear where all the necessary parts of a frontend module are located.

Goal 2: Living Styleguide

Based on the conventions from Goal 1 we are creating tools that parse our Rails projects and render anything that makes sense into a living styleguide. This would include an overview of all the modules with their different submodules and states and hopefully also some JS interactions. The two goals behind this would be a) to have a tool for something like "visual unit testing" and b) to have a communication device for any kind of design work within a project.

As a first step, our SMURF gem can already render a living styleguide of all the color variables in your Sass code.

An example for a similar tool could be kss-rails

There is also a 3rd goal about in-browser module development, but that is still some way ahead in the future.

Smurfville Gem


The gem is currently able to parse your Sass files and display all the used color variables (e.g. $primary-color) in a nice styleguide.

Future goals include extracting typography information and rendering SMURF modules.


  • Rails >3.1
  • Sass
  • Haml
  • Color gem


Add this to your Gemfile, run bundle install:

gem 'smurfville'

Add an initializer to your Rails project in which you tell Smurfville where it can find your Sass files:

# config/initializers/smurfville.rb

if defined?(Smurfville)
  Smurfville.sass_directory = Rails.root.join('app', 'assets', 'stylesheets').to_s

Mount the Smurfville::Engine in your routes:

# config/routes.rb

if defined?(Smurfville)
  mount Smurfville::Engine => "/smurfville"

Restart your server and you should be able to access the SMURF pages, e.g.


Here is a screenshot of how a very simple living color styleguide will look like:

Smurfville screenshot

Bitdeli Badge