Gemifying your style guide to DRY your CSS

At Ombu Labs we like to follow a style guide to drive our own products. A style guide is a document that provides guidelines for the way your brand should be presented from both a graphic and language perspective. You can see Fast Ruby's style guide at this link.

Since we have a few applications in place and it's important to make sure that they all use the same style, we need to ensure that they will all inherit the same CSS files. One way to do this is to copy the above style guide and paste it inside all of our apps, but this would end up causing a lot of duplicated code. If we decided to change the font-style, for example, we would need to change it in all apps individually.

Something else we are super fans of at Ombu Labs is to follow good code and development practices. One of our favorites is the DRY (Don’t Repeat Yourself) principle, which states that duplication in logic should be eliminated via abstraction. So to avoid the duplicated code here, we decided to create a gem to encapsulate our style guide and to be bundled in all of our products.

In this article, I'll show you how we did it!

Creating the Gem

The first step is to create the gem. Bundler has a command to create the skeleton of the Gem.

bundle gem fastruby-styleguide

Go to the created .gemspec file and add the info about the new gem and also a few dependencies:

# fastruby-styleguide.gemspec
require_relative 'fastruby/styleguide/version'

Gem::Specification.new do |spec|
  spec.name           = 'fastruby-styleguide'
  spec.version        = Styleguide.gem_version
  spec.authors        = ['OmbuLabs']
  spec.email          = ['hello@ombulabs.com']

  spec.summary        = 'Style Guide for all Fast Ruby products'
  spec.homepage       = 'https://github.com/fastruby/styleguide'

  # Rails
  spec.add_dependency 'rails', '>= 5.2.1'
  spec.add_dependency 'sass-rails', '>= 5.0'
  # Jquery
  spec.add_dependency 'jquery-rails', '>= 4.3.0'
  # Bootstrap
  spec.add_dependency 'bootstrap-sass', '>= 3.4.0'
  # Popper
  spec.add_dependency 'popper_js', '>= 1.14.5'
  spec.add_dependency 'material_design_lite-sass', '>= 1.3.0'
end

By default the gem is created as a module but we need to turn it into an engine, because we need to be able to integrate the gem code into any Rails application. In case you want to understand more about the Rails engine, check this link.

So, let's change the lib/fastruby-styleguide.rb

module Fastruby
  module Styleguide
    class Engine < ::Rails::Engine
    end
  end
end

Now we need to copy all the assets for the vendor/assets folder. The project structure will be like this:

Folder structure

Go back to the .gemspec file and make sure that the new files will be loaded adding the following line:

spec.files = Dir['vendor/**/*']

And this is it! The gem is ready to be used.

Adding the gem to a project

To use our new created gem we need to bundle it like any other gem. So add this line to your application's Gemfile:

gem 'fastruby-styleguide'

And then execute:

$ bundle install

The next step is to require the new gem assets into the application:

If using SASS, in application.scss, add:

@import "fastruby/styleguide";

And in application.js add:

//= require fastruby/styleguide

Now start the application and the gem assets should be available to use.

You can see our style guide code in this GitHub repository: https://github.com/fastruby/styleguide.

Conclusion

As developers, we are always thinking about the best way to organize our code and follow good practices, so here is our solution to share the same assets code amongst our several products. If you're facing the same issue, I hope that this is useful.

Extra

Want to see our style guide applied? We're proud to present our projects: Fastruby.io and Audit Tool.

Get the book