Pretty much the first thing I did when joining Snyk was to put together a rough front-end style guide. Having a style guide means we can assemble templates more quickly, and we’re less likely to unintentionally build the same thing more than once.
It was especially helpful to get a framework in place before Mark, our designer, began work on updating the site styles. We use it a lot for referencing colours, or grabbing some markup for a button or checkbox.
Our style guide is public. This is because the easier it is for the rest of the team to reference it, the more likely we are to use it. Knowing that people might be looking at it is also a good way to keep our code in check – that we’re writing markup we’d feel proud to show.
Deciding on a framework
I’m new to Node which is what Snyk is built on, and after messing about trying to get the patterns generated from a folder of partials, I turned to KSS – specifically, a Node implementation of KSS.
With KSS, you write the HTML in the CSS as comments. KSS takes these comments, and generates a style guide out of them.
Here’s an example Sass partial called author.scss, which holds a pattern used on the blog to show an author’s name and avatar:
// Image dimensions 70x70, served by cloudinary.com. Can be found on a blog post.
// <div class="author">
// <img src="http://placehold.it/70x70" alt="Photo of Full Name" class="author__photo">
// <a href="#" class="author__link"><span class="author__name">Author name</span></a>
// style guide component.author
margin: 0 0 1.5em 0;
margin: 0 0.7em 0 0;
At the top of the file is a CSS comment, which is what KSS looks for to pull this pattern into the styleguide. The first bit of the comment is the title of the pattern (Author). The text underneath is a description of the pattern. Below these descriptions is the markup the pattern uses, followed by its identifier, which indicates where the pattern lives. KSS will generate a new section of the style guide if a new identifier is used (
component.author places it in the component tab, along with the other components).
KSS works nicely with the way we write CSS. We’re using BEM, and KSS lets us define modifiers and display them easily in the styleguide.
It does all the things I like to do in a style guide, like letting me add a description for each pattern and showing the HTML alongside it.
My one concern with KSS was that it isn’t DRY. Normally when I build a style guide, I include the same pattern markup that is being used in the site, and using the same language the site is built with. So, if it were a PHP site, I’d create the patterns as PHP
includes, and include these in the various templates, but also include these same files in the styleguide. So if the pattern code changes, the style guide gets updated automatically with that change made in one place.
Unfortunately, relying on code comments like KSS does to generate the style guide means the patterns don’t stay in sync with the site – you have to remember to update them if you update the template.
Adding patterns to the style guide does require that extra step, but we’ve ingrained it into our process, and as a bonus, it makes our CSS better documented.
What’s in our style guide
The most useful thing for us in our style guide is the colour swatches. These include the Sass variable name, so if there’s a colour we want to use, it’s a case of looking at the style guide and copying and pasting the variable name into the CSS.
The fonts are also documented. We use four different weights of Prenton (Regular, Medium, Bold and Black), plus italics. (These fall back to a system font if Prenton doesn’t load quickly).
We have a section for the base styles – pure elements without classes applied to them - so we can see what the default looks like. We also have one specifically for forms, including all the different button styles and modifiers.
There’s a section for layout, navigation (including pagination, breadcrumbs and tabs), and also one for blog posts specifically.
Components make up the bulk of the patterns, and this section contains things like the severity level indicators, dependency tree styles, and “cards”, which are snippets of information shown on a page in various formats.
The utility section is for styles that add margin, padding, or a background colour to an element. We try and bring these into a component where possible, but they are very useful for quickly mocking something up.
There are a few things our style guide currently doesn’t do that are on my wishlist:
- I’d like to separate the content from the code, the way Lonely Planet have done with Rizzo, generating their style guide using an API. I’m also keen to get some performance monitoring in there, like they’ve done.
- I’d like to add a voice and tone, like Mailchimp have, to help keep our messaging consistent. I’d like to tie this in with some controlled vocabulary – there are a lot of phrases we use when describing vulnerabilities, and we need to describe these consistently to avoid causing confusion.
- As part of building the style guide, I’ve also been working on visual regression testing, so we can take before and after screenshots that get overlayed on top of each other, highlighting the differences. This means we can check a branch for unexpected visual changes before pushing it production. This is a particularly useful test to run against the style guide, as long as all of our styles are in there. It isn’t currently working as I’d like, but I’m keen to demonstrate it once implemented in a later blog post.
Our style guide is not a perfect solution, but it’s doing the job nicely for now. I’m looking forward to building it up as Snyk grows.