Front End Style Guides

Anna Debenham started the new year off by releasing an updated version of her book, Front End Style Guides and I spent some time reading it and highlighting and remembering what it is I love about style guides this week. Anna wasn’t the first person to introduce me to style guides, but she was definitely the first to talk about them extensively and her work helped me wrap my head around how they could work in client projects and product work.

The updated version is really well done with lots of great information about the steps to take to create a guide, why you should bother with the guide, and examples of guides to get ideas of how different places are using them and maintaining them. One thing I love about how Anna talks about style guides is that it’s about the guide being useful to the team that uses it; so guides can, and should, differ from team to team.

My highlights are below broken up by chapter, my highlights from her previous version are also on this site. Please remember that these are out of context, so you may want to read the whole thing to understand the concepts.

Chapter 1

Front-end style guides are still in their infancy, and a lot of terms exist. Just make sure the name you choose for your style guide makes sense based on what you’re building, and use the terminology you’ve chosen consistently.

While I like the Atomic principles and I think about them when I’m writing front-end code, my preference is to stick with the word “component”. I find the Atomic terminology too rigid – it’s not always obvious whether one of these building blocks is an atom, molecule, or organism, and I don’t want to pass on this confusion to the client.

Design systems are a particularly useful tool for creating a common design language for an organisation’s many different products, from websites to mobile apps.

Your front-end style guide could contain a pattern library, but it could also have a section on tone of voice. It’s a useful all-encompassing term.

Chapter 2

Component libraries are collections of all the components on a site, displayed in one place. They act as deliverables for other developers rather than as design conversation pieces.

I’ve found component libraries most effective as deliverables after the site has been developed, particularly if there’s any additional work to be done. Component libraries have been especially useful to me when I’m writing markup and CSS but handing over my work to developers who will integrate it with their CMS. Having patterns alongside the corresponding markup makes life easier for these developers – it means they don’t have to pick through my code to find what they need.

Chapter 3

Rather than asking the designer to style every possible element, create something the designer can refer to and tweak. A basic stylesheet, complemented by a style guide showing how elements look, makes it easy to sit down with the designer and work through it.

Just writing a style guide forces you to think about the semantics of the elements you’re using. My markup has become more thoughtful since I set out to make it publicly accessible and engaging: I want people to read it and use it!

Reflect on the techniques you’ve adopted: are they still worth following, or are they merely how you’ve always done things?

When you’re rapidly iterating, inconsistencies can creep in. Having all your modules in one place during code review helps keep track of what’s new, what’s a duplicate, and what’s not being used.

Demonstrating how a design adapts on real devices rather than in static mock-ups makes responsive design discussions easier. Front-end style guides are also invaluable as a way of delivering work, especially in Agile projects where different parts of a website may be completed at different times. Rather than getting feedback on a whole system at once, you can deliver parts of it, and really focus that feedback on the individual components.

The emphasis here lies on “collaborate”. People will resist adopting a process they don’t feel a part of. Get team members involved in planning and building the style guide right from the start so they are more likely to want to maintain it.

That being said, you can still make a front-end style guide if the site already exists. It’s harder to do at this stage, but it can be a useful part of an audit into a site’s design and front-end code.

A style guide that’s out of date is almost as useless as no style guide at all. The ongoing challenge is making style guides that are powered by the live site, using the same styles, the same content, and the same codebase.

No matter how good your pattern library or documentation is, it’s not a replacement for talking to the client or the rest of your team. A style guide isn’t something to build, hand over, and forget about.

Chapter 4

Sometimes many different styles are justified, but they must all have a reason for existing, ideally with their intended purpose documented in the component’s usage notes. Be aware that for every additional style, you’re increasing your code footprint and maintenance needs.

Very long headings or double-barrelled names can cause unexpected problems, so your content examples should respond well when text flows onto multiple lines or is bigger than its container. Use the style guide as a way to show these extremes and prove that you can deal with these situations.

Chapter 5

Your style guide doesn’t have to be a work of art. Sure, it helps if it looks nice because people will feel more proud of it, but a style guide is a tool. Start small and simple, and build on it as and when you can.

Chapter 6

A style guide isn’t a silver bullet – it needs good practices, care, and attention. Its success should be measured not by how good it is when it launches, but by whether it is kept up to date and referred to months, even years, later.