Skip to content
Start a project

Why small teams publish a style guide

What we learned writing public style guides for SecureDrop, Briar and Reproducible Builds.

Published
Reading time
3 min
Series
Under the HoodPart 7 of 10
Contents7
  1. The problem is many hands
  2. What goes into a useful guide
  3. Show examples people can copy
  4. Keep it public and lightweight
  5. Reuse a structure that works
  6. A guide needs an owner
  7. Does your business need one?

A style guide sounds like something only large companies need. Our experience points the other way. Some of the most useful style guides we have made were for small organisations and volunteer projects: SecureDrop for Freedom of the Press Foundation, the Briar secure messaging app and the Reproducible Builds initiative.

What these projects had in common was not size. It was the number of people producing material without sitting in the same room.

The problem is many hands

Reproducible Builds is maintained by volunteer contributors. Before the style guide, people produced slides, pages and graphics without a shared visual reference, so logos, fonts and interface components varied from one piece to the next. Nobody was doing anything wrong. They simply had nothing to check against.

SecureDrop had a similar issue at a different scale. It is a whistleblower submission system installed by news organisations, and each newsroom’s team works on its own installation. Without a clear reference, each team risked creating its own version of the brand. For a security product, that matters: a page that looks different from what people expect can make them hesitate at exactly the wrong moment.

What goes into a useful guide

A style guide does not need to be a hundred pages. The ones we built cover a small set of decisions that people make again and again:

  • colours, with the values written out
  • typography: which fonts, which sizes, where each one is used
  • icons, ready to download
  • interface components such as buttons, forms and alerts
  • the logo and how it may be used

The goal is to answer the question someone has at the moment they are making something, so they do not have to guess or ask.

Show examples people can copy

Rules alone are hard to apply. The SecureDrop and Reproducible Builds guides include documented examples that contributors can copy directly into their own pages. A contributor building a new page starts from a component that is already correct instead of rebuilding it from a screenshot.

Keep it public and lightweight

These guides are public web pages, not files passed around by email. Reproducible Builds keeps its guide under the initiative’s main domain. Briar’s guide is a Hugo site published on GitLab Pages. Anyone can find the current version, and there is only one current version.

The SecureDrop guide also works without JavaScript. Security-conscious readers often browse with scripts disabled, so a reference written for them should respect that choice.

Reuse a structure that works

When we created the Briar style guide, we based its structure on the SecureDrop guide. The two projects have different identities, but the questions contributors ask are similar, and a familiar structure made the new guide faster to build and easier to navigate.

A guide needs an owner

A style guide is only useful while it matches the product. Someone needs to update it when a colour changes or a new component is added, and contributors need a way to suggest changes. Keeping the guide in the same repository as the rest of the project helps: an update to the design and an update to the guide can be reviewed together.

Does your business need one?

If one person designs everything, probably not yet. If several people or agencies produce material for you, such as social media posts, presentations, a website and printed pieces, even a single page with your colours, fonts, logo files and a few examples will save time and keep things consistent.

We include brand basics in our website briefs, and you can see these style guides in our portfolio. If your team needs a shared reference, let’s talk.

Next step

Planning a website? Tell us what you need and we will reply with a clear plan and price.