Introducing the Style Guide gem

Your Rails application has a unit test suite in RSpec, a set of request specs using Capybara, and a Jasmine suite for your JavaScript. You may even have Cucumber so that your PM can participate in automated testing definition. According to long-standing traditions in Rails testing, your ass is covered.

You have a CSS-shaped hole in your test coverage. You need a style guide. Today, you can quickly set one up on your Rails application with the style-guide gem.

Poor CSS Hygiene is Technical Debt

Here at Pivotal Labs, we’ve run into this conundrum more than once. In the life of a Rails app, more and more pages get added, supported by more and more CSS, and hacks plug more and more holes in the layout. With every commit, even if your Ruby is good looking, you risk adding technical debt.

According to Nicole Sullivan, massively large sites like Facebook and LinkedIn run into the same issues. At one point, Facebook famously defined its blue color an astonishing 260 times more than it should have been. Not only does CSS get larger and more complex as time goes on, the act of paying down that technical debt usually involves acts of heroism.

In short, maintaining CSS on large projects has become a mostly-joyless cross-browser fiasco, desperately in need of tooling.

Testing the Visual Medium

Over the last few years, Pivotal Labs has sometimes extended the test suite metaphor to the visual elements of a Rails application. In most cases, this is a single page containing the most important visual elements. However, this strategy has existed largely as informal community knowledge.

In unit test suites, the major functions of a block of code are tested against controlled input. When tests written before implementation, loose coupling and decreased complexity are generally the result. Styling elements in a style guide first can have the same benefits.

As well as being a good system design tool, a unit test suite can also be considered a form of documentation. Tests describe the behavior of all the code in a system, often exposing the failure cases and exceptions that can happen during execution. A style guide serves the same purpose for new developers joining a team, efficiently describing all the widgets and states in a site.

As Pivotal Labs grows in size and builds out its design team, the style guide also serves as a communication device between designers and developers. On several projects, the style guide serves as a single point of reference for product owners, developers and designers to talk about their application’s visual elements.

One comment

Doc has been an on-and-off Rubyist since 2006, and served several multilingual tours of duty in the Browser Wars. He's what you might call a regular in the open source world, with recent contributions to the Hadoop, Chef, Backbone and Ruby communities.