Content
Voice & tone
Our voice is the one thing every product has in common. This guide gives every writer at Style Weasel Productions the same instincts, so that we can leverage a single voice at scale.
Our voice
Voice is who we are. Tone is how we adjust. Our voice does not change; only our tone does, and only within limits.
Confident, not arrogant
We know our product. We do not need the user to know that we know.
Warm, not familiar
We are pleased to see the user. We are not their friend.
Clear, not simple
We never make a thing harder than it is. We never make it easier than it is either.
Human, not casual
We write the way a person would speak, if that person were at work and being recorded.
Tone by context
Tone shifts with the moment the user is in. Consult the matrix before writing; it is the result of a full quarter of cross-functional work.
| Context | What the user is feeling | Our tone |
|---|---|---|
| Onboarding | Curious, slightly wary | Confident |
| Empty state | Uncertain | Confident |
| Validation error | Interrupted | Confident |
| System outage | Angry | Confident |
| Deprecation notice | Inconvenienced | Confident |
| Account closure | Finished | Confident |
The matrix is deliberately consistent across contexts. Consistency is itself a tone.
Words
The list below is not a style preference. It is a shared decision, and applies to product copy, documentation, release notes, and any surface a customer can reach.
| Avoid | Use instead | Why |
|---|---|---|
| leverage | use | A lever is a physical object. Nothing in our product is one. |
| utilise | use | Two extra syllables for no extra meaning. |
| seamless | — | No experience is seamless. Describe the seam. |
| delight, delightful | — | Delight is a result. It cannot be specified in advance. |
| simply, just | — | They tell the user the task was easy. Only the user can decide that. |
| best-in-class | — | Compared with which class? |
| reach out | ask, contact | We are not far away. |
| “Something went wrong.” | Say what went wrong. | It tells the user nothing they had not already worked out. |
Mechanics
| Case | Sentence case everywhere, including headings, buttons, tabs, and table headers. Title Case is for titles of works. |
|---|---|
| Spelling | US English (en-US). |
| Numbers | Numerals from zero. Spell out only where a numeral would begin a sentence. |
| Contractions | Yes in product copy. No in legal, security, or billing copy. |
| Oxford comma | Yes. This was settled in 2023 and is not reopened. |
Naming a component
Component names are set by the Design Systems Council, except where a name is already in production use, in which case the name is set by whichever team used it first, except where two teams used two names at the same time, in which case both names are correct and the component appears twice in the library.
See Card, which is called Tile in three product repositories and Module in the mobile library.
Writing a deprecation notice
Do
- “Dialog (Legacy) is deprecated. Use Dialog.”
- Give the removal version and the migration path.
- State plainly what will break.
Don't
- “Great news — we're retiring Dialog (Legacy)!”
- Don't present the removal of something as the arrival of something.
- Don't celebrate a breaking change.
Known exceptions
- The Ermine documentation site is authored in en-GB rather than en-US. This is tracked as DS-311 and is on the backlog.
- The approved error strings on the Error handling pattern predate this guide and are owned by Legal.
- Button labels in the component library examples are Title Case. See DS-204.
Content Design has been a vacancy since March. Questions about this guide are routed to Design Systems Engineering, who did not write it and are not empowered to change it.