Featured » Blog » Using the Style Guide gem

Using the Style Guide gem

January 21, 2013 Doc Ritezel

Much like any good Rails engine, using Style Guide is designed to give you as much flexibility as possible. In its default state, Style Guide renders subdirectories full of partials located under app/views/style-guide.

You might be wondering what to do next. Let’s walk through iterating on a partial.

Setting Up the Partial

$ mkdir -p app/views/style-guide/branding
$ mkdir -p app/assets/stylesheets/branding

Now we’ve got a place for our partials and stylesheets to live. Let’s make a partial for the company’s name:

# app/views/style-guide/branding/_headers.html
<h1 class="brand-name">The Company You Trust</h1>

Now we can style them using some SCSS. I heard you like hot pink:

# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #f0f;
  background-color: black;
  font-weight: 900;
}

Fantastic! It’s like the mid-90s in here.

Iteration in the Style Guide

At this point, Style Guide is ready for iterating until the header is properly-styled. Let’s change the colors around as a stand-in for your actual tweaking process.

# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #0096D6;
  font-weight: 900;
}

Compared to turning on all the pink pixels in your computer’s screen, that blue is a lot nicer to look at.

Laying Out Partials

A quick note for the sharp-witted: resist the temptation to do full-page layouts inside of Style Guide. Not only does putting layout inside Style Guide pollute the visual elements being styled, it complicates any future refactoring or extraction you might do. Layout nomenclature, an extremely complex issue, is best decided per project.

Let’s say we want to put both headers on the landing page, which will in this case be the “index” action of our “home” controller.

# app/views/home/index.html
<h1>Brand Name Company</h1>

Let’s say we’re very clever and put the controller and action name onto the body as CSS classes.

# app/views/layouts/application.html.erb
...
<body class="<%= controller.controller_name %> <%= controller.action_name %>">
...

We’re going to do something very clever with SASS in <code class="app/assets/stylesheets/home.css.scss 

"> that will make your head spin:


# app/assets/stylesheets/home.css.scss
.home.index {
  h1 {
    @extend .brand-header;
  }
}



This uses @extend to reduce CSS duplication.  All of a sudden, the rules in .brand-name that we styled are applied to .home.index h1.  Here's what the compiled version of headers.css.scss will look like:


.brand-name,
.home.index h1 {
  color: #0096D6;
  font-weight: 900;
}



Superficially, @extend lets us see all the places where the .brand-name class is applied.  Structurally, and more importantly, @extend separates the implementation of a widget's styling from its layout.


We could have gotten the same structural result with include, but that would have resulted in code duplication.  Likewise, we could have put .brand-name onto the <h1>, but that would be a stronger coupling.


Multiple States for Partials


Due to an unfortunate Superbowl ad, we need to change the company name's color when the mouse hovers over it.  Due to how browser's work, we can't fake the :hover selector, so we need to make a CSS class to represent the hovered state.  Let's add that to the branding/headers.html partial.


# app/views/style-guide/branding/_headers.html
<h1 class="brand-name">The Company You Trust</h1>
<h1 class="brand-name brand-name-hover">Trust No One</h1>



Now we need to style this.


# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #0096D6;
  font-weight: 900;
}
.brand-name-hover {
  color: #D9541E;
}



Okay, so now both states are styled.  Let's apply the hover style to that <h1>element to complete the story:


# app/assets/stylesheets/home.css.scss
.home.index {
  h1 {
    @extend .brand-name;
    &:hover {
      @extend .brand-name-hover
    }
  }
}



Wow, now that's some contrast!


Configuring the Style Guide Location


This whole time, we've been putting our files into app/views/style-guide, but this isentirely configurable.  Just pop open your application.rb and change the config.style_guide line.  Let's say you want to put your guide in app/guide instead:


class YourApplication < Rails::Application
  ...
  config.style_guide.paths << Rails.root.join("app", "guide")
  ...
end



Now you're configuring Style Guide like a champ!

About the Author

Biography

Previous
Visualizing the Economic Health of the Nation, One State at a Time
Visualizing the Economic Health of the Nation, One State at a Time

State by State is an ongoing project by Bloomberg's visual data team that offers a comprehensive look at th...

Next
Happy Friday
Happy Friday

Helps Tag successful builds in Travis CI Is there a way to tag commits in git that are successful builds in...

Return to Home