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
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.
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
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!