What People Publish

Style Guide

Definition

Two different documents share the name. An editorial style guide settles the questions that otherwise get argued in every draft: serial commas, capitalisation of job titles, how dates and numbers are written, which spellings the house uses. A design or front-end style guide documents the interface — the type scale, the spacing steps, the colour tokens, and every component shown in its states with the markup beside it. The second kind is often built as a live page so that the examples are rendered by the same CSS the product uses, which means a component that has drifted shows its drift. A style guide is narrower than brand guidelines, which cover the identity as a whole.

Why It Matters

A style guide's value is measured in arguments not had. Without one, every new page is a fresh negotiation about heading sizes and every writer decides capitalisation for themselves, and the result reads as though several organisations made it. For a front-end team the guide doubles as a test surface: put every component on one page and a change to a shared CSS variable shows its effect everywhere at once, which is a great deal faster than hearing about it from a user. The guide also has to be somewhere people can reach without an account, or contractors and agencies will simply guess.

How It Works

Build the guide as a page that loads the real stylesheet rather than a copy of it, so the examples cannot drift away from the product. Show each component in each state — default, hover, focus, disabled, error — with the markup visible next to it. Document the tokens as values rather than descriptions: the actual hex codes, the spacing scale in pixels or rem, the font stack as written. Publish at a fixed address and republish when it changes, so a link in an onboarding document never needs maintaining. Where the guide is internal, put a password on it; where it is meant for partners and suppliers, leave it open and easy to find.

Real-World Example

A product team publishes its guide at productname-styleguide.99helpers.site as a single folder: one page per component, the production stylesheet, and a page of tokens. A contractor building a new screen copies the markup for the form fields straight from the guide and gets the focus states right without asking anyone. When the type scale changes, the team republishes to the same address, and the previous version stays in the history on 99helpers — which settles a question a week later about what the old spacing values were.

Common Mistakes

✕Writing the rules and leaving out the examples — people do not follow a rule they cannot see the result of, they copy whatever the nearest existing page does
✕Letting the guide carry its own copy of the CSS — it slowly stops matching the product, and then it is worse than having none, because people trust it
✕Keeping it in a design tool nobody outside the team can open — an agency without a licence cannot see it, so they guess, and you review the guess

Related Terms

Brand Guidelines

Brand guidelines are the document that says how an organisation's identity may be used: the logo and its clear space, the colours with their values, the typefaces, the tone of voice, and what is not allowed.

Documentation Site

A documentation site is the reference for a product, library or internal system: how to install it, how to use it, what each option does. Most documentation tools output plain HTML, which makes documentation one of the most common static-hosting jobs there is.

Put a file online in seconds

Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.

Host a file free →