Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks
On This Page

Terminology and Wording

Text is prevalent throughout the macOS interface for such things as button names, menu labels, dialog messages, and help tags. Using text consistently and clearly is a critical component of UI design.

In the same way that it’s best to work with a professional graphical designer on the icons and images in your app, it’s best to work with a professional writer on your app’s user-visible text. A skilled writer can help you develop a style of expression that reflects your app’s design, and can apply that style consistently throughout your app.

For guidance on Apple-specific terminology, the writer should refer to the Apple Style Guide. That document covers style and usage issues, and is the key reference for how Apple uses language.

For issues that aren’t covered in the Apple Style Guide, Apple recommends three other works: The American Heritage Dictionary, The Chicago Manual of Style, and Words Into Type. When these books give conflicting rules, The Chicago Manual of Style takes precedence for questions of usage and The American Heritage Dictionary for questions of spelling.

Use User-Oriented Terminology

Almost all apps need to use some words to communicate with users, even if the only words are in button labels. It’s important to choose all of your app’s words carefully so that you can ensure that your communication with users is unambiguous and accurate.

In general, avoid jargon. Above all, you want to use the terminology your users are comfortable with. If your app targets sophisticated users who frequently use a set of specialized, technical terms, it may make sense to use these terms in your app. But if your user audience consists of mostly novice or casual users, it’s usually better to use simple, widely understood terms. For example, the Parental Controls preferences pane uses simple, straightforward language to describe the feature and explain what the user can do.

image: ../Art/no_jargon_2x.png

Avoid developer terms. As a developer, you refer to UI elements and app processes in ways that most of your users don’t understand. Be sure to scrutinize the UI and replace any developer terms with appropriate user terms. For example, Table 11-1 lists several common developer terms, along with equivalent user terms you should use if you need to refer to these items in the UI.

Table 11-1Some developer terms and their user term equivalents

Developer term

Equivalent user term

Cursor

Pointer

Data browser

Scrolling list or multicolumn list

Dirty document

Document with unsaved changes; unsaved document

Error message

Alert message; message

Focus ring

Highlighted area; area ready to accept user input

Control

Button, checkbox, slider, menu, and so forth.

Launch

Start

Mouse-up event

Click

Override

Take the place of; take precedence over

Reboot

Restart

Sheet

Dialog

String

Text

String length

Number of characters

Use proper Apple terminology. If you need to refer to standard parts of the UI or to system features, use the terms that Apple defines. For example, to describe the use of a checkbox in your UI, tell the user to “select" the checkbox, not to "check,” “click,” or “turn on” the checkbox. If you mention how to start your app by clicking the app icon in the Dock, be sure to capitalize “Dock.” You can learn more about Apple terminology by reading Apple Style Guide.

Create Succinct Labels for UI Elements

Make labels for UI elements concise and easy to understand, but don’t sacrifice clarity for space.

When the context of a label is clear, avoid repeating the context in the label. For example, within the context of a document-modal dialog, it’s clear that the dialog acts upon a file or document, so there’s no need to add the words “File” or “Document” to the Format pop-up label. Similarly, users understand that the items in an app’s Edit menu act upon the current editing context, so there is seldom a need to make this explicit in the menu item names.

Use the correct capitalization style. The capitalization style to use in the label for an interface element depends on the type of element. For information on the proper way to capitalize the words in labels for different types of interface elements, see Use the Right Capitalization Style in Labels and Text.

Use an ellipsis in the name of a menu item or button that produces a dialog. The ellipsis (…) indicates that the user must take further action to complete the task. The dialog title should be the same as the menu command or button label (except for the ellipsis) used to invoke it. To learn more about using an ellipsis, see Use an Ellipsis When More Input Is Required.

Use the Right Capitalization Style in Labels and Text

All interface element labels should use either title style capitalization or sentence style capitalization.

Title style capitalization. Capitalize every word except:

  • Articles (a, an, the)

  • Coordinating conjunctions (and, or)

  • Prepositions of four or fewer letters, except when the preposition is part of a verb phrase, as in “Starting Up the Computer.”

However, always capitalize the first and last word, even if it is an article, a conjunction, or a preposition of four or fewer letters.

Sentence style capitalization. Capitalize the first word, and make the rest of the words lowercase, unless they are proper nouns or proper adjectives.

Element

Capitalization style

Examples

Menu titles

Title

Highlight Color

Number of Recent Items

Location

Refresh Rate

Menu items

Title

Save a Version

Add Sender to Contacts

Log Out

Make Alias

Go To…

Go to Page…

Outgoing Mail

Push buttons

Title

Add to Favorites

Don’t Save

Set Up Printers

