emjot/elemental_styleguide

Simple style guide for Rails 5.1+

Elemental Style Guide

Simple style guide for Rails 5.1+, designed to go well with elemental_components. The two together are inspired by the works of Brad Frost and by the thoughts behind Lonely Planet's style guide Rizzo.

Installation

Add this line to your application's Gemfile:

gem "elemental_styleguide"

And then execute:

$ bundle

Run the install generator:

$ bin/rails g elemental_styleguide:install

This will create the following files and directories:

app/
  views/
    layouts/
      styleguide/
        example.html.erb
    styleguide/
      01_home.md

The style guide can be mounted in your routes file with:

mount ElementalStyleguide::Engine => "/styleguide"

You can now access the style guide at http://localhost:3000/styleguide.

Pages

You can create style guide pages simply by adding markdown files to the app/views/styleguide directory. These can be structured by putting them in subdirectories, and sorted by prefixing the file names with a digit.

Check out Brad Frost's Style Guide Guide for style guide inspiration.

Examples

A special markdown syntax, inspired by Catalog, can be used to render examples of any erb code on the style guide page, in the context of your own application:

# Example

```example
<%= "Hello world" %>
```

It is possible to pass options to the example, in order to control the width and height of the wrapping element:

```example
width: 500
height: 200
---
<%= "Hello world" %>
```

Examples need your application's CSS and JS in order to function properly. There is an app/views/layouts/styleguide/example.html.erb layout file that examples are rendered within. This file can be modified in order to add additional tags to the header, like the javascript_pack_tag when using the webpacker gem, or classes and styles to the body tag.

Acknowledgements

This library, together with elemental_components, was inspired by the writings of Brad Frost on atomic design and living style guides, and Rizzo, the Lonely Planet style guide. Other inspirations were:

• Catalog - style guide for React
• Storybook - style guide for React
• React Styleguidist - style guide for React
• Cells - view components for Ruby
• Komponent - view components for Ruby

For a list of real world style guides, check out http://styleguides.io.