UX Writing Style Guide Template
Extract every user-facing string, rank the sentences by who actually reads them, and write the rules from the ones that already work.
Free download · No account needed
A style guide is normally written by looking at a product, forming a view, and writing the view down. Nobody argues with clear, human and direct, because there is nothing there to argue with. Check its examples against the strings the product actually contains and the problem shows up immediately. At the fictional Marlbury, thirty-four do-and-do-not examples matched eleven real strings. The other twenty-three described copy nobody had ever shipped. That guide was not wrong, it was unfalsifiable, and nothing inside it could say so.
Meanwhile the sentences people read most were not in the guide, because they are not in the design files either. They sit hardcoded in the code, written while an engineer was handling a failure. Marlbury had 4,812 user-facing strings, 1,622 of them hardcoded, and 1,085 of those were sentences rather than labels. So this pack builds the corpus first and derives the rules from it, which is the opposite order to every guide template on the internet.
Split sentences from labels, join them to render and error telemetry, and the ranking inverts. Marlbury's twenty most-read sentences carried 65.3% of all sentence impressions from 1.01% of the sentences. Sixteen were failures, thirteen were hardcoded and therefore shipped in English to nine locales, and the existing guide named three. It sits alongside the handoff pack that decides which failure states get written at all, and the design system's own documentation.
What is in the pack
String Register
Every user-facing string from both halves of the corpus, the translation catalogue and the hardcoded literals, joined to how many times each was actually rendered. Sentences separated from labels, because ranking them together buries every sentence in the product under Save and Cancel.
Inconsistency Log
Sentences collapsed into the events that cause them, ranked by combined impressions rather than by variant count. Marlbury's session-expiry event had seven sentences behind it and 942,500 monthly impressions between them, which is 11.3% of all sentence reading and invisible while it sits in seven rows. Grouping by event rather than by text is the move the accessibility remediation pack makes when it groups findings by component instead of by page.
Terminology Map
Every concept with more than one word in use, counted, with a decision per word rather than per concept. Billing keeps account, because that is the word on the invoice and the card statement, and the product body standardises on one noun everywhere else.
Error Message Standard
The three-part shape, derived from the failures that already work rather than from first principles. WCAG 2.2 requires that a known correction is offered wherever an input error is detected, which is the floor here rather than the target. It handles the generic failure message explicitly: Marlbury's was hardcoded at seventeen call sites, so the fix was seventeen specific sentences and not one better vague one. A failure large enough to need a notice as well as a sentence is incident comms rather than copy work.
Voice and Tone Guide
Written backwards. Find the two or three strings you would ship unchanged, work out what they have in common, and make that the rule. Tone moves with what is at stake for the reader rather than with brand adjectives, so warmth gets cut on the billing failure.
Pattern Library
One entry per recurring message type, each carrying the sentence shape, a worked example from the register, and the count of strings that do not currently match it. An entry with no strings behind it is the same failure as an invented example.
How it works
- 1
Send both halves
The translation catalogue in whatever form it exists, plus read access to the front-end source. Either alone still produces findings, and the code half is the half nobody has read.
- 2
Rank by who reads it
Join every string to render and error telemetry, then rank the sentences separately from the labels. Expect a small fraction of the sentences to carry most of the reading.
- 3
Collapse into events
Group sentences by what happened from the reader's point of view. Marlbury's 1,977 sentences came from 1,143 events, leaving 834 redundant ones nobody could see from inside one team.
- 4
Split the plan in two
Every fix is a catalogue edit that ships today or a code change that needs a release. Marlbury split 291 against 543, with thirteen of the top twenty in the second group.
Frequently asked questions
Why not just write the style guide?
Because you cannot check it. A guide with no counts behind it is a set of preferences, and the space rule here is that no rule gets written without the register column that decides compliance and the current number of strings failing it. Marlbury's existing guide had thirty-four examples and eleven of them described a real string.
What if we do not have render telemetry?
You still get a register, an inconsistency log grouped by event, and a terminology map with real counts. What you lose is the ranking, so the work gets scheduled in file-path order. Error telemetry alone recovers most of it, since failures are where the reading concentrates.
Is reading our source code really necessary?
It is the point. The catalogue holds the copy a writer has always been able to see, which is why that copy is already reasonable. The hardcoded half is unreviewed, untranslated, and at Marlbury it held thirteen of the twenty most-read sentences in the product.
Our error messages come from the API. Is that a problem?
Usually yes. Server validation text is written for an API consumer and it is correct for that reader. Marlbury rendered one such string to users from twenty-three endpoints. The client should map a machine-readable error to a sentence a person reads, and the GOV.UK Design System bans exactly this, along with status codes and jargon.
Why does it care about numbers inside sentences?
Because a sentence assembled at runtime from fragments cannot be translated. ICU's own documentation says a message has to be written and translated as a single unit, since a translator handed pieces cannot reorder them. Marlbury welded a number onto the hardcoded fragment days left, 298,400 times a month, in English, to nine locales.
Will this tell us to use one word everywhere?
No, and a map that does would be wrong. The decision is made per word, not per concept. Billing keeps its own noun because the invoice, the card statement and the tax receipt all use it, so the product disagreeing on those screens is worse than the inconsistency.
How is this different from a content audit?
A content audit inventories pages and surfaces. This inventories strings, joins them to reading, and collapses them into events, which turns 1,977 rows into 834 decisions with an owner and a delivery route. Messages you send deliberately are a separate corpus, handled by the in-product messaging pack.
Find out what your product actually says
Send the translation catalogue and read access to the front end. The first number back is how much of your copy no writer has ever seen.
Read your own strings