Restore Defaults

Set Key Repeat

Toolbar item labels

Title

Reading List

Zoom to Fit

New Folder

Reply All

Get Mail

Labels that are not full sentences (for example, group box or list headings)

Title

Mouse Speed

Total Connection Time

Account Type

Options that are not strictly labels (for example, radio button or checkbox text), even if they are not full sentences

Sentence

Enable polling for remote mail

Cache DNS information every ___ minutes

Show displays in menu bar

Maximum number of downloads

Dialog messages

Sentence

Checking for new software…

Are you sure you want to quit?

Use Contractions Cautiously

When space is at a premium, such as in a pop-up menu, you can use contractions, as long as the contracted words aren’t critical to the meaning of the phrase. For example, a menu could contain the following items:

  • Don’t Allow Printing

  • Don’t Allow Modifying

  • Don’t Allow Copying

In these examples, the contraction doesn’t alter the operative word for the item. If a contraction does alter the significant word in a phrase, such as “contains” and “does not contain,” it’s clearer to avoid the contraction.

As much as possible, avoid using uncommon contractions that may be difficult to interpret and localize. In particular:

  • Avoid forming a contraction using a noun and a verb, such as in the sentence "Apple's going to announce a new computer today."

  • Avoid using less common contractions, such as "it'll" and "should've."

Use Abbreviations and Acronyms That Users Understand

Abbreviations and acronyms save space in the UI, but they can be confusing if users don't know what they mean. Conversely, some abbreviations and acronyms are better known than the words or phrases they stand for, and an app that uses the spelled-out version can seem out-of-date and unnecessarily wordy.

To balance these two considerations, gauge an acronym or abbreviation in terms of its appropriateness for your app's intended users. To help you decide whether to use a specific abbreviation or acronym, consider the following questions:

  • Is the acronym or abbreviation one that your users understand and feel comfortable with? For example, everyone uses CD as the abbreviation for compact disc, so even apps intended for novice users can use this abbreviation.

    On the other hand, an app intended for users who work with color spaces and color printing can use CMYK (which stands for cyan magenta yellow key), even though this abbreviation might not be familiar to a broader range of users.

  • Is the spelled-out word or phrase less recognizable than the acronym or abbreviation? For example, many users are unaware that Cc originally stood for the phrase carbon copy (that is, the practice of using carbon paper to produce multiple copies of paper documents). In addition, the meanings of Cc and carbon copy have diverged so that they are no longer synonymous. Using carbon copy in place of Cc, therefore, would be confusing to users.

    For some abbreviations and acronyms, the precise spelled-out word or phrase is equivocal. For example, DVD originally stood for both digital video disc and digital versatile disc. Because of this ambiguity, it's not helpful to use either phrase; it's much clearer to use DVD.

If you use a potentially unfamiliar acronym or abbreviation in the user help book for your app, be sure to define it when you first use it. To learn more about the help technologies available to your app, see User Assistance.

Use an Ellipsis When More Input Is Required

When it appears in the name of a button or a menu item, an ellipsis character (…) indicates to the user that additional information is required before the associated operation can be performed. Specifically, it prepares the user to expect the appearance of a window or dialog in which to make selections or enter information before the command executes.

Because users expect instant action from buttons and menu items, it's important to prepare them for this different behavior by appropriately displaying the ellipsis character. Use the guidelines and examples here to help you decide when to use an ellipsis in menu item and button names.

Use an ellipsis in the name of a button or menu item when the associated action:

  • Requires specific input from the user.

    For example, the Open, Find, and Print commands all use an ellipsis because the user must select or input the item to open, find, or print.

    You can think of commands of this type as needing the answer to a specific question (such as "Find what?") before executing.

  • Is performed by the user in a separate window or dialog.

    For example, Preferences, Customize Toolbar, and App Store all use an ellipsis because they open a window or dialog in which the user sets preferences, customizes the toolbar, or shops for new apps.

    To see why such commands must include an ellipsis, consider that the absence of an ellipsis implies that the app performs the action for the user. For example, if the Customize Toolbar command does not include an ellipsis, it implies that there is only one way to customize the toolbar and the user has no choice in the matter.

  • Always displays an alert that warns the user of a potentially dangerous outcome and offers an alternative.

    For example, Restart, Shut Down, and Log Out all use an ellipsis because they always display an alert that asks the user for confirmation and allows the user to cancel the action. Note that Close does not have an ellipsis because it displays an alert only in certain circumstances (specifically, only when the document or file being closed has unsaved changes).

    Before you consider providing a command that always displays an alert, determine if it's really necessary to get the user's approval every time. Displaying too many alerts asking for user confirmation can dilute the effectiveness of alerts.

