Voice & toneDo and don't
Do and don't
The five pairs that come up most often in the review queue. Each pair is an actual sentence that almost shipped, paired with the version that did.
The five pairs
Do
Tokens are the system. Components are proof.
Plain. Specific. Confident. One argument in two sentences.
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.
Do
Eight color tokens. Three radii. Two shadows.
Specific numbers. The list is short and the reader can hold it in their head.
Don't
A small, carefully curated set of color tokens, radii, and shadow elevations.
Vague. "A small set" is what every design system says.
Do
Read color first, then typography, then spacing.
An order. A directive. The reader knows what to do next.
Don't
It is recommended to familiarize yourself with color before exploring typography, though the optimal order may vary based on your needs.
Bureaucratic. The reader's time is being wasted.
Do
This is not a brand voice. It is the voice of one designer.
Plain. Honest. The reader knows what kind of site they're on.
Don't
Our brand voice has been carefully crafted to reflect our values as a forward-thinking design collective.
Marketing. There is no collective. There is one person.
Do
The system has 23 components. Each one a real artifact.
Specific count, specific promise. The reader knows what to expect.
Don't
We are proud to offer a comprehensive library of components.
"Comprehensive library" is what every component library says. The word is meaningless.
After the do and don't
The patterns above are not rules to memorize. They are anchors to return to. When in doubt, the seven principles on the principles pageare the test.