Returnless UI

Actionable language ​

Users use Returnless to get things done. Content should be written and structured to help them understand and take the most important actions.

Headings and subheadings ​

Headings and subheadings are titles and subtitles that refer to sections of the interface.

Basic structure ​

Headings and subheadings should be:

Informative and descriptive

  • Highlight the most important concept or piece of information for users
  • Help users understand what they'll find in the section below

Concise and scannable

  • Use simple, clear language
  • Keep headings to a single sentence
  • Avoid using punctuation such as periods, commas, or semicolons
  • Write in sentence case (capitalize the first word and proper nouns only)

Articles ​

Whether to use articles ("the", "a", "an") in headings and subheadings depends on the type of message.

Conversational headings ​

For more conversational areas in the product, like empty states or onboarding, use articles. It makes the language more approachable and helps people to understand new, complex concepts.

Microcopy headings ​

For labels, titles, and microcopy, avoid articles to keep content short and actionable. This increases readability and encourages immediate action.

Sentences ​

Start sentences with imperative verbs when telling users what actions they can take (especially when introducing something new).

When a user reads a sentence that starts with an imperative verb it should sound like they're being instructed what to do. Don't use permissive language like "you can".

Buttons ​

Buttons need to be clear and predictable. Users should be able to anticipate what will happen when they select a button. Never mislead someone by mislabelling a button.

Buttons should always lead with a string verb that encourages action. To provide enough context to users, use the {verb} + {noun} content formula on buttons except in the case of common actions like "Done", "Close", "Cancel", or "OK".

  • Always write button text in sentence case, which means the first word is capitalized and the rest are lowercase (unless a term is a proper noun).
  • Avoid unnecessary words and articles such as “the,” “an,” or “a.”

Links need to be clear and predictable. Users should be able to anticipate what will happen when they select a link. Never mislead someone by mislabelling a link.

  • Links should never use “click here” or “here” as link text.

Links in full sentences shouldn't link the entire sentences, only the text that describes where users go when they select a link.

It's better for internationalization to have only single term or small parts of phrases linked. Linking a full phrase is problematic because the word order might change, which would break the link into two parts.

Links that aren't in full sentences should use the {verb} + {noun} pattern and not be punctuated, except question marks.

When linking out the documentation from help text in the panel, link to relevant keywords. In general, don't add another sentence starting with "Learn more...", because it's repetitive and takes up unnecessary space.

Only add a "Learn more..." sentence if the help text addresses more than one concept, each of which could be linked to their own help doc. In that situation, pick the most appropriate link and contextualize it with "Learn more...".

Confirmation ​

Confirmations are presented for actions that can't be undone or are difficult to undo.

Confirmation messages should:

  • Always give users the option to either confirm or cancel their action
  • Be used for a single, primary task
  • Keep body content to one line of text and not use more than two calls to action

Confirmation titles should:

  • Ask if users want to continue, using a concise {verb}+{noun} question
  • Be one sentence and avoid using punctuation, except question marks
  • Avoid articles (the, a, an) to keep content short and actionable
  • Be written in sentence case (the first word is capitalized, and the rest is lowercase)

Confirmation body content should:

  • Clearly explain if the action is irreversible or difficult to undo, using plain language
  • Be concise: use only one like of text. Don't start the sentence with "Are you sure?"

Confirmation primary and secondary actions should:

  • Be clear and predictable: users should be able to anticipate what will happen when they click a button
  • Scannable: avoid unnecessary words and articles such as "the," "an," or "a"

Since confirmation messages are placed in modals, the call to action in the title is in close context to the buttons. Because of this, the call to action text on the buttons doesn't have to follow the {verb}+{noun} pattern. Instead, one word calls to action can be used ,for example, "Delete" or "Cancel".

Deletions

Before users can delete objects, we present them with a confirmation message that has two calls to action, one to "Cancel" and one to "Delete". We keep it short and don't use the {verb}+{noun} button copy.

Directional language ​

In the same way that links should never say "click here", avoid using directional language such as "above/below", or "right/left".

