Jon Allured

Computer Programmer, Whiskey Drinker, Comic Book Reader

Using Style Guides to Drive Website Design

published 10/30/25

A practice I picked up from my days at Hashrocket is to add a style guide section to website projects. I've been using this on my personal projects and wanted to write up why I spend the time and how it has helped me drive the design of these sites.

Style Guide Sections

The idea is to add a section to website projects where we can produce the intended design by using dummy pages. The style guide section can have one or more pages where we lay out common website elements and ensure they visually appear as designed.

Typically these are orphaned pages that are really only helpful while building the project but I like to actually publish them so I can verify things on my production site.

My Style Guides

I have a style guide section on my Rails project Monolithium that has separate pages for:

For this blog I did something even more simple and just added a single style guide page that gives me a good enough set of elements to use.

Driving Out Table Styles

As an example of how this practice can be useful I wanted to share how I drove out the design of table styles for this site. At the end of the Evaluating Apache Access Log Data post I did a table of data that initially looked like this:

Table Before Styling Screenshot

click for bigger

I logged an issue to come back to this because I didn't like how it looked. That was a good excuse to add a table to the style guide page so I did that and then iterated on the design until it looked like this:

Table After Styling Screenshot

click for bigger

Then I opened a PR to close the issue and deployed that change pretty quickly. You can take a look at the actual styles - there isn't a lot there just some minor changes but I think they make the data look a lot nicer!

Why Bother?

I could have easily made this improvement to table styles without bothering with a style guide but I think it is worth the effort. As the site evolves I might find that I will have variations of tables that I want style slightly differently. Now I have an easy place to do that and to document those differences.