How to Convince People to Contribute to Style Guide Development

How to Convince People to Contribute to Style Guide Development

The benefits of creating and maintaining website style guides is so clear that I try to contribute a style guide to new or existing web services whenever I have the chance to do so. To benefit from style guide-driven development, selling team members on creating a style guide is a crucial step. When selling the idea to a developer, you need to use arguments that are different from what you would say to a business owner. This article is all about how to convince people to be a part of the style guide development. If you're unfamiliar with style guides, the resources section has links for getting started.

Convincing front-end developers of the benefits of a style guide

The more seasoned the front-end developer is, the easier your task will be. I think all developers who have completed a project or two have seen the following problems with their CSS and HTML:

  • developers creating the same controls twice
  • inconsistencies across pages (font sizes, margins)
  • existing utility classes not being used
  • differences between behaviors (for example, missing data-attributes)
  • difficulties connecting smaller components for creating new ones
  • communication between team members lacking a shared vocabulary

All these are symptoms of poor information transfer that a style guide approach can improve.

After introducing the idea to the developer and getting the thumbs up, you'll hear every developer's favorite question: "Which library/tool should we use?" which is a synonym for "how do we get started?"

I would start without tools.

The reason is that tools will draw attention away from things that matter, such as increasing useful documentation. Many of the tools (such as KSS) have created more problems than benefits. Troubleshooting a tool doesn't add any value to the project. Instead of selecting a tool, the team should decide on a suitable way to create structure in your process.

Convincing a business owner to spend time and money on a style guide

First of all, creating and maintaining a style guide sounds expensive, something that only big companies can afford to do. Searching for "style guide examples" will return huge sites like Lonely Planet's or National Geographic's. Just by browsing, you can get the sense that a company has to spend a great deal of time and money to create a style guide.

Most projects do not have the same scale or monthly budget as Lonely Planet's projects. Your task is to explain the difference and choose an appropriate level of a time usage for the style guide.

From a business perspective, what are the benefits? Saving money and increasing quality, especially in the long-run.

A business owner probably wants a more detailed description of how money will be saved and why quality will increase.

  • increased communication leads to less duplicate work
  • consistency across views in a product and also consistency across products
  • proposing changes is easier when you have a shared vocabulary
  • related services (such as third-party clients to your platform) can have the same look and feel


Knowing that something is beneficial isn't enough; you need to be able to convince people and help them understand the benefits. Forcing people to use a style guide without discussing it with the team won't ever work in the long-run. Also, depending on your organization, you might have to convince a boss that this extra step is worth the effort. Use the provided bullet points and do a bit of research. For example, use case studies of similarly sized companies/products to back up your argument.

Discuss on Hacker News