When Style Guides Meet Pattern Libraries…
Reusable Babies Are Born
So you’re building a SaaS app, a consumer web product, or absolutely anything that will live in a web browser. You might consider utilizing a Web Style Guide–essentially, a type of design system that lives in a browser and makes life much easier on those that need to develop web application features at a rapid pace.
What’s a Web Style Guide?
You may be confused by the use of term Style Guide, because Style Guides started out as static PDF documents that defined a company’s branding guidelines, examples of logo and identity, color palettes and typography, and might also include content and tone guidelines for content writers. But this sort of static PDF document, is not what we mean by Web Style Guide.
A Web Style Guide is a living web site that documents aspects of a web-based application. But that’s a pretty broad definition. Let’s let the prolific Brad Frost list some specific Style Guide categories that are commonly seen:
- Brand Identity
- Design Language
- Voice and Tone. Writing
- Patterns
- Code
As you notice, some of the things from our old PDF document are still potentially there; notably Brand Identity and Design Language, just on a web page. But, using this, let’s redefine a Web Style Guide as:
a web site that delivers one or more of the above categories for use by designer, developer, and product teams, to help make their jobs easier when trying to figure out how their product should look and behave.
In practice, it’s a one-stop place for the entire team — from product owners and producers to designers and developers — to reference when discussing site changes and iterations.
Benefits
Suffice to say that a Web Style Guide is only as useful as its ability to serve folks who are “in the trenches” helping to improve the product your customers covet so dearly. Specifically, a useful Web Style Guide will:
- Proliferate awareness and understanding of the design system throughout your organization
- Document your system in a more digestible way that new hires and non technical team members can understand
- Provide a single source of truth where code in the Style Guide reflects code in production
- Instill a sense of pride and craftsmanship and allow for reuse of code
- Attract potential talent that sees that you follow current web best practices
Additionally, an effective Web Style Guide will allow your team to build out features faster and more reliably while reducing complexity.
Lincoln Mongillo–Web Category Manager at Starbucks–talks about their motivation to create a Styleguide:
We created the Starbucks style guide, which was atomic elements or content modules that we thought were perfect ways to express responsive at Starbucks. It created a common language for us to rally around as a design team and a development team.
This notion of a common language that can unify dev and design is key.
What’s a Pattern Library?
If you look at the list above, you noticed that a Web Style Guide may contain things like code and patterns. In fact, a pattern library may be, and usually is, included within a Web Style Guide that describes the system’s UI on the widget level.
In the case of Mavenlink’s Web Style Guide, we have two sections, UI Components and Modules that serve this purpose. It should be noted that we use modules to mean any combinations of components that work together to do something e.x. an Autocomplete module may consist of an input, dropdown, typeahead logic, etc., that all work together.
Web Style Guide Best Practices
What are the components of an effective Web Style Guide from the practitioner’s standpoint? Let’s dive in…
Componentization
In software, componentization is may be defined as:
Componentization is the process of atomizing (breaking down) resources into separate reusable packages that can be easily recombined–Rufus Pollock
A Web Style Guide helps you to move towards a system of componentization since your UI components are presented at the component level. So, if you for some reason had 10 different versions of Buttons in your system, all coded differently, you’d have to ask “Which one do I put in the Styleguide?”. You’d obviously determine that this is bad, and hopefully choose one Button to rule them all, then, refactor the other 9 versions of Buttons to use the same code. While this scenario may seem contrived, it’s not at all uncommon to find yourself in a place where you have duplication across your system. A Web Style Guide exposes that and gives you the opportunity to correct it!
When the 18F and the U.S. Digital Service teams introduced the U.S. Web Design Standards they spoke to the empathetic side of componentization as you get the benefit of documentation your developers can use as a result:
We wanted to create a single reference point for developers in need of common patterns, providing the building blocks of code for teams to assemble websites. Our goal was to build a system of components shaped by modern best practices in front-end development and government accessibility standards.
So while refactoring alone may improve the componentization of your system, putting that component in the Style Guide further benefits future teams in terms of providing findable source of documentation. According to Robert Haritonov–author of Web Style Guide engine SourceJS:
The documentation process is always the weakest spot among modern web builder teams.
Single Source of Truth
In addition to solving the documentation problem, we must also test our UI components while also ensuring they stay in sync with our production system. What we really want–as we’ve started to call at Mavenlink — is a sort of Single Source of Truth. Ian Feather of Lonely Planet describes how important it is to maintain consistency between a Web Style Guide and the production system:
if you’re rendering templates to a Style Guide and you want it to be maintainable, then they can’t just be identical to your application templates, they need to be the exact same templates. This is easier said than done.
Lonely Planet created a whole component API based system called Rizzo to achieve this where every components is “asked for” via a Component API call.
For our Web Style Guide, we’ve chosen a slightly different approach. Perhaps trading some robustness in order to stay lighter weight, in that none of the system code requires an API call for customized component initialization, or commented CSS code.
Our system uses TDCSS, which, essentially works as follows:
- You create a simple HTML page
- Include your production CSS and any JavaScript
- You craft sections of your Styleguide e.x. Buttons, Dropdowns, etc.
- For static widgets simply define markup which will utilize the production CSS
- For template-based components, use JavaScript or Coffeescript to instantiate that component
The exact same production templates that are in production will be initialized in the exact same way as they are in production, since it’s using the same code.
A notable benefit from using the rather unopinionated TDCSS, is that we were able to not only use on our older Backbone components, but, also our newer React/Webpack delivered components with little additional effort. At it’s core, TDCSS is just a simple HTML parser which will use whatever is included on the page…in our case it’s our production CSS and JavaScript–nothing more, nothing less. Win!
Edd Sowden and the dev team at GOV.UK also realized they needed a Web Style Guide that properly stayed in sync, but, when looking at Rizzo as an option it was determined:
What we really wanted was the ability to update all the pages on GOV.UK without having to bump a gem in each repository and then re-deploy each application
And so they developed their own system. Salesforce has also followed suit in this trend towards finding a way to achieve a dynamic style guide:
The Salesforce Lightning Design System is our living style guide that makes doing the right thing also the easiest thing. We define our styles using code. They are flexible. The intent is for them to evolve to our needs, quickly.
The take away, is that the old way was generating a Web Style Guide from statically built pages, or comment-based generators, the new way is some sort of system that uses the same component templates on both sides.
Communication
Once you’ve got a Web Style Guide that inspires confidence, there’ little reason for team members not to use it. Bookmarkable URLs make a single source of truth even more powerful providing the ability to drop links to specific components in your team’s Slack channel or Google Hangout meeting.
Accountability
Having a publicly facing style guide shows a company’s commitment to quality, but also holds that company accountable and motivating teams to do the “right thing”. Frederico Holgado, lead UX developer at MailChimp states:
Just knowing that other people are looking and that [MailChimp’s Style Guide] is a resource…that just makes us feel like we have to keep up with it.
Navigation
While there are many navigational patterns that can certainly work, if you’re application is embracing a single page app SPA convention, it might make sense to have your Web Style Guide do the same depending on how many categories it covers. For Mavenlink’s Web Style Guide, we’ve went with this approach as it helps designers and developers find things quickly.
In his Introduction to Style Guides, Jake Rocheleau praises Yelp’s Web Styleguide for using a single page approach stating that it provides the benefit of:
Organizing design & brand concepts into a unified location for easy access…Everything is easily accessible from a series of links…Each design pattern ranging from regular typography to grids and buttons is organized with code samples and live demonstrations.
As your Web Style Guide starts to include more ethereal resources for things like design language, content style and tone, etc., you may elect to utilize a more complicated navigational system like Salesforce does with their Lightning Design System.
Speed
In the same article — Introduction to Style Guides — Jake Rocheleau also asserts:
Being able to quickly expand upon an existing website is one of the most significant factors of a style guide
When asked if the up front cost of building a Web Style Guide is really worth it, Anna Debenham states:
With a site that has a pre-existing pattern library, I can add a new piece of functionality to the site much more quickly than if I had to forage around the site hunting for similar styles or recreating something that nobody is aware already exists.
The notion of being able to find things quickly and ramp up new developers is a common motive for the use of CSS frameworks such as Foundation and Twitter Bootstrap. Brad Frost reflects on this:
Faster design and development is one of the main reasons why UI frameworks like Bootstrap are so popular. We’re under pressure to get projects out the door as soon as humanly possible. By developing your own design system, you can reap those same speed rewards as the out-of-the-box UI tool kits
The takeaway is that getting the speed benefits of a framework but not compromising your brand, and this can be achieved with a Web Style Guide.
Conveniences
General usability for the hurried developer and designer that actually will use the Style Guide is key. These sorts of “UX niceties” come in many shapes and sizes, but here are couple of examples that we implemented at Mavenlink:
Parting Thoughts
This article has attempted to define what a Web Style Guide is, why and how to you’d want to use one, and, provide a few prerequisite concerns you’ll want to consider before embarking down the road of setting up one yourself. With that purpose in mind, we’ve avoided code examples and gory details so you can focus on big picture and testimonial from thought leaders in the field. Perhaps, we’ll follow up with an in-the-trenches examination of how we went about implementing this at Mavenlink in an upcoming post.
