Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks
On This Page

Integrating with macOS

Use Standard UI Elements Correctly

macOS provides a wide range of built-in UI elements, such as controls, menus, and dialogs. When you use the system-provided elements correctly, you benefit in several important ways:

  • Users are familiar with the built-in elements, so they already know how to use them in your app.

  • The system-provided elements help ensure consistency within your app and with the rest of the system.

  • System-provided UI elements look and behave appropriately in various translucent contexts (such as light or dark vibrancy).

  • When there are changes to the system-provided controls, your app automatically acquires the updated appearance and behavior.

To realize these benefits, it’s crucial that you use the built-in elements correctly. Follow these guidelines as you use macOS UI elements in your app.

Don't assign new behaviors to built-in UI elements. It’s essential to use the system-provided elements according to the guidelines in this document. If you misuse macOS elements, you make your UI unpredictable and hard for users to figure out.

In general, don’t create a custom UI element that looks or behaves like a macOS UI element. If your custom element looks too much like a macOS element, users might not notice the difference, and they will be confused when it does not behave as they expect. Similarly, if your custom element behaves the same way a macOS element behaves, users will wonder what, if anything, is different about the custom element.

If you really need a new behavior, design a new element for it. Don’t redefine the behavior of an existing UI element. A custom UI element should provide users with a unique benefit that is difficult to achieve in any other way. If a new UI element doesn’t help users, they’re likely to feel that they wasted the time they spent learning about it.

Avoid replicating a UI element from another platform. Users aren’t necessarily familiar with other platforms, so you can’t assume that they recognize non macOS UI elements. It’s better to design a new UI element that coordinates with the design of your app and that supplies the precise behavior you need.

Don’t worry that using standard controls and views will cause your app to get lost in the crowd and be indistinguishable from other macOS apps. In reality, using standard UI elements lets you differentiate your app in ways that really matter to users, while giving them a stable foundation of consistency and familiarity.

Reach as Many Users as Possible

Early in the design process, start thinking about accessibility and worldwide compatibility so that the market for your app is as large as possible. It’s much easier to build in support for accessibility and internationalization from the beginning than it is to add support to a finished app.

macOS includes many assistive features, including VoiceOver, zoom, and full keyboard access mode. When your app is accessible, users can interact with it using the assistive device or feature of their choice. For example, in addition to speaking the UI to VoiceOver users, VoiceOver can also show the current focus and output to the user’s sighted colleagues. To learn more about supporting accessibility in your app, see VoiceOver and Accessibility.

Prepare your app for localization by internationalizing it.Internationalization involves separating user-visible text and images from your executable code. When you isolate this data, you make it easier to localize your app, which is the process of adapting an internationalized app for culturally distinct markets. To get more details about internationalization and localization, read Internationalization and Localization Guide.

Plan to localize visible UI elements. That is, make sure the UI elements in your app can be translated into other languages and otherwise adapted for use in other countries. When you use the Auto Layout, you can specify how text and other UI elements are related so that localizers don’t have to redesign your layout to accommodate different lengths of text. To learn more about the advantages of Auto Layout, see Cocoa Auto Layout.

Pay attention to the possible meanings of the graphics and symbols in your app. Make sure your graphics and symbols are unambiguous and inoffensive to all, or prepare to localize them. For example, if you use images of American holidays to represent seasons—such as Christmas trees, pumpkins, or fireworks—be sure to localize them for cultures that are not familiar with those holidays.

Be aware of the user’s locale preferences. In the Formats pane of Language & Text preferences, macOS helps users customize the way dates, times, and number-based data (such as monetary values or measurements) are displayed. Most APIs take these preferences into account when getting or formatting this type of information, so you shouldn’t have to perform custom formatting or conversion tasks.

Support different address formats. Don’t assume that all of the user’s contacts have addresses that are in the same format as the user’s address. Contacts helps users keep track of contacts all over the world by supporting different regions and allowing customization of any format. If you support or display Contacts data, be prepared to handle different address formats and postal code information.

Make your text easy to translate. Translating text is a sophisticated, delicate task. Avoid using colloquial phrases or nonstandard usage and syntax that can be difficult to translate. Carefully choose words for menu commands, dialogs, and help text. Be aware that text in U.S. English can grow up to 50 percent longer when translated to other languages.

Use complete sentences in string resources whenever possible. Grammar problems may arise when you concatenate multiple strings to create sentences; the word order may become completely different in another language, rendering the message nonsensical when translated. For example, word order in German sometimes places the verb at the end of a sentence. For more information on handling text in other languages, see Guidelines for Internationalization.

Consider text size, location, and direction when creating window layouts. Text size varies in different languages. Also, depending on the script system, the direction of the text may change. Most Middle Eastern languages read from right to left. Text location and alignment within a window should be easy to change.

