User Interface Text Guidelines

Concise

Don't add text if it's not needed.

Use as few words as possible.

Focus on users' tasks; write only what is necessary for users to complete them.

Avoid unnecessary and redundant information.

Keep tasks short.

Conversational

Use language you would use with a business colleague. Think business casual.

Contractions are OK.

Focus on the user—write from the users' perspective to help them accomplish tasks.

Know your user—end user tasks can have a more informal tone than administrator tasks.

Direct

Use plain English.

Avoid buzzwords, jargon, and words you wouldn't say in person.

Use active voice; avoid complex verb structures.

When naming buttons, name the action that the button will trigger, especially if it is potentially destructive. For example, in a warning message dialog box, Delete All and Cancel buttons are clearer than OK and Cancel buttons.

Use please sparingly

Avoid please except when prompting the user to do something inconvenient or when the system is to blame for the situation. For example: The export process may take time. Please wait until the process completes.

Avoid sorry

Use sorry only in error messages that result in serious problems for the user (for example, data loss, the user cannot continue to use Salesforce, or the user must get help from Customer Support to continue). Avoid apologizing if the issue occurred during normal Salesforce functions. For example:

Avoid

Sorry, but you must supply a search string of at least two characters.

Better

Sorry, but you must exit and log in again.

Before you use sorry in user interface text, ask yourself if we could change the design to avoid the situation altogether. It's better to design a solution that doesn't require an apology.

Whenever possible, phrase sentences positively rather than negatively.

Negative

The mini view doesn't display if the record in the detail view doesn't have any records associated with it.

Positive

The mini view only displays if the record in the detail view has records associated with it.

Use consistent terminology

Glossary terminology guidelines apply to user interface text.

Use consistent capitalization

Capitalization guidelines apply to user interface text.

Use title-style capitalization for button names, such as Clone or Run Report. Don’t use ending punctuation in button labels.

In UI text, most object names are referenced from hard-coded labels that are capitalized. In this case, use the capitalization found in the user interface. For example: Select Text Area (Long) and click Next.

Use consistent punctuation

See individual punctuation entries in this guide for details. You can also refer to the Microsoft User Interface Text website for additional guidelines.

Refer to user interface elements by name

Refer to user interface elements using the element's exact label (including any end punctuation, such as an ellipsis). For example: Click Add... to browse for files on your local computer.

Avoid developer-focused terminology, unless appropriate

Most users of the Salesforce user interface are business users or non-technical administrators.

Use terminology that is familiar to business users within the context of Salesforce. For example:

• Avoid: database table and row
• Better: object and record

If technical information is necessary, explain it using general terms for a business user and then add more specific technical information. For example:

• Avoid: You can't change the organization-wide default settings for an object if the object’s Share table is referenced in an Apex script. For example, if there is a reference to AccountShare in a script, the sharing model for Accounts cannot be modified.
• Better: You can't change an object's organization-wide default settings if an Apex script examines the object's sharing entries. For example, if a script retrieves the users and groups who have sharing access on an account (represented as the AccountShare object in the code), you can't edit the organization-wide sharing default settings for accounts.

(This example is from the Salesforce Help, so it’s wordier than typical user interface text, but the same principles apply.)

See Mobile Interfaces and Documentation.

Ensure user interface messages have a consistent tone, style, and language.

Label messages

If the message design doesn't include a messaging icon, prefix the message with the appropriate messaging word (required for 508 compatibility for visually-impaired users that use a screen reader).

• Error: For error messages
• Warning: For warning messages

Provide clear instructions for users to correct errors

Give the user clear instructions on how to correct the error. For example: This Self-Service username already exists. Choose a unique Self-Service username.

Avoid phrasing that blames the user or implies user error. Passive voice can be appropriate in messages to achieve this purpose. For example: No number was specified. Enter a number and try again.

See Style and Tone.

Use consistent terminology

Use terminology that is consistent with the rest of the user interface. Follow the Glossary.

When you write for mobile, be consistent with the Web application when possible.

Note that on mobile devices, terminology differs by operating system. See Mobile Interfaces and Documentation.

Use consistent capitalization and punctuation

Follow the style guide in writing message headers, message details, and button labels; see Message and Buttons.

Follow these guidelines when designing pages that incorporate user interface text and other user assistance elements, such as field-level help.

Avoid large blocks of text

• Keep only one topic per paragraph.
• Avoid long, complex sentences. Write so readers only have to read the sentence once.
• Keep your average sentence length less than 17 words.
• Make smooth transitions, using words and phrases such as also, in addition, moreover, consequently, however, although, for example, next, first, finally, and in contrast.
• In running text, generally avoid a string of one-sentence paragraphs.

Design text for easy scanning

• Users often scan, rather than read, text, so design the information for scanning.
• Place the most important points first and then add supplemental information if necessary.
• If you have multiple pieces of information to convey, use bulleted lists for easier scanning.
• Users read actionable text before explanatory text, so place actions first and then add explanations if necessary.
• Assume that once users have decided what to do, they immediately stop reading and do it.
• Use See Also links at the end of topics to refer users to related information. Avoid inline links whenever possible.

Avoid special visual treatment on user interface elements

Don't use special styles or punctuation (such as quotation marks, bold, or italics) to refer to user interface elements or link text. However, use bold text when referring to data that the user entered (such as an account name). For example, Here is the sharing for My Big Opp.

Give information “just-in-time”

Introduce required conceptual information only when the user is engaged in the task that requires those concepts.

Explain business rules or constraints only when the user encounters their constraining effects.

Put instructions next to the corresponding user interface element

Avoid putting all instructions at the top of the page.

Divide dense instructions and place them next to the corresponding user interface elements or in field-level help hover text.

Avoid referring to the location of items on a page

Don't use below, following, above, or other such words to refer to the placement of user interface elements on a page.

In UI text, provide a direct link to a described page instead of a sequence of menu options.