Directional language is confusing and unhelpful when spoken aloud by a screen reader It creates challenges for internationalization (for example, right to left languages) and can conflict with mobile design patterns.

Directional language often indicates a lack of visual copy hierarchy. Whenever possible, keep instructional copy and related actions close together so that directional language isn't needed.

Save vs. done ​

Use "Save" when a change is saved immediately to the database and "Done" for deferred saves.

Saving immediately to the database ​

Use "Save" as the default for any action that saves immediately to the database.

Deferred saves ​

Sometimes, when users confirm a set of changes inside a modal or sheet, these changes are applied as unsaved changes to the current page. In other words, that changes made weren't immediately saved to the database. When this happens, don't use the verb "Save" as the call to action because it would be misleading.

Use the adjective "Done" for deferred saves. When the modal or sheet closes, the users can save all the changes they made.

Most deferred saves happen when confirming changes in Add, Edit, Manage, and Select modals and sheets.

Datepickers ​

Use the adjective "Done" for datepickers.

Close vs. Accept ​

Use the verb "Close" when users need to confirm they've read something, but aren't required to legally accept terms of service before continuing. For example, use "Close" when presenting a security notification in a modal.

Don't use "OK". "OK" is an exclamation, not an action. When users click the "Close" button, they're not saying "OK", they're doing a specific action.

Use the verb "Accept" when terms of service require legal confirmation before users can continue.

Close vs. Cancel ​

Use the back arrow button as the call to action for modals and screens when:

  • The content is in a view-only state

Don't use "Close" as the call to action when there's the option for users to:

  • Make any changes to the modal or screen
  • Confirm they've read something or accept terms of service

Use "Cancel" as the option for users to back out of any changes made on a page or modal. When the cancel button is pressed, changes automatically get discarded. "Cancel" is often paired with "Save" and "Done" actions (and is always placed on the left).

Select vs. choose ​

Use the verb "Select":

  • When telling users to pick something from a limited number of options of the same kind
  • When users need to make an easy or obvious decision that doesn't require deep reflection or analysis
  • For defined lists and dropdown menus
  • When users are given the option to pick from a list of already existing objects

Use the verb "Choose" when:

  • Encouraging users to make a decision that is more subjective, strategic, emotional, or open-ended
  • Users have to pick from a large inventory of items, or options that require strategic decision-making, like pricing plans

Edit vs. manage ​

Use the verb "Edit" when you can change the input of a field (letters, numbers, properties). Place as link text next to the field or area that is being edited. There's no need for a noun unless it's unclear what's being edited.

Use the verb "manage" at a higher level to convey that multiple actions can be done, or sections and settings can be updated. Pair this verb with a noun if it's in a button or if it's unclear what is being managed.

Change vs. switch ​

Use the verb "change" when users can replace an option, but not edit it. For example, they can change an image or theme, but the action doesn't include editing its properties. Place as link text next to the field or area that is being changed. There's no need for a noun unless it's unclear what's being changed.

Use the verb "switch" when it's important for users to know what they're switching between, like accounts, or modes. When the switch happens, the previous option is turned off, logged out, or deactivated. Always pair with a noun to prevent confusion.

Create vs. add ​

Use the verb "create" when you're encouraging users to generate something from scratch.

Use the verb "add" when you're encouraging users to bring something that already exists in the application.

View vs. see ​

Use the verb "view" when you're encouraging users to go to a specific page or section for more details, or to reveal more information. Use "view" in buttons, calls to action, and link text.

Use the verb "see" in more general, conversation descriptions without a specific call to action.

Need vs. must ​

Use the verb "need" when you're telling users something they're required to do or should do.

Export vs. download ​

Use "export" as the call to action when users need to transfer data from the application and convert it into a different format.

Use "download" as the call to action when users need to copy data (of the same format) from the application to a computer system.

Import vs. upload ​

Use "import" as the call to action when users need to transfer data and convert it into a different format, so it can be used in the application.

Use "upload" as the call to action when users need to copy data of the same format from a computer system to the application.