As much as possible, identify the logical flow of content and use that to determine the layout of your UI. For example, the more important or higher level objects are usually placed near the upper left of a window that is designed for regions associated with left-to-right languages. In a version of the window that targets users who read right-to-left languages, it makes sense to reverse this layout. The more you can characterize user interface objects according to their logical, not visual, position, the more easily you can extend your app to other markets.

Provide a macOS Experience

People don’t experience your app in isolation. The user experience of your app is affected by myriad system features and the way people configure the macOS environment. For example, people may want to use your app in fullscreen mode, switching to other apps in different spaces. Or people might use an app extension to perform an action related to the task they’re accomplishing within your app. And some people may interact with your app using VoiceOver and an assistive input device.

The better an app integrates with macOS features and technologies, the more people will feel that the app belongs in the system. To learn how to adopt specific features and technologies, read sections such as App Extensions, iCloud, Game Center, and Notification Center.

At a minimum, be sure to meet people’s expectations by incorporating the items listed here.

  • Embrace vibrancy. Vibrancy is the sophisticated blending of foreground and background content that lets UI elements in Notification Center, window sidebars, menus, and popovers appear to absorb color from the content beneath them. Standard AppKit UI elements behave appropriately when they’re in a vibrant context.

    To support vibrancy in a custom view, use the NSVisualEffectView class.

  • Respect the single menu bar and avoid putting menu bars in your app's windows. macOS provides a single menu bar across the top of the screen, which gives apps a consistent location to display commands. Learn more about how your app interacts with the menu bar in Menu Bar Menus.

  • Integrate Spotlight. Spotlight helps users find things anywhere in the system, using criteria they define. Be sure to supply a Spotlight importer if your app uses a custom file format, so that users can easily search for the files your app creates. To learn more about supporting Spotlight in your app, see Spotlight.

  • Cooperate with the Dock to provide information and utility to users. The Dock is an essential part of macOS and users expect it to behave according to their preferences. At the very least, your app must not interfere with the Dock's position on the screen. Learn more about the Dock in The Dock.

  • Create high-quality icons. Part of the allure of macOS is the abundance of beautiful, high-resolution, meticulously rendered icons, including app icons. To learn about designing these icons, see Designing App Icons, Toolbar Items, and Sidebar Icons.

  • Respect the multilayered window environment of macOS. Be sure you know which types of windows your app should display and how they should look and behave (to start learning more, see About Windows).

  • Support modelessness. As much as possible, avoid forcing the user to complete the current task before they can do anything else. Use sheets and popovers to allow the user more freedom (for more information about sheets, see Using Document-Modal Dialogs (Sheets) and Popover). If you must use modes in your app, be sure to clearly communicate the current status and make it easy for users to get into and out of a mode.

  • Put the files your app creates in the proper locations. macOS defines particular locations for app-specific files, such as preferences and user-created documents. Don't place files associated with your app in arbitrary locations because they will clutter the file system and users won't know where to look for them. For guidelines on how to interact with the file system, see File System Overview.

  • Support the multiuser environment and fast user switching. macOS allows multiple users to use a single computer at the same time. With fast user switching, one user's login session is active while the sessions of other users continue to run in the background. In this multiuser environment, be sure to avoid relying on exclusive access to resources or assuming that there is only one instance of a per-user service running at any one time. For more information on how to support fast user switching, see Multiple User Environment Programming Topics.

  • Support gestures. Multi-Touch gestures in macOS let people use a trackpad to reveal Notification Center, switch to a different full-screen window or desktop, and show the desktop, among other things. For more information on supporting gestures in your app, see Gestures Can Enhance the User Experience.

  • Use display names. macOS lets users customize how file, directory, and app names are displayed. Be sure to respect the user's display name preference in your app (note that this also makes internationalization much easier). For more information about filename extensions, see Interoperability.

  • Don’t override the system-reserved keyboard shortcuts, and respect the Apple-recommended keyboard shortcuts. Users don’t generally distinguish between system-reserved and Apple-recommended keyboard shortcuts, but they tend to expect the shortcuts they know to enable specific behaviors regardless of the app they’re using. To learn more about supporting the keyboard appropriately, see Keyboard Shortcuts.

  • Support drag and drop. Drag-and-drop functionality is ubiquitous in macOS, making it one of the most appreciated and well-known features of the platform. Although it’s important to provide keyboard alternatives to drag-and-drop operations, it's essential to fully support this direct manipulation technology. To learn more about it, see Drag and Drop.

  • Support the Clipboard. Users rely on the Clipboard's contents remaining unchanged when they switch between apps. Be sure to support the Clipboard and implement cut, copy, and paste operations in your app. For more information on operations that access the Clipboard, see The Edit Menu and The Format Menu.