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.
Installing the Style Guide gem
The style-guide Rails engine mounts onto your Rails application at /style-guide by default and renders files out of subdirectories underneath app/views/style-guide.
style-guide also ships with a bunch of Twitter Bootstrap elements by default, which can easily be hidden.
Add the following line to your Gemfile:
gem "style-guide"Use Bundler to install it:
$ bundle installUse the Rails generator to set up your project the rest of the way:
$ rails generator style_guide:installStart Rails and Guard (in their own terminals of course):
$ rails server
$ bundle exec guardYou’re ready to visit Style Guide in its new home, most likely at http://localhost:3000/style-guide.
Stay tuned for part 2: Using Style Guide in your Workflow.
About the Author
