Writing

Start with a verb and name the object: “Create invoice”, “Download CSV”, “Add member”. A control labeled for its category rather than its effect makes the reader guess which effect they are about to get.

Controls are read out of context. A label reaches someone in a toolbar, in a row of icons, or in a screen reader’s list of every element on the page, where none of the surrounding text comes with it. A label that only makes sense next to its heading has no meaning in the place it is needed most.

“Save changes”, not “Save Changes”. Sentence case is one rule for every string in the product, so nobody has to decide per component whether a label counts as a title.

No periods, no ellipses, no exclamation marks. A label is not a sentence, and an ellipsis promising “more” usually means the label was not specific enough. Periods belong in helper text and error messages, which are sentences.

A dropdown button labeled “Menu” names its own mechanism rather than what it opens. So does a dialog titled “Modal”, a link labeled “Link”, and a button labeled “Button”. The reader can see what it is; tell them what it does.

“Delete file” is knowledge the reader has at the moment of clicking. “Remove” is not. Where the outcome destroys something, the label says what is destroyed, and the color is never the only thing carrying that.

An error names the problem in the reader’s terms and gives them the next move. “Enter a date after January 1, 2020” is both. “Invalid input” is neither, and “Something went wrong” is an apology standing in for a message.

“Sorry”, “Oops”, “Unfortunately” and “Please” spend the reader’s attention on the tone of the failure rather than on getting out of it. State the problem.

A placeholder disappears at the first keystroke, so anything the reader still needs while typing belongs in helper text where it stays. Show the shape of the answer — “name@company.com” — rather than repeating the label.

Second person, and no hedging. “Use an icon button when the action is already understood.” Not “it is generally recommended that icon buttons be considered for…”.

If something is a rule, state it. If it genuinely depends, say what it depends on — that is more useful than “consider”, and shorter.

Words that go in the bin. seamless, robust, leverage, utilize, powerful, intuitive, delightful, simply, just. Each one asks the reader to take on trust a quality the sentence has not demonstrated. simply and just do something worse: they tell someone who is stuck that their problem is easy.

ensure is not a rule. “Ensure sufficient contrast” names no ratio, no tool, nobody responsible, and no consequence. Say which ratio, or say who checks.

This site is written to the same rules, plus three of its own. They are here rather than in a private style guide because a contributor writing a new component page needs them, and because a design system that publishes its components and hides its voice has documented half of itself.

A rule true of the whole system lives in exactly one place. Sentence case is a fact about Persona, not a fact about Badge, so it is on this page and a component page links here.

A rule repeated per component stops being read. A reader who opens three pages and meets the same paragraph three times learns to skip that section, including on the page where it finally says something specific.

A sentence belongs on a component’s page when it carries something only true of that component: a count, a prop name, a constraint, a consequence, an absence. Swap the subject for a different component and read it again. If it survives, it belongs somewhere more central, or nowhere.

The most useful sentences on this site are the ones that explain why something is not there — that resize is CSS rather than a prop, that a plain Card still exists beside CardV2, that this system claims no WCAG conformance level. A reader arrives more often with “why can’t I” than “what is”.

A rule with no reason anywhere near it is a rule the reader has to take on faith, and the first time it’s inconvenient they will drop it. “Use one primary button per view” is an instruction. “Two of them cancel each other out, because emphasis is relative” is why it holds, and it also tells the reader what to do in the case the rule didn’t cover.

Documentation that asserts without explaining reads as generated, whoever wrote it.