Website Style Guide

A style guide is a memory aid, not a design exercise. Its whole value is that the fortieth page matches the first without anyone re-deciding what a button looks like. If writing it feels like documentation for its own sake, you are probably writing it too early — the decisions have to exist before they can be recorded.

Record decisions, not aspirations

The most common failure is a beautiful document describing a site that was never built. A useful guide describes what exists, is short enough to read, and is updated when reality changes.

Start with the values that already appear in your CSS. If your buttons use three different radii, that is not a guide entry — it is the first thing the guide should resolve.

What belongs in it

Colour. Every colour with a name and a role: surface, text, accent, border, and the states — hover, focus, disabled, error. Record the contrast ratio of each text-on-background pair alongside the value, so nobody has to re-derive it. The palette method is in choosing an accessible colour palette.

Type. Families, the size scale, line heights, and — most usefully — which combination each element uses. "Body text is 1rem/1.6" prevents more drift than a list of available sizes.

Spacing. One scale, used everywhere. Four, eight, twelve, sixteen, twenty-four, thirty-two, forty-eight, sixty-four. The point is not the exact numbers but that arbitrary values stop appearing.

Components. Buttons, form fields, cards, alerts. For each: what it looks like, what its states are, and — the part usually missing — when not to use it.

Voice. Sentence case or title case in headings. Oxford comma or not. What the primary button says. These are the details that make a site feel like one thing rather than several.

Tokens make the guide enforceable

A style guide people have to remember is a style guide people will drift from. Tokens turn it into something the code reads.

:root {
  /* Колір за роллю, а не за виглядом: --brand, а не --purple. */
  --color-surface: #fcfbf9;
  --color-text: #191634;
  --color-brand: #4a3aff;
  --color-rule: #e3dfd4;

  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-6: 1.5rem;

  --radius: 0.375rem;
}

Name tokens by role, not appearance. --color-brand survives a rebrand; --color-purple becomes a lie the moment the brand turns green.

In a block theme, this already exists as a formal mechanism: palette, type scale and spacing steps declared once in theme.json and surfaced in the editor through global styles. Defining tokens there rather than in a separate stylesheet means editors can only pick values that are in the system.

Keep it where the work happens

A guide in a slide deck is read once. A guide in the repository, next to the code, gets updated with the code.

The strongest version is a living page on the site itself, rendered from the same tokens the site uses. When a value changes, the guide changes with it, because it cannot disagree with the source it is generated from.

The entries people forget

Three sections are missing from most style guides and cause most of the drift.

States. A button has five: default, hover, focus, active, disabled. Documenting only the first guarantees the other four are invented differently each time — and the focus state is the one that gets dropped, which quietly breaks keyboard use. The reasoning is in the accessibility checklist.

Density. How much space sits between sections, inside cards, around headings. Without a recorded answer, spacing is re-decided per page, which is the most visible form of drift. The rule it should encode is in white space in web design.

Imagery. Aspect ratios, whether photographs are cropped or contained, whether illustrations and photographs may appear on the same page. Image decisions drift faster than any other kind because each one is made by whoever is writing that page.

When it becomes a design system

The step up is worth taking when several people build regularly and the same components keep being rebuilt slightly differently.

Building the second before you need it is a common and expensive mistake. A component library maintained by nobody, for a site with twelve pages, is overhead pretending to be maturity.

Common mistakes

• Writing it before anything is built. The decisions have to exist first.
• Documenting exceptions as rules. One page needed a special layout; that does not make it a component.
• Naming by appearance. --blue-dark outlives its accuracy.
• Listing options rather than decisions. "Available weights: 300–900" tells nobody which to use.
• Keeping it somewhere nobody looks. If it is not next to the work, it is not part of the work.
• Never deleting anything. A guide that only grows becomes a list of things that used to be true.

Verify

Take a page built last month and check it against the guide. Every value that is not in the guide is either a gap in the guide or drift in the page, and both are worth resolving. Then hand the guide to someone who has not built on the site and ask them to make a new page — whatever they have to ask you is what the guide is missing.

The principles behind the decisions being recorded are in web design principles, and the structural half in layout design.