Styleguide Rails

You might as well learn it now, because you’ll be using it in 6 months. Styleguide rails is a cool gem that builds a living, breathing styleguide for your site. You can add it to your project really easily (let’s just do it right now):

gem install styleguide_rails

OR edit your Gemfile:

gem 'styleguide_rails'

and then bundle.

Lastly, you install the styleguide into your application:

rails generate styleguide:install

Start rails and navigate to http://localhost:3000/styleguide. There should be a built-in _example_elements.html copied into your new app/views/styleguide/widgets/ directory. This is where your new styleguide widgets live (for more on how to use them, see “Using it” below).

But now let’s talk about why this is a really solidly good idea. The styleguide will get you a bunch of benefits.

You can centralize all your design in one place. One of the tenets of good software design is that you should avoid repeating yourself. When you have the same snippets of code scattered all around your application it just ups the chore-factor of trying to change anything. We all know that the solution to this problem is to collect all that code in one place and give it a name; Lo! the function/subroutine/method is born! Well, the same goes for style. You can put all the code defining a given style in one spot. This is then the Source of Truth for the whole team.

Next is that it lets you show off what things will look like when they’re really used on the site. This is like paint swatches up on a bedroom wall. You can get a sense that, no maybe orange doesn’t work in that room. This is a great way to show a client, or even yourself, what a site will really look like.

Lastly, you get the benefit of “shared vocabulary”. You now can draw a box around that “thingy” on “that one page” and say once and for all that it is a news sidebar and it is on the current events page. Knowing the name of something gives you power over it. You can discuss it at meetings and you can point to it when talking about it.

Using it

You should have a “widget” directory at app/views/styleguide/widgets. Each partial in this directory becomes another widget on the http://yourapp.com/styleguide page. Easy! Let’s add one.

I want a nice, simple box around my images that holds each image’s caption. Here’s the html (in _image_caption.html, in the widget directory):

Next I’ll write some sass to style it (methods for doing this vary a bit but, in a rails app with the asset pipeline, you could create a file at app/assets/stylesheets/widgets/image_caption.css.sass):

figure
  padding: 5px
  display: table

  figcaption
    font-style: italic
    border:
      top: 1px dashed blue
      bottom: 1px dashed blue
    padding:
      top: 2px
      bottom: 2px

Now, reload the styleguide. Here’s what I get:

Pretty easy, huh? I hope you run off and give it a try. Styles can be clean, well-organized, and self-documenting. Go forth and be styled!