Voice & tonePrinciples
Seven principles
The principles below are the rules. They are short, they are arguable, and they apply to every page on the site.
The seven
In the order that matters when writing.
Plain words are easier to read, easier to translate, and easier to argue with. The system uses plain words. A clever phrase is allowed only if it earns its place in a pull quote.
Use numbers, names, and concrete references. 'Eight tokens' is better than 'a small set'. 'The 22 px gap' is better than 'that awkward value'.
Make the argument. 'Tokens are the system' is better than 'Tokens might be a useful abstraction'. The system has opinions; it is allowed to have them.
A short page is better than a long one. A short sentence is better than a long one. If a paragraph can be two sentences, it is two sentences.
'The system uses 8 tokens' — not '8 tokens are used by the system'. Active voice is shorter and clearer.
A live demo is better than a screenshot of a demo. A real code snippet is better than a description of the code. The system shows the components, not the spec for them.
A page is an argument, not a list. Lists are useful for tokens, components, and rules. Prose is useful for the rest.
Do and don't
Do
Tokens are the system. Components are proof.
Plain. Specific. Confident. Two short sentences. One argument.
Don't
In this section, we will explore the role that design tokens play within the broader design system, considering how they interact with components, themes, and patterns.
Hedge-y, general, passive. Reads as marketing copy, not as a designer's note to a peer.
How to apply them
The principles are not a checklist. They are a stance. When in doubt, the test is: would a designer or an engineer, reading this on their lunch break, feel respected? If yes, the writing is on voice. If no, something is off.