Frontend Architecture for Design Systems

Chapter 15. Style Guides

As our stylesheets evolve from a list of declarative statements to a system of variables, functions, and logic, we need to make sure that our documentation system evolves as well. Hologram equips us with everything we need to create a robust system of documentation for our design system. It allows us to annotate our system directly in the Sass or JavaScript files where we are writing our code. The annotation is automatically collected by Hologram and turned into a browsable website with rendered examples, as well as correlating code examples. This means that we aren’t maintaining two separate codebases—the style guide is integrated into the actual design system. It is easy to see if code has been written without sufficient documentation.

On top of system documentation, Hologram allows us to create standard Markdown files that will be browsable within our style guide. These give us a great place to write onboarding docs, project rules and procedures, contact information, or anything else that needs to be captured, organized, and displayed for the team.

Let’s take a quick look at the setup of Hologram and then jump into some documentation examples.

Hologram is a Ruby gem, so we’ll start out by installing the gem to our system:

$ gem install hologram

Hologram Configuration

With the gem installed, we configure Hologram by creating a YAML file with the following:

​destination: ./docs
documentation_assets: ./doc_assets
code_example_templates: ./code_example_templates ...