Styleguides: more than just about style

Style Guide

When we talk about styleguides in 2016 we need to recognize that they come in a variety of flavors, both in terms of their content, how they get used and how they set the stage for the success of a website.

Traditionally, visual styleguides were geared almost exclusively toward branding across a variety of mediums, including print ads, billboards, company stationary, and Word document templates. Styles for websites were often defined, but they were rarely robust enough to meet real-life requirements of a working website. A section defining colours, fonts, positioning of logos, and visual treatments of images often left designers (and developers) at a loss when it came down to the many other components that make up a functioning website. These styleguides were (and sometimes still are!) created using InDesign and exported to PDFs, making them somewhat cumbersome to use.

Thankfully for web designers and front-end developers, some styleguides have evolved beyond the static PDFs and general branding guidelines of the past. Today we have entire HTML-based resources that illustrate how elements of a website look, and how they function in the environment they’re intended to reside: the web browser.

Image of Lonely Planet's Style Guide

Lonely Planet’s styleguide illustrates the design of its various components as well as the scripts used behind them.

Advantages of a Styleguide

Having a “living” online repository of styles and digital assets should be immediately apparent to anyone well versed in web design or front-end development. At the most basic level, it demonstrates how elements like buttons or forms behave in a web browser. At the more advanced end of the spectrum, a styleguide may illustrate how a widget animates on the screen and what happens when a user interacts with it. A responsive guide could demonstrate how this same widget behaves when viewed at different screen sizes.

Whistler's Responsive Style Guide’s styleguide, illustrating responsive behaviors of its event cards.


Having guidelines for design and behaviors is important for the sake of the people maintaining a site, but more importantly for the people who are actually using it. In terms of user experience, there’s something to be said about having things behave in a predictable and consistent manner.

These libraries can also help ensure best practices are being met in terms of HTML mark-up for cross-browser compatibility and accessibility. Increasingly we see guides that allow developers to see the markup as well as the CSS of any given component. Better yet, we are now seeing styleguides that share the same assets as the live site. If a change is made to the CSS, the changes are reflected in both the guide and site. This helps ensure the two are never out of sync.

What’s in a name?

The term “styleguide” can mean different things depending on who you talk to. As a result, it’s often worth establishing a set of high-level and technical requirements for what’s to be developed so all parties understand what their styleguide is and isn’t.

For example, it may be decided that an organization’s guide should support the following:

General Requirements

  • Be a living, instant representation of our website’s components
  • Improve communication and aid in the exchange of ideas between stakeholders, designers and developers
  • Provide a platform that improves testing and quality assurance
  • Be mobile-friendly and illustrate the responsive behaviors of any applicable elements
  • Allow searching of components based on name or category
  • Allow styles to be edited by non-technical people
  • Encourage consistency in visual design, HTML markup and CSS
  • Illustrate best practices for accessibility standards

Technical requirements

  • Be LESS or SASS compatible
  • Make use of same CSS files used on live sites
  • Provide support for KSS style documentation
  • Allow developers to easily view markup or styles attached to a given component
  • Be available to developers and other interested parties through Github or Bitbucket


Styleguides in the Design Process

It’s easy to think of these sorts of styleguides as something that arrives after a site is completed, but they can also have a role during the design phase of a project. In our experiments with design in the browser, we’ve sometimes used styleguides in place of Photoshop by using PatternLab.

PatternLab, a styleguide toolkit developed by Brad Frost uses atomic design principles; a methodology that encourages web designers to build things starting at a ‘molecular’ level and to use those elements as building blocks for more complex components.


Using PatternLab, a styleguide may be organized in such a manner:

Atoms: headers, paragraphs, buttons, links, form labels, input fields, logos, single images

Molecules: articles, search form, lists, images with captions, primary navigation

Organisms: Site mastheads, footers, product grids, comment threads

Templates: homepage, product page, blog

While there may always be some exceptions, generally objects in the Organisms category will consist of Molecules, and Molecules will consist of Atoms. Make a change to an Atom and the result will be seen further up the chain all the way up to the Template level.

If traditional styleguides were created to encourage visual consistency, tools like PatternLab take things a step further by ensuring consistency and efficiencies in terms of how things are built. It encourages us to re-use CSS and HTML mark-up so that we’re only creating what’s necessary. Not only does this make a site perform better and easier to maintain, but benefits user experience as well.


While it’s easy to espouse the virtues of having a styleguide, things often become a bit less clear when it comes to how such a thing works during the process of creating a website or the maintaining and updating it. Even on it’s own, there’s the question of who maintains the guide, who writes and adds the descriptive copy that resides within it, who adds or removes elements from it so that it remains up to date and relevant.

Usability Matters recently created a guide for a client using KSS notation that allows developers to add a layer of documentation directly within the CSS. Or put another way: the CSS is the styleguide. While it’s advantageous to want to keep things together this way, it did raise the question of whether or not it should be left to developers to have to write the instructive text and accompanying descriptions.

While styleguides can’t solve all problems related to workflow, they do present opportunities to improve it. They encourage designers and non-designers alike to think less about static layouts and pages and more about dynamic modules and patterns that fit together regardless of screen size.

Additionally styleguides make conversations between creative and technical teams easier by being able to focus on specific elements to ensure they look and function the way they were intended and/or experiment without going back to the drawing board completely. On a more general level, styleguides give anyone (regardless of their position or experience) an immediate understanding of the lay of the digital landscape.

Further Reading




Example styleguides

New Call-to-action