Guides and Sample Code


macOS Human Interface Guidelines

On This Page

Starting and Stopping

Start Instantly

Users expect to benefit from your app as soon as they install it. Meet this expectation by helping users accomplish things right away.

Avoid requiring users to supply a lot of setup information before they can do anything else. Instead, let users get started right away and defer asking for setup or configuration information until it’s actually needed. As much as possible, query sources such as system preferences and Contacts so that you can avoid asking users for information they may have already supplied elsewhere. When you must ask users for information, try to give them something in return for each piece of information they provide.

Think twice before providing an onboarding experience. (Onboarding introduces an app’s features and explains how to perform common tasks.) Before you consider onboarding, make every effort to design your app so that all its features and tasks are intuitive and easily discoverable. Onboarding is not a substitute for good app design. If you still feel that onboarding is necessary, follow these guidelines to create a brief, targeted experience that doesn’t get in the user’s way.

  • Give users only the information they need to get started. A good onboarding experience shows users what to do first or briefly demonstrates a few of the features that most users are interested in. If you give too much information to users before they have a chance to explore your app, you make users responsible for remembering details they don't need right away and you may send the message that your app is hard to use. If additional help is needed for specific tasks, provide that help only when the user is performing those tasks.

  • Use animation and interactivity to engage users and help them learn by doing. Add text sparingly and only if it enriches the experience; don’t expect users to read long passages. For example, don’t describe how to perform a simple task when you can use animation to show users what to do. To lead users through a more complex task, you might add transient overlay views that briefly describe each step as the user is about to do it. As much as possible, avoid displaying screenshots of your app because they’re not interactive and users can confuse them with app UI.

  • Make it easy to dismiss or skip the onboarding experience. After users view the onboarding experience, they probably don’t want to view it again; other users may not want to view it at all. Be sure to remember the choice users make and don’t force them to make it every time they open your app.

Establish intelligent default settings. Determine how most users are likely to use your app and set the default configuration accordingly. When you gauge the needs of your user audience accurately, it’s rarely necessary for users to adjust the default settings in your app’s preferences.

Make sure the functionality in your app is easily discoverable. When the usage of your app is obvious, users feel empowered and they can be successful right away. Although you should make help content available in case users need it, you don’t want users to feel that they must read a manual before they can begin using your app. (For guidelines on how to provide good help content, see User Assistance.)

Don’t ask users to restart. After installation, your app should be ready for immediate use. If your app relies on a restart to work correctly, rethink its design.

Always Be Prepared to Stop and to Restart

Most users don’t distinguish between closing an app’s main window and quitting the app. Unless there are good reasons for drawing attention to the difference, it’s best to respond to both events in the same way. Follow these guidelines to give users a good experience as they leave and return to your app.

Decide whether users need to explicitly quit your app. If your app displays only a single window, it's often appropriate to quit automatically when users close the window.

Reopen in the same state in which users left your app. Preserving user-modifiable settings, such as window dimension and location, enhances users’s perception of the stability of your app. macOS makes state-preservation easy to achieve when you enable Resume. To learn how to support Resume in your code, see User Interface Preservation.

Support Auto Save and Versions, if appropriate. Users expect their content to be saved continuously and mostly without their intervention. If users can create documents in your app, be sure to opt in to Auto Save so that they can rely on these behaviors in your app. (To learn more about how these technologies should work in your app, see Auto Save and Versions.)