Voice & toneWriting examples

Writing examples

The twelve microcopy moments that show up in the system. Each is the version that shipped, with the reasoning.

12 microcopy momentsEach is shipped codeArgue in the PR

The twelve

Use these as anchors. When you're writing new microcopy, the right answer is usually one of the patterns below, with the words swapped.

Where	Copy	Why
Button — primary	`Read more`	An action, not a sentence. Two words. The verb carries the action; the noun carries the destination.
Button — destructive	`Discard changes`	States the consequence, not the action. 'Delete' would have been shorter; 'Discard changes' is the one the reader needs to see.
Form label	`Email`	One word. The helper text below carries the policy. The label is the question, the helper is the answer.
Helper text	`We'll only contact you about the design system.`	States the policy in the reader's voice. Not 'Email addresses are required for notification purposes.'
Section header	`How to add a diagram`	An action header. The reader knows what the section is going to teach them to do.
Empty state	`No matches. Try a foundation or component name.`	States the situation and offers a next step. No 'Sorry' — the system doesn't apologize for an empty result.
Toast	`Saved`	Past tense. One word. The reader can move on.
Error message	`Please enter a valid email address.`	States the problem, suggests the action. Not 'Invalid input' — 'invalid input' doesn't tell the reader what to do.
404 page	`This page doesn't exist. Try the work index.`	States the fact, offers a next step. The page is a fork in the road, not a dead end.
Search placeholder	`Search foundations, components, patterns...`	Suggests the breadth of the index. The ellipsis is a concession to the reader, not a flourish.
Tab title	`Color — Foundations`	The page name, then the section. The reader always knows where they are in the doc system.
Open-graph description	`Tokens, components, and patterns. The official design system for the izaias personal website.`	A noun phrase. Tells the reader what the page is, in 90 characters, in the first 12 words.

The four microcopy rules

Plain words. "Email" is a label, "Email address" is a label that hides. Use the short one.
One idea. A button label is one idea. "Read more" works. "Read more about the case study" doesn't.
State the action or the consequence, not both. A destructive button names the consequence. A primary button names the action.
No "Sorry". The system doesn't apologize for being a system.