Grammar and mechanics

Consistent language helps users navigate apps confidently. Like visuals, words that blend seamlessly into the interface strengthen our identity and build trust.

    Basics

  • Use American spellings: license, organize, synchronize, center, dependent, favorite.
  • Choose simple tenses. For most cases, prefer was over has been.
Simple and succinct success message title.

Do

Simplify your message titles to "Task created," "Payment failed," etc.

Overly complex success message title.

Don't

Avoid indirect present perfect tense, and skip redundant successfully.

    Use sentence case

  • It's easier to maintain, read, and understand.
  • Apply to all interface elements, including buttons and headers, unless it's an exception.
  • Capitalize the first letter of a sentence, UI label, proper nouns, days, months, etc.
  • Don't capitalize the names of features, such as column view or post function.
    • A feature is anything that does something within an app. While some features might seem special, their significance is subjective and often perceived differently by users.
  • Don't capitalize project, scope, sprint, or iteration, as those are common nouns.
  • Don't capitalize a in the app when referring to your product. We're not braggy.
Example of a consistently used sentence case.

Do

Consistent use of sentence case makes information easier to follow and understand.

Example of combining sentence and title case.

Don't

Inconsistent capitalization makes apps seem sloppy and unprofessional.

    Exceptions to sentence case

  • If a term comes from another ecosystem, respect its original spelling.
  • Use all caps to write "Save PDF" or "Export CSV." Add lowercase s for plurals, like JPGs.
  • Use all caps for other necessary acronyms.
  • Use all caps for text in distinct UI elements such as lozenges or dropdown group labels.
Examples of lozenges and dropdown group labels written in all caps.

    Terminal punctuation

  • Aim for short tooltips and inline messages without periods.
  • Use periods when there's more than one sentence or other punctuation marks.
  • Use periods in sentences followed by links ("New tokens available. Go to Fuegokit").
  • Don't use terminal punctuation to end those links.
  • Don't use terminal punctuation for titles and headings.
Short tooltip that doesn't require terminal punctuation.

Do

Omitting periods helps short text elements flow smoothly and look informative.

Tooltip consisting of 2 sentences, requiring terminal punctuation.

Do

Consistency requires terminal punctuation for multiple and complex sentences.

    Other punctuation

  • Improve clarity with an Oxford comma to join independent clauses or list multiple items.
  • Use quotation marks only to quote someone. To distinguish text, use italics or bold.
  • Reserve ellipses to indicate an action in progress, like Loading….
  • Use colons to introduce a bulleted list in body text but not after headings.
  • Avoid semicolons; use commas or split your sentence into two.
  • Don't overdo it with exclamation marks! Too many, or too often, are likely to be annoying!
  • Avoid parentheses except for definitions, as they create ambiguity and disrupt scanning.
Do
4 examples of simple and efficient content writing without parentheses.

Make it easy to grasp important details and what action to take.

Don't
4 examples of unnecessary parentheses use across the interface.

Don't break the flow or make people decide if singular or plural is more relevant.

    Dashes and hyphens

  • Use hyphens (-) to join words (well-known, high-quality, etc.) or indicate a range (0-10).
  • Choose unhyphenated spelling if both are correct (email, post function, subtask, etc.).
  • Use em dashes (—) to break up a sentence—and don't add spaces.
  • Use em dashes sparingly. Often it's better to start a new sentence.
  • Don't use ampersand (&) in body text unless it's a part of the product name.
  • Limit ampersands in other UI elements. They are less accessible than and.

    Contractions

  • Use simple contractions (you'll, it's, there's, etc.) to sound natural.
  • Use negative contractions (can't, don't, won't, etc.) most of the time.
  • Consider spelling out negatives when overlooking not could have critical implications.
  • Spell out noun + verb contractions. Browser is reads better than browser's.
  • Avoid using complex phrases such as should have and their contractions like should’ve.

    Abbreviations and acronyms

  • Write for example or such as for more conversational copy.
  • Use e.g., (followed by a comma) only when space is minimal, such as in placeholders.
  • Use etc. sparingly.
  • If an acronym is necessary, define it first using parentheses.
    • The Universal Plugin Manager (UPM) provides a powerful and user-friendly interface. Through the UPM, you can browse, try, and buy apps.
  • Don't explain common acronyms that are not app-specific, such as PDF, HTML, or FAQ.

    Numbers and numerals

  • Use numerals to improve scanning for specific data.
  • Use numerals for dates and times, units, steps, instructions, and formulas.
  • In general contexts, use numerals for 2 and above.
  • In general contexts, write zero and one in words to avoid confusion with o and l.

    UI references

  • Aim to write about values and capabilities, not UI elements.
  • When a UI element reference is necessary, match the case and punctuation exactly.
  • Use bold for buttons, checkboxes, fields, labels, options, and toggles.
  • Use italics for page and tab names, headings, and dialog titles.
  • Don't add terms like button or option. Having a clear context makes them redundant.
  • Avoid saying above, below, here, etc., as those are relative and inaccessible.
Clear, direct instructions help people quickly understand what to do:
"Select Hide parent tasks to see only tasks matching your criteria."
Redundant terms complicate things:
"Select the Hide parent tasks option below to see only tasks matching your criteria."

Do you have feedback for us? Share it on the #design-systems channel in Slack.