Don't use an ellipsis in the name of a button or menu item when the associated action:

  • Does not require specific input from the user.

    For example, the New, Save a Version, and Duplicate commands don't use an ellipsis because either the user has already provided the necessary information or no user input is required. That is, New always opens a new document or window, Save a Version saves a snapshot of the current document, and Duplicate creates a new copy of the current document.

  • Is completed by the opening of a panel.

    A user opens a panel to view information about an item or to keep essential, task-oriented controls available at all times. A command to open a panel, therefore, is completed by the display of the window and should not have an ellipsis in its name. Examples of such commands are Get Info, About This App, and Show Inspector. To learn more about panels, see Panels.

  • Occasionally displays an alert that warns the user of a potentially dangerous outcome.

    If you use an ellipsis in the name of a button or menu item that only sometimes displays an alert, you cause the user to expect something that will not always happen. This makes your app's user interface inconsistent and confusing. For example, even though Close displays an alert if the user has never named the current document, it does not display an alert at other times, and so it does not include an ellipsis.

An ellipsis character can also show that there is more text than there is room to display in a document title or list item. In general, it’s best to use an ellipsis to take the place of text in the middle of a title or name, because this preserves the beginning and end of the text, which tend to be the most recognizable parts.

Use a Colon to Connect a Label with Controls

Use the colon character (:) in text that introduces and provides context for controls. The text can describe what the controls do or a task the user can perform with them. The combination of introductory text, colon, and controls forms a visually distinct grouping that helps users find the controls that apply to a particular task and understand what the controls do.

A colon implies a direct connection between the descriptive text and a particular control or set of controls, so it doesn’t belong in the text that appears in:

  • A control label, such as a push button name or a command pop-down menu title

  • Menu items (unless the colon is part of a user-created menu item) and menu titles

  • Tab and segmented controls

  • Table view column headings

The colon is a good way to associate introductory text with related controls, but it’s not the only way to do so. For example, you might use a tab view to display different groups of related controls. For guidelines on how to use this view, see Tab View.

Don’t use a colon in the text that serves as a group box title. (A group box is a control that lets you create a visually distinct area of content, such as the set of screen corner controls shown here.) In these cases, the group box itself takes the place of the colon and makes explicit the relationship of the introductory text to the controls that follow it. To learn more about the group box control, see Group Box.

image: ../Art/group_box_title_2x.png

Use a colon in introductory text that precedes a control or set of related controls that aren’t in a group box. The text can be a noun or phrase that describes either the target of the control or the task the user can perform. The following examples illustrate some variations on this arrangement of text and controls:

  • Use a colon in text that precedes a control on the same line.

    image: ../Art/colon_preceding_control_2x.png
  • Use a colon in text that precedes the first control in a vertical list of controls.

    image: ../Art/colon_before_control_list_2x.png

    Use a colon in text that precedes the first control in a horizontal list of controls.

    image: ../Art/colon_before_horizontal_2x.png
  • Use a colon in introductory text that appears above a control.

    image: ../Art/colon_above_control_2x.png
  • Use a colon in checkbox or radio button text that introduces a second control. (Note that if the text describing a checkbox or radio button state doesn’t introduce a second control, it should not include a colon.)

    image: ../Art/colon_after_checkbox_2x.png

A colon is optional before a control that is part of a sentence or phrase. This guideline is flexible because it depends on how much of the text follows the control and how the sentence or phrase can be interpreted. Consider the specific combination of text and controls and the overall layout of your window as you decide whether to use the colon in the following situations.

If none of the text follows the control, then the control's value supplies the end of the sentence or phrase. A colon is recommended in this case, because this is another variation of the guideline to include a colon in text that precedes a control. For example, the term “Genie effect” completes the sentence that begins “Minimize windows using:”

image: ../Art/colon_after_phrase_2x.png

If a substantial portion of the sentence or phrase follows the control, a colon is optional.

image: ../Art/no_colon_in_sentence_2x.png

Similarly, the colon is optional when some text follows the control, but that text does not represent a substantial portion of the sentence or phrase. To help you decide whether a colon is appropriate in these cases, determine if the presence of a colon breaks the sentence or phrase (including the value of the control) in an awkward or unnatural way.

Remove Extraneous Space Between Sentences

If any part of your app's UI displays two or more sentences in a paragraph, be sure to insert only a single space between the ending punctuation of one sentence and the first word of the next sentence.

Although much of the text in an app's UI is in the form of labels and short phrases, app help, alerts, and dialogs often contain longer blocks of text. Examine these blocks of text to make sure that extra spaces don't appear between sentences.