It's highly recommended for designers to maintain a living styleguide and make iterations there than doing a tedious task of doing it in Photoshop or Sketch then passing them to your developer.

Your styleguide can contain everything from Brand Identity to UI components and scenarios. Ruby on Rails is often used in big applications composed of big teams, styleguides can be used to write maintainable and legible code. It serves as a code style and practice on how the team can write their code with consistency and focus on the more important parts for the project instead of refactoring or writing duplicates of an existing UI component.

Using styledown-rails by Rico Sta. Cruz , we can document our CSS files with inline comments, and styledown will generate the view for you.

Styleguides for Lawadvisor , showing it's iconography

Getting Started

Step 1

Install the styledown gem on your Gemfile then run bundle install

# Gemfile
gem 'styledown'

Step 2

Add the route to your styleguide in your routes.rb

# routes.rb
get 'styleguides' => 'styleguides#index'

Step 3

Create your styleguide layout: styleguides.haml

!!!
%html
  %head
    = stylesheet_link_tag    'https://cdn.rawgit.com/styledown/styledown/v1.0.1/data/styledown.css'
    = javascript_include_tag 'https://cdn.rawgit.com/styledown/styledown/v1.0.1/data/styledown.js'
  %body.landing-page
    = yield

Step 4

Create a controller for your styleguide: styleguides_controller.rb

Load your layout and on the stylesheets action, load the CSS directory that you need.

class StyleguidesController < ActionController::Base
  layout 'styleguides'

  def index
    @html = cache(mtime) { Styledown.parse(stylesheets) }
  end

private

  def mtime
    stylesheets.map { |file| File.mtime(file) }.max
  end

  def stylesheets
    Dir[css_path("components/*.scss")].sort
  end

  def css_path(*a)
    Rails.root.join 'app/assets/stylesheets', *a
  end
end

Step 5

Create your styleguide views: views/styleguides/index.haml

.styleguide-heading
  .container
    .logo
      =image_tag("logo-colored.svg")
    %h1 Styleguides

.styleguide-content
  .container
    !~ @html

Step 6: Documenting

You can document your stylesheet with inline comments. For example, you have a component assets/stylesheets/components/component-name.scss

You will be writing a Markdown block within the comment. It can be written as Jade or HTML

The first line of the block is your component name, which should end in :

/**
* Component Name:
* `.component-name` - tell us how to use this component.
*
*     @example
*     div.component-name
*       h3.name Sample code
*       p.excerpt goes here
*/

.component-name {
  background: #fff;
  ...
}

Further reading

Writing styleguides is better if it isn't messed up and terrible to read. For my personal projects or even at Proudcloud, it is recommended to use Reasonable System for CSS Stylesheet Structure as a guide in writing maintainable CSS.

Other Examples

Typography Styleguides for GoodMealHunting
Buttons and Dish Card component styleguides for GoodMealHunting
Buttons styleguides for LawAdvisor