UI Element Guidelines: Windows

A window provides a frame for viewing and interacting with apps and data.

Although users tend to view most rectangular areas on the screen as “windows,” developers need to know about the main varieties of windows in OS X.

Examples of these window types are shown here.

../art/wn_fivewindowtypes.png

As you can see in the window examples above, the overall appearance of windows on OS X is subtle and understated. This muted appearance helps users focus on the content that’s important to them.

About Window Appearance and Behavior

A window consists of window-frame areas and a window body. The window-frame areas are the title bar and unified toolbar (and, in rare cases, a bottom bar). The window body extends from the bottom edge of the title bar (or toolbar, if present) to the bottom edge of the window (not including the bottom bar, if one is present). The window body represents the main content area of the window. For example, in a Mail message viewer window, the window body contains the mailbox list, the message list, and the selected message.

../art/wn_windowbody.jpg

The window-frame areas have a light gray gradient surface. OS X provides toolbar controls that are specifically designed to look good on the toolbar. To learn about the controls you can use in a toolbar, see “Window-Frame Controls.”

In the window body, content views (such as text or column views) display a white background by default; the surrounding window-body background is usually a shade of light gray.

Window Components

Every document and app window and panel has, at a minimum:

  • A title bar. Even if a window does not have an actual title (a tools panel, for example), it needs a title bar so that users can move the window.

  • A close button, so that users have a consistent way to dismiss the window.

A standard document window may also have the following additional elements that an app window or panel might not have:

  • Transient horizontal or vertical scroll bars, or both (if not all the window’s contents are visible)

  • Minimize and zoom buttons

  • A proxy icon and a versions menu (after the user has given a document a name and save location for the first time)

  • The title of the document

  • Transient resize controls

For example, the TextEdit document window shown here contains a title, a proxy icon, the close, minimize, and zoom buttons, and a scroller. You can’t see the resize controls in this window, because they are visible only when the pointer rests above a window edge. Similarly, you can’t see the versions menu because the document is not locked (and has not been recently edited) and the pointer is not resting in the title bar to the right of the document title.

Standard window parts

The TextEdit window shown above also includes an optional window element called the scope bar. A scope bar appears below the toolbar and allows users to narrow down a search operation or to filter objects or other operations by identifying specific sets of characteristics. To learn more about scope bars, see “Using a Scope Bar to Enable Searching and Filtering.”

Rarely, a window might display a bottom bar, which is a window frame area that extends below the main content area of the window body. A bottom bar contains controls that directly affect the contents and organization of the window, such as the add a buddy and chat controls at the bottom of the iChat window.

../art/wn_ichatbottombar_2x.png

Scrolling

People scroll to view content that is larger than can fit in the current window. Scroll bars are not persistently visible by default.

In general, scroll bars can appear when users:

  • Open or resize a window that contains scrolling content

  • Open content within a window that is too small to display all of the content at once

  • Place two fingers on a trackpad or mouse surface

  • Actively scroll content

In all of these cases, scroll bars appear briefly and then disappear shortly after users stop interacting with the window or the content. This behavior helps users see that the content exceeds the size of the window body, without requiring the scroll bar to occupy valuable space in the content area.

For example, you can see the scrollers in the Safari window shown here, because it was recently resized.

The elements of a scroll bar

The scroller size (relative to the length of the track) reflects how much of the content is visible. For example, a small scroller means that a small fraction of the total content is currently visible. The scroller also represents the relative location, in the whole document, of the portion that can be seen in the window.

Users scroll content in a window by doing one of the following:

  • Scrolling on a trackpad. This is an easy, natural gesture that strengthens the user’s sense of direct manipulation (to learn about the principle of direct manipulation, see “Direct Manipulation”).

    Note that users can also specify whether the content should move in the same direction that their fingers move in, or in the opposite direction.

  • Rolling the scroll ball on a mouse. Users can adjust how fast or slow scrolling occurs in Mouse preferences.

  • Dragging the scroller. This method can be the fastest way to move around a large document. The window’s contents changes in “real time” as the user drags the scroller.

    When a scroll bar is currently invisible, users must cause it to appear before they can drag the scroller. After a scroller appears, it remains visible for a few seconds so that users have a chance to interact with it.

  • Clicking or pressing in the scroll track. Clicking moves the document by a windowful (the default) or to the pointer’s hot spot, depending on the user’s choice in General preferences. A “windowful” is the height or width of the window, minus at least one unit of overlap to maintain the user’s context. The Page Up and Page Down keys also move the document view by a windowful.

    Pressing in the scroll track displays consecutive windowfuls of the document until the location of the scroller catches up to the location of the pointer (or until the user stops pressing).

    When a scroll bar is currently invisible, users must cause it to appear before they can click or press in the scroll track. There is a delay between the appearance and disappearance of the scroll bar, so that users have time to interact with the scroll track.

Most of the time, the user controls scrolling. But sometimes, scrolling happens automatically while the user is performing a different task, such as extending a selection past the edge of a window. To learn when your app should support this action, known as automatic scrolling, see “Enabling Scrolling.”

Moving

The user moves a window by dragging any part of the window frame (for more information about the parts of a window, see “About Window Appearance and Behavior”). As the user drags a window, the entire window and its contents move. Users can drag a window from one desktop to another by dragging it to the left or the right of the screen until the current space is pushed away by the neighboring space.

If the user presses the Command key while dragging an inactive window, the window moves, but does not become active. For more information about active and inactive windows, see “Main, Key, and Inactive Windows.”

Layering

Each app and document window exists in its own layer on a desktop, so that windows and documents from different apps can be interleaved. Clicking a window to bring it to the front doesn’t disturb the layering order of any other window on the desktop.

A window’s depth in the layers is determined by when the user last accessed it. When a user clicks an inactive document or chooses it from the Window menu, only that document, and any open panel, is brought to the front.

Users can bring all of an app’s windows forward by clicking the app icon in the Dock or by choosing Bring All to Front in the app’s Window menu. These actions bring forward all of the app’s open windows, maintaining their onscreen location, size, and layering order within the app.

Panels are always in the top layer. They are visible only when their app is active, and they float on top of any open document windows in the app.

Users can view all of an app’s open windows by activating App Exposé. In App Exposé view, users can choose one of the open windows on the current desktop or scroll to find an open window on a different desktop. Users can also cycle forward or backward through an app’s open windows on the current desktop by using Command-Backquote (Command-`) and Command-Shift-Backquote (Command-Shift-`). If full keyboard access is on, they can cycle through all windows by using Control-F4 and Shift-Control-F4.

Main, Key, and Inactive Windows

Windows have different appearances based on how the user is interacting with them. The foremost document or app window that is the focus of the user’s attention is called the main window. The main window is often also the key window, which is the window that accepts user input. For example, the “close window” keyboard shortcut, Command-W, always targets the key window.

Typically, the main window is also the key window, but this is not always the case. Sometimes a window other than the main window takes the focus of the input device, while the main window remains the focus of the user’s attention. For example, a user might be working in a document window when they need to open an inspector or the Colors window to make adjustments. In this situation, the document is still the main window, but the inspector or Colors window is the key window.

Both main and key windows are always in the foreground, but only the controls of the key window have color.

Main and key windows are both active windows. In an active window, the title bar (and toolbar, if one is present) displays the standard window-frame color. An active window that is not key has active, but clear, controls.

Inactive windows are windows the user has open, but that are not in the foreground. In an inactive window, the title bar (and toolbar) displays a lighter shade of the window-frame color. You can see the visual distinctions between main, key, and inactive windows in the figure below.

../art/wn_main_key_inactive.jpg

Going Full Screen

Apps can allow users to take a window full screen, so that they can immerse themselves in an experience or perform a task without distractions. When users take a window full screen, the app moves the window into a new space.

Use modern APIs to enable a full-screen window. If your app enabled a full-screen window in earlier versions of OS X, you should update your code to take advantage of the full-screen behavior supported by NSWindow, NSWindowDelegate Protocol, and NSApplication. Users expect to see windows transition to a new space and they expect to be able to switch between them and see them displayed in Mission Control. When you use the modern APIs, you can take advantage of the system-provided support for these behaviors, so that users get a consistent experience. For an overview of these programming interfaces, see “Implementing the Full-Screen Experience”.

Avoid creating a custom control that takes your window full screen. When you use the full-screen APIs, the appropriate dual-state button (that is, ../art/EnterFullscreen.jpg and ../art/ExitFullscreen.jpg) automatically appears in the right end of the title bar, giving users a consistent way to take your window full screen. You should also add the Enter Full Screen item to the View menu or—if you don’t include a View menu—the Window menu. (For more information about these menus, see “The View Menu” and “The Window Menu.”)

Create custom animations for your window’s transition to and from full-screen mode. It’s recommended that you design a smooth, subtle animated transition to replace the default transition. In particular, you need to make sure that all parts of your window move smoothly together and no parts appear to break apart or lag behind.

Displaying Items in the Title Bar

All windows should have a title bar even if the window doesn’t have a title (which should be a very rare exception). In a full-screen window, the title bar is hidden.

There are only four elements that can appear in the title bar: the window title, the title bar buttons, the full-screen button, and a proxy icon (in document windows). For the most part, you directly control only the window title; the system provides the other title-bar elements, depending on how you define your app’s behavior.

The Window Title

The window title is centered in the title bar. If the title is too long for the width of the window, it is truncated and an ellipsis is added, if necessary.

Name each window appropriately. The title of a document window should be the name of the document that it displays. The title of an app window is the app name. Panels should display a descriptive title appropriate for that window, such as Media or Layout.

If necessary, change the title of the window to reflect the current context. This might be appropriate if, for example, users can change the contents of the window. For example, in the Keynote inspector panel, the title of the window changes to reflect which pane the user has selected.

Separate multiple items in a title with an em dash (—) with space on either side. For example, when users select a mailbox the Mail message viewer window displays the name of the mailbox followed by the account name. When users open a message in its own window, the message title (that is, the subject) is displayed, followed by the mailbox name.

Don’t display pathnames in window titles. When displaying document titles, use the display name and show the extension if the user has elected to show extensions. If you need to display a path in the body of a window you can use the path control, described in “Path Control.”

Title Bar Buttons

The close, minimize, and zoom buttons, which are known collectively as the title bar buttons, appear in all windows except alerts and modal dialogs.

Document and app windows always display active close and minimize buttons. (For details on what these buttons do, see “Closing Windows” and “Minimizing and Expanding Windows.”) The zoom button appears if the window can be adjusted in size. (Information on how the zoom button works is in “Resizing and Zooming Windows.”)

Panels always display an active close button but never an active minimize button, because an open panel hides or minimizes together with its associated app or document window.

In general, inactive title bar buttons are visible in their inactive state; that is, they don’t disappear when they’re inactive. The exception is in panels, where it is acceptable to display only the close button. To learn more about panels and their title bar buttons, see “Panels.”

You can see the appropriate configurations of title bar buttons for app and document windows (and alerts and modal dialogs) below.

Title bar buttons for standard windows

Note that in an app that is not document-based, the close button might display a dot to indicate that the window contains unsaved changes. Document-based apps rarely need to do this, because Auto Save allows users to stop worrying about the saved state of their documents. For more information about Auto Save, see “Auto Save and Versions.”

The Full-Screen Button

If you use the standard AppKit programming interfaces to enable a window to go full screen, the system-provided full-screen button appears in the right end of the title bar by default (shown here in Mail).

../art/wn_fsbuttoninmail_2x.png

Users can click the full screen button to take a window full screen; in the full-screen window, they click the button again to return the window to its standard size. To learn more about enabling full-screen windows in your app, see “Allow Users to Go Full Screen (if Appropriate).”

The Proxy Icon and Title Bar Menu

The title bar of a document window can include a proxy icon (after the content is saved at least once) and a menu that lets users rename, move, tag, or lock a document.

A proxy icon is a small icon that represents the document itself. After pressing a proxy icon for a brief period, users can manipulate it as if they were manipulating the actual document. For example, users can attach a document to an email message by dragging its proxy icon into the email message, as shown below.

A proxy icon being dragged to another application

When users Command-click the document title or the proxy icon, a pop-up menu displays the document path. (Note that you don’t place a standard pop-up menu control in the title bar to provide this behavior.) Because OS X is a multiuser environment, it’s especially important to show the complete path of a document to avoid confusion. For example, in the Preview document shown here, the document path displays the document itself and all its containing folders, including the volume that contains the user’s home directory.

A document path pop-up menu, opened by Command-clicking the proxy icon

The title bar menu gives users a shortcut way to rename, move, or assign tags to a document or lock it (which prevents unauthorized editing).

../art/wn_versionsMenu_2x.png

Designing a Toolbar

A toolbar gives users convenient access to the most frequently used commands and features in an app. For example, the default Mail toolbar includes the commands people use most often as they view, compose, and manage their email.

../art/wn_toolbarexample_2x.png

Users often rely on the presence of a toolbar, but you can hide it in a full-screen window if users don’t need it to accomplish the focused task. For example, Preview hides the toolbar in a full-screen window because users are more likely to be focused on reading content than on annotating it. If you hide the toolbar in a full-screen window, users should be able to reveal it (along with the menu bar) when they move the pointer to the top of the screen.

Because a toolbar in an app or document window contains frequently used items, it tends to be a prominent part of the user’s experience with your app. The guidelines in this section help you to design a toolbar that enhances the usability of your app.

Create toolbar items that represent the functionality users need most often. To help you decide which items to include in your toolbar, consider the user’s mental model of the task they perform in your app (to learn more about the mental model, see “Mental Model”).

Arrange toolbar items so that they support the main task users accomplish in your app. In general, you want to use the left end of the toolbar for commands that should have the highest visibility. (In a localized version of your app, the commands that you’ve identified as being high-visibility might appear in the right end of the toolbar.) “High visibility” can mean different things in different apps. In some apps, for example, frequency of use should determine visibility; in other apps, it makes more sense to rank items according to importance, significance, or their place in an object hierarchy. The figure below illustrates three possible ways to arrange toolbar items.

../art/wn_toolbarprioritization.jpg

If appropriate, separate toolbar items into subsets and then arrange the subsets according to importance. Sometimes, you can define logical subsets of your app’s features and objects, such as one subset of document-manipulation commands and another subset of commands for manipulating page-level objects such as paragraphs, lists, and tables. When this is the case, you can arrange the items in each subset according to importance or frequency of use, and then use the same criteria to position each subset in the toolbar.

The default Keynote toolbar is an example of this type of arrangement. Keynote groups items according to functionality and then positions the groups so that the items that handle slide decks and slides are to the left of items that provide inspection and selection of object attributes. You can see about half of these groups below:

../art/wn_toolbarorganization.jpg

Use window frame controls in a toolbar. Standard Aqua and light content controls look bad on the toolbar background. Instead, you should use the controls that have been specifically designed for use in toolbars, such as the round textured button (shown here used for the Quick Look button in the Finder toolbar). To learn more about the controls you can use in a toolbar, see “Window-Frame Controls.”

../art/wn_toolbarbutton.jpg

Ensure that your toolbar controls clearly communicate their meaning to users. It’s best when users can tell what a toolbar control does without experimentation (or waiting to see a help tag). You can use system-provided icons in your toolbar controls to represent a wide range of common commands and features, such as the Action menu and Quick Look; that is, ../art/NSActionTemplate.jpg and ../art/NSQuickLookTemplate.jpg. Users are familiar with the meanings of these items, and using them frees you from having to design custom icons. (For more information about the system-provided images you can use, see “System-Provided Icons.”)

If necessary, you can design custom icons to represent toolbar items. If you have to do this, be sure to follow the guidelines in “Designing Toolbar Icons.”

Avoid displaying a persistent selected appearance for a toolbar item. When the user clicks an item in an app or document window toolbar the item highlights briefly, and an immediate action occurs, such as opening a new window, switching to a different view, displaying a menu, or inserting (or removing) an object. Because the result of the click is an action, it does not make sense to imply that there is a change in state. The exception to this is a segmented control that shows a persistent selected appearance within the context of the control, such as the view controls in the Finder toolbar:

../art/wn_segmentedselected.jpg

Make every toolbar item available as a menu command. Because users can customize the toolbar (and it can be hidden under some circumstances), the toolbar should not be the only place to find a command.

It’s important to emphasize that the converse of this guideline is not true. That is, you should not create a toolbar item for every menu command, because not all commands are important enough (or used frequently enough) to warrant inclusion in a toolbar.

In general, allow users to show or hide the toolbar. Users might want to hide the toolbar to minimize distractions or reveal more of their content. (Note that you can cause the toolbar to hide automatically in a full-screen window.) The commands for showing and hiding the toolbar belong in the View menu (for more information about this menu, see “The View Menu”).

In general, allow users to customize the toolbar. Although the default toolbar should include the commands that most users want, you should allow users to customize this set of commands to support their individual working styles. In addition, users should be able to specify whether toolbar items are displayed as controls only, text only, or controls with text (by default, display both controls and text). Place the Customize Toolbar command in the View menu (for more information about this menu, see “The View Menu”). Although you can also allow users to adjust the size of toolbar items, most users don’t expect this capability (if you decide to do this, you must supply different sizes of toolbar icons).

In addition, you can enable a contextual menu that is revealed when users Control-click the toolbar itself. In this menu, users can choose to customize the appearance and contents of the toolbar in various ways.

Avoid putting an app-specific contextual menu in your toolbar. Users reveal the contextual toolbar customization menu by Control-clicking anywhere in the toolbar. Additionally, in document windows, users can reveal the document path menu by Control-clicking the window title. This does not leave any areas in the toolbar that users could Control-click to reveal a third contextual menu. If you need to offer a set of commands that act upon an object the user selects, use an Action menu control instead (this item is described in “Action Menu”).

Enable click-through for toolbar items when appropriate. Click-through means that the user can activate the item when the containing window is inactive. You can support click-through for any subset of toolbar items. In general, you want to allow click-through for nondestructive actions that users might want to perform when they’re focused on a task in a different window. For additional guidelines on supporting click-through, see “Enabling Click-Through.”

Enabling Scrolling

Scrolling is one of the most common ways that users interact with their content. Follow the guidelines in this section to help you enable convenient, intuitive scrolling that takes advantage of the translucent, transiently visible scroll bars in OS X.

Avoid causing the legacy scroll bar to display. Users expect scroll bars to be only transiently visible by default. Although users can change the appearance of scroll bars in General preferences, you should not force users to see scroll bars if they don’t want to. Be sure to avoid using a placard or placing a control inline with a scroll bar, because including these elements in your UI causes legacy scroll bars to appear in your app.

Don’t move window content when scroll bars appear. Scroll bars are both transient and translucent, so users can see the window content that is beneath them. It should not be necessary to adjust the layout of content in your window, and doing so risks confusing users.

Help users discover when a window’s content is scrollable. Because scroll bars aren’t always visible, it can be helpful to make it obvious when content extends beyond the window. In a table or list view, for example, you can display the middle of a row at the bottom edge of the window instead of displaying a complete row. Displaying partial content at the bottom edge of a window in this way shows users that there’s more to see.

Don’t feel that you must always indicate when text doesn’t fit within a document window by, for example, displaying a partial line of text at the bottom edge. Remember that scrolling is an intuitive and nondestructive action that users don’t mind experimenting with. When faced with a window full of text, the vast majority of users will instinctively scroll in the window to see if more content is available.

If necessary, adjust the layout of your window so that important UI elements don't appear beneath scrollers. Occasionally, there might be cases in which you want to avoid having a scroller appear on top of specific parts of your UI. In Mail, for example, the position of an unread message badge in the Mailbox List leaves enough room for the scrollers to display without visually interfering with the badge. If you need to do this, note that the overall width of a regular-size scroll bar is 10 points (the overall width of a small-size scroll bar is 8 points). If necessary, you can adjust your layout so that there are no important UI elements within 10 points of the edge of the content area (or within 8 points of the edge, if you're using a small-size scroll bar).

Choose the scroller color that best coordinates with your UI. If your UI is very dark, for example, you might want to specify the light-colored scrollers so that users can see them easily. You can specify light, dark, or default. Mail, for example, uses the default scroller color:

../art/wn_defaultscroller.jpg

Determine how much to scroll when users click in the scroll track. Clicking in the scroll track advances the document by a windowful (the default) or to the pointer’s hot spot, depending on the user’s choice in General preferences. (Recall that users must first scroll the content to reveal the scroll track, as described in “Scrolling.”) A “windowful” is the height or width of the window, minus at least one unit of overlap to maintain the user’s context. You define the unit of overlap so that it makes sense for the content you display. For example, one unit might equal a line of text, a row of icons, or part of a picture. Note that you should respond to the Page Up and Page Down keys in the same way that you respond to a click in the scroll track; that is, pressing these keys should also move the content by a windowful.

When users press in the scroll track, you should display consecutive windowfuls of the content until the location of the scroller catches up to the location of the pointer (or until the user stops pressing).

Scroll automatically when appropriate. Most of the time, the user should be in control of scrolling, but your app should perform automatic scrolling in the following cases:

Move the document only as much as necessary during automatic scrolling. Minimizing the amount of automatic scrolling helps users keep their place in the content. For example, if part of a selection is showing after the user performs an operation, don’t scroll at all. If your app can reveal the selection by scrolling in only one direction, don’t scroll in both.

If possible, show a selection in context when automatically scrolling to it. If the entire window shows only the selected content, it can be difficult for users to remember the position of the selection within the overall content.

Consider using small or mini scroll bars in a panel, if necessary. If space is tight, it can be acceptable to use smaller scroll bars in panels that need to coexist with other windows. Note that if a window uses small or mini scroll bars, all other controls in that window’s content area should also be the smaller version.

Avoid using a scroll bar when you should instead use a slider. Use sliders to change settings; use scroll bars only for representing the relative position of the visible portion of a document or list. For information about sliders, see “Slider.”

Don’t override the default gesture to make scrollers appear. Users of OS X v10.8 and later are accustomed to the systemwide scrolling behavior. Scrollers appear automatically when users place two fingers on a trackpad or appropriate mouse surface. You should not override this behavior.

Using a Scope Bar to Enable Searching and Filtering

A scope bar allows users to specify locations or rules in a search or to filter objects by specific criteria. In general, scope bars are not visible all the time, but appear when the user initiates a search or similar operation. For example, the figure below shows the scope bar Safari displays when the user performs a find.

../art/wn_findwithscopebar_2x.png

Use a scope bar to help users specify and narrow a search, or to filter items. You might provide a scope bar if you want users to be able to specify and refine a search while maintaing their focus in the window. If you need to give users a way to navigate or to select collections of items or data that should appear in the window, however, you should use a source list instead (described in “Providing a Source List”). For example, the Dictionary app uses a scope bar to allow users to dynamically filter results by reference type (such as dictionary, thesaurus, or Apple dictionary), as shown below.

../art/wn_dictionaryscopebar_2x.png

If appropriate, allow users to refine a scoping operation. Users can specify additional rules to refine their scoping operation in filter rows that appear below a scope bar. A filter row can contain text fields that accept user input and round rectangle–style scope buttons (used for selecting or saving scoping criteria). For example, when users search in the Finder, they can click the Add button to view a new filter row with supplementary rules they can use to refine their search, as shown below.

../art/wn_finderscopebarrows_2x.png

Use the appropriate controls in a scope bar. In addition to the search field control, you should only use the controls that are specifically designed for use in a scope bar. These controls are the recessed-style scope button and the round rectangle–style scope button. The recessed-style scope button can display scoping locations and categories and the round rectangle–style scope button allows users to save or manipulate a scoping operation. To learn more about these controls, see “Scope Button.”

Allow users to save their searches. Users appreciate being able to perform specific searches again, especially if they spent time defining (and refining) a useful search.

Providing a Source List

A source list (also called a sidebar) is an area of a window, usually set off by a movable splitter, that provides users with a way to navigate or select objects in an app (for more information on splitters, see “Split View”). Typically, users select an object in the source list that they act on in the main part of the window.

You can provide a source list as the primary means of navigating or viewing within your app, as the Finder and Mail do, or as a way to select a view in a part of the app, as the Network preferences pane does. Each of these usage patterns is associated with a different source list appearance. Specifically:

For example, the Finder sidebar, which helps users navigate the file system, uses the blue background.

Finder Sidebar as a source list

To learn how to design icons to display in a sidebar similar to the Finder sidebar, see “Designing Sidebar Icons.”

In the figure below, you can see the white background of the source list in Network preferences, which allows users to select a network service to configure.

../art/wn_secondarysourcelist_2x.png

The following guidelines help you use a source list appropriately in your app.

Consider using a source list to give users a file-system abstraction. A source list can shield users from the details of file and document management, and allow them to work with user-customizable, app-specific containers that hold related items. Source lists can be especially useful in single-window apps that aren’t necessarily document-based, but that allow users to create and manage content. For example, iTunes allows users to ignore the file-system locations of their songs, podcasts, and movies, and instead work with libraries and playlists. Similarly, iWeb focuses on website creation, not on file management.

In particular, you might consider using a source list in your app when:

If necessary, display titles inside the source list. Source lists don’t generally have headers like lists can, but they can display titles to distinguish subsets of objects or data. For example, the Finder displays several useful subsets of locations and items in its sidebar, such as Devices, Shared, and Tags.

../art/wn_sectiontitlesinsrclist_2x.png

Avoid displaying more than two levels of hierarchy in a source list. If the data you need to display is organized in more than two levels of hierarchy, you can use a second source list, but you should not use additional disclosure triangles to expose additional levels of hierarchy in a single source list. If, however, your app is centered on the navigation of deeply nested objects, you should consider using a browser view instead of multiple source lists.

Use the appropriate background appearance in your source list. If your app contains a single source list that provides primary navigation and selection functionality, you can use the blue background. In all other cases, however, you should use the white background. Specifically, use the white background when:

As much as possible, allow users to customize the contents of a source list. It’s best when users can decide which object containers are most important to them. You should also consider using Spotlight to support smart data containers. For more information on using Spotlight in your app, read Spotlight Overview.

If you need to allow users to add, remove, manipulate, or get information about items in a source list, you can use gradient buttons at the bottom edge of the source list. Gradient buttons look good on the window-body area. (For details about using gradient buttons, see “Gradient Button.”)

Consider using a popover instead of a source list. If your source list does not represent primary functionality in your app you might consider replacing it with a popover, because a popover can appear only when users need it. To learn more about using a popover in your app, see “Popovers.”

Providing a Bottom Bar

A bottom bar is a window-frame area that is below the window body. Bottom bars are rarely used in modern Mac apps. If an earlier version of your app includes a bottom bar, consider redesigning the UI so that the controls are offered elsewhere, such as in the toolbar. If you’re creating a new app, it’s best to avoid using a bottom bar.

In general, controls in a bottom bar are frequently used, but are somewhat less important than controls in a toolbar. For example, the bottom-bar controls in iChat allow users to add buddies to the list and to text message, call, or video chat with a selected buddy, whereas the controls in the toolbar are focused on the user of the app.

../art/wn_ichatbottombar_2x.png

Because a bottom bar is considered a window-frame area, it has the same gray gradient surface that is visible in the toolbar–title bar area.

Bottom bars can contain either regular or small window-frame controls; bottom bars should not contain icon buttons, custom controls, or any Aqua controls that are designed for use in the window body. See “Window-Frame Controls” for more information about controls that are suitable for use in a bottom bar.

Avoid using a bottom bar to provide frequently used commands. Users don’t typically look at the bottom area of a window more often than they look at the top area, so placing the most important controls at the bottom makes them harder to find.

As much as possible, use the system-provided icons within bottom-bar controls. Users are already familiar with the meaning of the system-provided images (for more information about them, see “System-Provided Icons”). Note that you can also use text inside a bottom-bar control, such as “Edit.“ If you must design an icon for a bottom-bar control, try to imitate the clean lines of the system-provided images (for more information on designing icons for use in bottom-bar controls, see “Designing Toolbar Icons”).

Make sure that every bottom-bar item is also available as a menu command. Also, bottom bars should not contain contextual menus. If you need to offer a collection of commands that users can perform on a selected item in the window body, provide an Action menu control that displays the system-provided Action image (for more information on this control, see “Action Menu”).

Use Interface Builder to create a bottom bar of the appropriate size. If you decide to include a bottom bar in your app, select the window object on the Interface Builder canvas and open the size inspector. Choose large or small bottom border in the Content Border pop-up menu. Use regular controls in the large bottom bar; use small controls in the small bottom bar.

Providing a Drawer

A drawer is a child window that slides out from a parent window and that the user can open or close (show or hide) while the parent window is open. Drawers are rarely used in modern Mac apps. As much as possible, redesign your UI to avoid using drawers; if you’re creating a new app, avoid adding a drawer to the design.

Typically, a drawer contains frequently accessed controls that don’t need to be visible at all times. For example, the Keynote Build inspector uses a drawer to provide additional details about slide builds, as shown below.

An open drawer next to its parent window

Although a drawer is somewhat similar to a sheet in that it attaches to a window and slides into view, the two elements are not interchangeable. Sheets are modal dialogs, whereas drawers provide additional functionality. When a sheet is open, it is the focus of the window and it obscures the window contents; when a drawer is open, the entire parent window is still visible and accessible.

Drawers aren’t widely used in modern Mac apps, and they are rarely attached to a main window. If your app design includes a drawer, you might consider replacing it with a panel or perhaps a popover. (For more information about panels, see “Panels”; to learn about popovers, see “Popovers.”) If you really need to provide a drawer, follow the guidelines in this section.

Don’t enable a drawer on a window that can go full screen. Because a drawer slides out from an edge of its parent window, a full-screen window doesn’t have room to display a drawer.

Use drawers only for controls that need to be accessed fairly frequently but that don’t need to be visible all the time. This is in contrast to the criterion for a panel, which should be visible and available whenever its main window is in the top layer. (For more information about panels, see “Panels.”)

Don’t use a drawer to enable navigation. If you need to give users a way to navigate hierarchically arranged content in your window, you should use a source list instead. To learn more about source lists, see “Providing a Source List.”

If appropriate, automatically open a drawer when the user drags an object near it. Typically, users click a button or choose a command to show or hide a drawer. But if a drawer contains a valid drop target, you might want to open the drawer when the user drags an appropriate object to where the drawer appears.

Ensure that a drawer can open fully without disappearing offscreen. When a drawer opens, it appears to be sliding from behind its parent window, to the left, right, or down. If the user moves a parent window to the edge of the screen and then opens a drawer, the drawer should open on the side of the window that has room. If the user makes a window so big that there’s no room on either side, the drawer opens off the screen.

Ensure that a drawer is smaller than its parent window. This size difference supports the illusion that a closed drawer is hidden behind its parent window. If the user vertically resizes the parent window, an open drawer resizes, if necessary, to ensure that it does not exceed the height of the parent window.

Automatically close a drawer if the user makes it too small to see the contents. The user can resize an open drawer by dragging its outside border. If the user drags a drawer’s border to the point where its content is mostly obscured, the drawer should simply close. For example, if a drawer contains a scrolling list, the user should be able to resize the drawer to cover up the edge of the list. But if the user makes the drawer so small that the items in the list are difficult to identify, the drawer should close. If the user resizes a drawer, your app should remember the new size and use it the next time the drawer is opened.

Maintain a drawer’s state when its parent window becomes inactive or reopens. For example, an open drawer should remain open when its parent window becomes inactive or when it’s closed and then reopened. When the user minimizes a parent window with an open drawer, the drawer should close; the drawer should reopen when the parent window is unminimized.

Treat a drawer as part of the parent window. That is, don’t dim a drawer’s controls when the parent window has focus, and vice versa. When full keyboard access is on, a drawer’s contents should be included in the window components that users can select by pressing Tab.

Use standard Aqua controls in a drawer. A drawer can contain any control that is appropriate to its intended use.

Opening Windows

Users expect a window to open when they:

Most users expect app windows that were open when they logged out to reopen when they log back in. To meet this expectation, be sure to opt in to the Resume feature; to learn the programmatic steps you need to take to adopt Resume, see “User Interface Preservation” in Mac App Programming Guide. (Note that users can opt out of this feature in General preferences.)

Make sure windows display changeable panes as users expect. For the most part, users expect windows to reopen the pane that was open previously. Specifically, windows with changeable panes should reopen in their previous state as long as the app is open; if the user quits the app, these windows should return to their default state.

In a window with multiple toolbars, if the toolbar represents only a subset of multiple possible views (such as favorites), the default state should be to show all of the options below the toolbar, not a particular pane. If the toolbar displays all of the possible selections, then the default state of the window should be to display the pane that the user last selected. For example, when System Preferences opens, all of the possible selections are visible, but when Mail preferences opens, it displays the last pane selected by the user.

Title a newly opened window appropriately. When the user opens an existing document, make sure its title is the display name, which reflects the user’s preference for showing or hiding its filename extension. Don’t display pathnames in document titles. To learn how to name new windows, see “Naming New Windows.”

Naming New Windows

Most windows display a title, whether it’s the name of the app, the name of a document, or the name of a specific type of functionality, such as Inspector. A window’s title helps users instantly identify the window and its contents. Follow the guidelines in this section as you name new windows that users can open in your app.

Use your app name for the title of a main, nondocument window. If your app has a short name, use it as the title (for more information about the short name, see “The App Menu”).

Name a new document window “untitled.” Leave “untitled” lowercase to make it more obvious that the window contains untitled content. Don’t put a “1” on the first untitled window, even after the user opens other new windows.

If the user chooses New again before titling the first untitled document window, name the second window “untitled 2,” and so on.

Appropriate titles for a series of unnamed windows

If the user dismisses all untitled windows, the next new document window they open should start over as “untitled,” the next should be “untitled 2,” and so on.

Positioning and Repositioning Windows

When your app displays a window, you must decide where to put it and how big to make it. You must also respond appropriately when users move your app’s windows.

Horizontally center new document windows and display as much of the content as possible. The top of the document window should butt up against the menu bar (or the toolbar, if one is open and positioned below the menu bar). Subsequent windows on the same desktop should open to the right 20 points and down 20 points. Make sure that no part of a new window overlaps with the Dock (for more information about the Dock, see “The Dock”).

In general, horizontally center a new nondocument window. The vertical position should be visually centered: The distance from the bottom of the window to the top of the Dock (if it’s at the bottom of the screen) should be approximately twice the distance as that from the bottom of the menu bar to the top of the window. Subsequent windows are moved to the right 20 points and down 20 points. Make sure that no part of a new window overlaps with the Dock.

“Visually centered” placement of a new nondocument window

As much as possible, reopen a window in the same location, and at the same size, that the user last specified. Users appreciate being able to predict where a window will open. Before reopening a window, make sure that the size and state are feasible for the user’s current display setup, which may have changed since the last time the window was open. If you can’t reproduce both the size and location of the window, maintain the window’s location, but reduce its size as necessary. If you can’t reproduce either the location or the size, try to keep the window on the same display, and open the window so that as much of the content as possible is visible. If the user moves a window so that it is entirely positioned on a second display and later opens the window on a single-display system, respect the window’s previous size, if possible.

Note that if a user opens, moves, and closes a document window without making any other changes, you should save the new window position but you should not modify the file’s date stamp.

On a multidisplay system, visually center the first new window in the screen that contains the menu bar. If the user doesn’t move that first window, display each additional window below and to the right of its predecessor. If the user moves the window, display each additional window on the screen that contains the largest portion of the frontmost window, as shown below.

Appropriate placement of a new window on a system with multiple monitors (the user moved the first window to span the screens)

In particular, you want to avoid opening a window so that it spans more than one display. The initial position of a window should always be contained on a single screen. If the user opens several windows on a multidisplay system, continue to place the windows on the screen where the user is working, each new one below and to the right of its predecessor.

Don’t allow users to move a window to a position from which they can’t reposition it. For example, it should not be possible for users to “lose” a window below the Dock or on a second display that they unplug at a later time.

Resizing and Zooming Windows

Your app determines the initial size and position of a window, which is called the standard state. If the user changes a window’s size or location by at least 7 points, the new size and location is the called the user state. The user can toggle between the standard state and the user state by clicking the zoom button in the title bar. Follow the guidelines in this section so that users can have the zoom experience they expect.

Choose a standard state that is best suited for the tasks your app enables. A document window, for example, should show as much as possible of the document’s content. Don’t assume that the standard state should be as large as the current display permits; instead, determine a size that makes it convenient for users to use your app. If appropriate, you can allow users to take some app windows full screen if they want more space.

Adjust the standard state when appropriate. The user can’t change the standard state that defines a window’s initial position and size, but your app can do so, based on other settings. For example, a word processor might define a standard that accommodates the display of a document whose width is specified in the Page Setup dialog.

Respond appropriately when the user zooms. When the user zooms a window that is in the user state, your app should make sure that size defined by the standard state is appropriate in the current context. Specifically, move the window as little as possible to make it the standard size, while at the same time keeping the entire window on the screen. The zoom button should not cause the window to fill the entire screen unless that was the last state the user set.

If the user zooms a window in a multidisplay system, the standard state should be on the display that contains the largest portion of the window, not necessarily on the display that contains the menu bar. This means that if the user moves a window between displays, the window’s position in the standard state could be on different displays at different times. The standard state for any window must always be fully contained on a single display.

Don’t allow a zoomed window to overlap the Dock. You always want to make sure that users have full use of both your windows and the Dock. For more information about the Dock, see “The Dock.”

Minimizing and Expanding Windows

When the user clicks the minimize button in the title bar, double-clicks the title bar, or presses Command-M, the window minimizes into the Dock. The window’s icon remains in the Dock until the user clicks it or, if it is the app’s only open window, until the user clicks the app icon in the Dock. (To learn more more about the Dock, see “The Dock.”) The action of “unminimizing” a window that’s minimized in the Dock is called expanding.

Clicking an app icon in the Dock should always result in a window—a document or another appropriate window—becoming active. If a document-based app is not open when the user clicks the Dock icon, the app should open a new, untitled window.

When a user clicks an open app’s icon in the Dock, the app becomes active and all open unminimized windows are brought to the front; minimized document windows remain in the Dock. If there are no unminimized windows when the user clicks the Dock icon, the last minimized window should be expanded and made active. If no documents are open, the app should open a new window. (If your app is not document-based, display the main window.)

Closing Windows

Users can close windows by choosing Close from the File menu, pressing Command-W, or clicking the close button. Follow the guidelines in this section to ensure that your app closes windows as users expect.

Use modern APIs to preserve the window’s state. Regardless of whether you support Resume, you should remember a window’s onscreen size and position so that you can restore the user’s state when they reopen the window (or reopen your app). To learn more about how to use modern APIs to do this, see “User Interface Preservation” in Mac App Programming Guide.

In general, quit when users close the last open window in your app. In apps that are not document-based, users generally expect the app to quit when they close the main window. If an app continues to perform some function when the main window is closed, it might be appropriate to leave it running after the user closes the main window. For example, iTunes continues to play after the user closes the main window. If users close the last remaining document window in a document-based app and switch to another app, it’s appropriate to quit the app.

Display a close confirmation save dialog when users close a document window that contains unsaved data. Note that this behavior is automatic in document-based apps that adopt Auto Save. The close confirmation save dialog is similar to the standard Save dialog, but it adds a message that asks the user if they want to save their work. The reason for the message is that the action of closing the window implies that the user wants to discard their changes; if this is not the case, the user can respond by saving the data or canceling the close. Note that the close confirmation save dialog is not displayed if the document window closes as the result of some other action, such as the user quitting the app. In these other situations, you should automatically save the user’s work so that the user can choose to save or discard it at a later time.

After a document has been saved the first time, the close confirmation save dialog is not displayed when users close the document window, because users expect their changes to be saved continuously and without their intervention. (For learn more about save dialogs, see “Save Dialogs.”)

Enabling Click-Through

An item that provides click-through is one that a user can activate with one click, even though the item is in an inactive window. (To activate an item that does not support click-through, the user must first make the containing window active and then click the item.) Although click-through can make some user tasks easier, it can also confuse users if they click items unintentionally.

Click-through is not a property of a class of controls; any control, including toolbar items, can support click-through. This also means that you can support click-through for any subset of items; you don't have to choose between supporting click-through for all items in a window or none. Follow the guidelines in this section so that you can support click-through when it’s appropriate.

Avoid providing click-through for an item or action whose result might be dangerous or undesirable. Specifically, avoid enabling click-through for an item that:

Clicking in any one of these situations should cause the window that contains the item to be brought forward, but no other action to be taken.

In general, it’s safe to provide click-through for an item that asks the user for confirmation before executing, even if the command ultimately results in destruction of data. For example, you can provide click-through for a delete button if you also make sure to give users the opportunity to cancel or confirm the action before it proceeds.

Think twice before supporting click-through for items that don’t provide confirmation feedback. Specifically, consider how dangerous the action might be, and determine how difficult it will be for the user to undo the action after it’s performed. For example, the Mail Delete button does not provide click-through because it deletes a message without asking for confirmation, which is a potentially harmful action that can be difficult to undo. On the other hand, click-through for the New button in Mail is fine because its resulting action is not harmful and is easy to undo.

Ensure that items that don't support click-through appear disabled when their window is inactive. The disabled appearance helps users understand that these controls are unavailable. For example, the Delete and Mark as Junk buttons in the inactive Mail window shown below don't support click-through.

An inactive window with controls that support click-through

Popovers

A popover is a transient UI element that provides functionality that is directly related to a specific context, such as a control or an onscreen area. Popovers appear when users need them and (usually) disappear automatically when users finish interacting with them. For example, Calendar displays a popover in which users can create and edit a meeting.

../art/wn_popover_2x.png

A popover floats above the window that contains the control or area that it’s related to, and its border includes an arrow (sometimes referred to as an anchor) that indicates the point from which it emerged. In some cases, users can detach a popover from its related element, which causes the popover to become a panel. For example, Calendar allows users to detach the meeting-editing popover so that they can make changes to it while they refer to other windows.

../art/wn_popoveraspanel_2x.png

To learn how to define a popover in your code, see NSPopover. Follow the guidelines in this section to use popovers appropriately in your app.

Use a popover to display UI that users need occasionally. Popovers are perfectly suited to provide small amounts of focused functionality that users need. For example, when users select a term and open a contextual menu, they can choose the Look Up “term” menu item to see the Dictionary definition (in addition to information related to the term) in a popover.

../art/wn_popoverdictionary_2x.png

Because popovers can disappear when users finish interacting with them, users can spend more time focusing on their content and less time removing clutter from their workspace.

Consider using popovers instead of source lists, panels, or changeable panes. You might want to use a popover instead of these UI elements because doing so allows you to present a more focused and stable UI. For example, users might not need to navigate or select objects in your window’s source list very often. If you use a popover to display the source list’s content, you can use the window space for more important UI that directly relates to the user’s task.

Using a popover to replace a panel that contains auxiliary information can also make sense, because you can ensure that the popover disappears when users click outside of it. For example, users appreciate that they don’t have to explicitly dismiss the Safari Downloads popover before they continue interacting with the Safari browser window.

Finally, using a popover to replace changeable panes in a main window can help your UI seem more stable. For example, if you offer secondary or transient functionality in a pane that users can hide and reveal, you can instead offer the functionality in a popover. Because a popover appears only when it’s needed, it doesn’t alter the look of the window. Users tend to be most comfortable with a window layout that does not change very often.

Allow users to detach a popover if appropriate. Users might appreciate being able to convert a popover into a panel if they want to view other content or other windows while the popover content remains visible.

Don’t use a popover as an alert. Popovers and alerts are very different UI elements. For one thing, users choose to see a popover; they never choose to see an alert. If you use popovers and alerts interchangeably, you blur the distinctions between them and confuse users. In particular, if you use a popover to warn users about a serious problem or to help them avoid imminent, unintentional data loss, they are likely to dismiss the popover without reading it, and blame your app when negative results occur. If you really need to alert users (which should happen only rarely), use an alert; for guidelines on how to design an alert, see “Alerts.”

As much as possible, ensure that the popover arrow points directly to the element that revealed it. The arrow helps people remember where the popover came from and with what task or object it’s associated.

In general, use the standard popover appearance. The standard appearance is identified by the NSPopoverAppearanceMinimal constant. You can also use the “HUD” appearance, but this is generally only suited to an app that uses a dark UI and enables an immersive, media-centric experience.

Avoid including a “close popover” button. In general, a popover should close automatically when the user doesn’t need it anymore. This behavior helps users focus on their task without worrying about cluttering their desktop. For example, after users finish editing an Calendar event, they can click Done or they can click outside the event-editing popover to close it. Regardless of the method users choose, Calendar saves the edits they made.

Choose a closure behavior that makes sense in the context of the task the popover enables. A popover can close in response to a user interaction (transient behavior), in response to a user’s interaction with the view or element from which the popover emerged (semitransient behavior), or in an app-defined way. If a popover merely presents a set of choices, it can be appropriate to close it as soon as the user makes a choice (that is, using the transient behavior). Because this behavior mirrors the behavior of a menu, users are comfortable with it. If, on the other hand, you use a popover to enable a task that requires multiple user interactions, such as the Calendar event editing popover, you can use the semitransient behavior to close the popover when the user interacts with the area outside of it.

Avoid nesting popovers. A popover that emerges from a control inside a different popover is physically difficult for users to interact with and confusing to see. In addition, users can’t predict what will happen when they click outside of both popovers.

Avoid making a popover too big. A popover should not appear to take over the entire screen. Instead, it should be just big enough to display its contents and still point to the area from which it emerged.

Avoid making significant appearance changes in a detachable popover. If you allow users to detach a popover, you should ensure that the resulting panel looks similar to the original popover. If the new panel looks too different, users might forget where it came from.

If appropriate, change a popover’s size while it remains visible. You might want to change a popover’s size if you use it to display both a minimal and an expanded view of the same information. For example, Calendar displays a minimal popover when users double-click a meeting they’ve created. If the user wants to edit the meeting, the minimal popover expands to accommodate more information about the meeting and the editing controls. The transition from one popover size to another should be smoothly animated, so that users can be sure that they’re still interacting with the same popover.

Panels

A panel is an auxiliary window that contains controls and options that affect the active document or selection. An app-wide toolbar in its own window is also called a tool panel or, less frequently, a tool palette.

Panels are either app-specific or systemwide. App-specific panels float on top of the app’s windows and disappear when the app is deactivated. Systemwide panels, such as the Colors window and the Fonts window, float on top of all open windows. (To learn more about the Colors window, see “The Colors Window”; to learn more about the Fonts window, see “The Fonts Window.”)

Most panels are standard panels, which means that they use the same textures in the window body and title bar that a standard window does. Also, a standard panel tends to use small versions of the standard UI controls. A few panels are translucent, which means that they use a dark, translucent texture in the window body and title bar, and they use small white and gray UI elements. You can see a few examples of different types of panels in the figure below.

../art/wn_panelexamples.jpg

In general, use a standard panel. For some apps, such as highly visual, immersive apps, transparent panels can be appropriate, but for most apps, standard panels are best. Users don’t expect to see a transparent panel unless it contains image adjustment tools or it is displayed by an immersive app that uses a dark UI. To learn more about when transparent panels are appropriate, and how to design one, see “Transparent Panels.”

Use a panel to give users easy access to important controls or information that directly affects their task. For example, you can create a modeless panel, such as a tools panel, to offer controls or settings that affect the active document window. Because panels take up screen space, however, don’t use them when you can meet the need by using a popover, a modeless dialog, or by adding a few appropriate controls to a toolbar.

Hide and show panels appropriately. When a user makes a document active, all of the app’s panels should be brought to the front, regardless of which document was active when the user opened the panel. When an app is inactive, its panels should be hidden.

Panels should not be listed in the Window menu as documents, but you can put commands to show or hide all panels in the Window menu.

Make sure a panel includes a title bar. Even if a panel doesn’t need a title, it should have a title bar so that users can drag it.

Avoid including an active minimize button in a panel. A user should not need to minimize a panel because it is displayed only when needed and disappears when its app is inactive. Instead, a panel should include the close and zoom buttons or, more commonly, only the close button. The correct configurations are shown below, followed by some incorrect configurations.

../art/wn_panelcontrols.jpg

Inspectors

An inspector is a panel that allows users to view the attributes of a selection. Inspectors (sometimes called inspector windows) can also provide ways to modify these attributes. Pages, Keynote, and Preview are just a few of the apps that use inspectors (an inspector window in Numbers is shown below).

../art/wn_inspectorexample.jpg

Ensure that an inspector updates dynamically based on the current selection. Users expect an inspector’s view to always be up to date. Similarly, they expect the changes they make in an inspector to immediately affect their content. Contrast this behavior with that of an Info window, which shows the attributes of the item that was selected when the window was opened, even after the focus has been changed to another item. Also, an Info window is not a panel; it is listed in the app’s Window menu and it does not hide when the app becomes inactive.

You can provide both inspectors and Info windows in your app, because in some cases users want to have one window in which context changes with each new item they select (an inspector) and in other cases users want to be able to see the attributes of more than one item at the same time (a set of Info windows). Note that users can open multiple inspector windows and Info windows in the same app at the same time.

Transparent Panels

A transparent panel gives users a way to make quick adjustments to their content or task without being distracted from their work. Although the behavior of a transparent panel is similar to the behavior of a standard panel, its appearance is designed to complement apps that focus on highly visual content or that provide an immersive experience, such as a full-screen slide show. For example, iMovie provides a transparent panel that enables users to adjust several settings in the movie.

../art/wn_transpanexample.jpg

Have a good reason to use a transparent panel instead of a standard panel. Users can be distracted or confused by a transparent panel when there is no logical reason for its presence. In general, you should use transparent panels only when at least one of the following statements is true:

  • Your app is media-centric, that is, focused on movies, photos, or slides.

  • Users use your app in a dark environment or in an immersion mode (frequently, this type of app also uses a dark, custom UI).

  • Users make only quick adjustments in the panel and dismiss it quickly.

  • A standard panel would obscure the content that users need to adjust.

Use a combination of standard and transparent panels, if appropriate. If your app focuses on highly visual content only at specific times or only in some modes, use the panel type that is best suited to the current task and environment. For example, the Keynote inspector allows user to set slide transitions, edit tables and graphs, and make complex adjustments to text and formatting. Keynote uses a standard panel for the inspector because none of its functions are focused solely on adjustments to media.

But Keynote also provides an image-adjustment panel, which helps users make simple adjustments to slide images. The image-adjustment panel is transparent, because users use it while they are focusing on the image, watching the effect of the adjustments they make.

../art/wn_keynotetranspan.jpg

Don’t change a panel’s type when your app changes its mode. For example, if you use a transparent panel when your app is in an immersive mode, don’t transform it into a standard panel when your app switches to a nonimmersive mode.

As much as possible, use simple adjustment controls in a transparent panel. In particular, you want to avoid using controls that require users to type or to select items, because these controls force users to shift their attention from their content to the panel. Instead, consider using controls such as sliders and steppers, because they’re easy for users to use without focusing on them.

Use white controls with gray accents and white or gray text in a transparent panel. Light-colored controls and text are easier for users to see on the dark translucent background of a transparent panel. And, as users focus on the content behind the panel, the white text and controls appear to be floating above it.

Use color sparingly. In the dark UI of a transparent panel, too much color can lessen its impact and distract users. Often, you only need small amounts of color to enhance the information you provide in a transparent panel. For example, the morsels of color in the Keynote image adjustment panel (shown in above) communicate ranges in white balance and exposure, in addition to color-specific settings, in a clear and unobtrusive way. Make sure that these small amounts of color have high contrast so that they look good on the dark translucent background.

In general, keep transparent panels (and their contents) small. Transparent panels are designed to be unobtrusively useful, so allowing them to grow too big defeats their primary purpose. You don’t want a transparent panel to obscure the content that the user is trying to adjust, and you don’t want it to compete with the content for the user’s attention.

About Windows

An About window, also called an About box, is an optional window that displays your app’s version and copyright information. The Finder About window is shown here.

Example of an About window

Unlike other windows, an About window combines some of the behaviors of panels and windows: Like a panel, an About window is not listed in the app’s Window menu and like a window, it remains visible when the app is inactive.

An About window should be modeless so the user can leave it open and perform other tasks in the app. If you decide to provide an About window, be sure that it:

  • Has a title bar with no title

  • Is movable

  • Includes the close button as the only active window control

  • Displays your app icon

  • Includes the full app name and version number (the version number should be the same as the version number displayed by the Finder)

  • Includes copyright information, technical support contact information, a brief description of what the app does

Use buttons in an About window if you want to give users a way to contact you. For example, you might provide a button that opens your website in a browser window or opens a blank email message that is pre-addressed to you. Of course, it’s best to provide most of your company contact information in the first page of your help documentation (for more information on Help menu items, see “The Help Menu”).

Consider putting branding elements, such as logos or slogans, in your About window. An About window is the appropriate place for these elements because users expect it to provide information about your company and product. It’s best to avoid putting such elements in document windows and dialogs.

Dialogs

A dialog is a window that is designed to elicit a response from the user. Many dialogs—the Print dialog, for example—allow users to provide many responses at one time.

OS X provides three main ways to present dialogs:

In addition, OS X provides an alert, which is a special type of dialog that can be document modal or app modal. In general, if the error condition or notification applies to a single document, the alert is document modal (that is, a sheet). If the alert applies to the state of the app as a whole, or to more than one document or window belonging to the app, the alert is app modal. For guidelines on when to use alerts and how to design them, see “Alerts.”

Using Sheets (Document-Modal Dialogs)

A sheet is a modal dialog that is attached to a particular document or window, preventing users from interacting with the document or window until they dismiss the dialog. To avoid annoying users, you should use a sheet only when necessary.

Because a sheet is attached to the window from which it emerges, users never lose track of which window the dialog applies to. The TextEdit "locked” dialog shown here is an example of a sheet.

../art/wn_sheetasmodaldlg_2x.png

A sheet animates into view as if it were emerging from a window’s toolbar (or title bar, if no toolbar is present). When a sheet opens on a window near the edge of the screen and the sheet is wider than the window it’s attached to, the sheet causes the window to move away from the edge. When the sheet is dismissed, the window returns to its previous position.

Only one sheet can be open for a window at any one time. If the user’s response to a sheet causes another sheet to open for that document, the first sheet closes before the second one opens.

In general, a sheet is a good way to present:

  • A modal dialog for an activity that is specific to a particular document, such as exporting, attaching files, or printing.

  • A modal dialog that is specific to a single-window app that does not create documents. For example, a single-window utility app might use a sheet to request acceptance of a licensing agreement from the user.

  • Other window-specific dialogs that are typically dismissed by users before they proceed with their task.

Follow the guidelines in this section to ensure that the sheets you display behave as users expect.

If necessary, display a sheet on top of any active panels that are related to the current document window. However, if the user leaves a sheet open and clicks another document in the same app, the inactive window and its sheet should go behind any open panels.

Avoid using sheets if multiple open windows can show different parts of the same document at the same time. A sheet is not useful in this situation, because it implies that the changes users make apply only to one portion of the document. In this type of situation, it’s better to use an app modal dialog to help users understand that changes in one window affect the content in other windows.

Use a sheet when multiple documents can appear in a single window at different times. For example, a tabbed browser can display different documents in a single window at different times. A sheet is appropriate in this situation, even though it applies to only the document that is currently visible in the window. Because users must in effect dismiss the current document before viewing a different document in the same window, they should first dismiss the sheet.

Don’t use a sheet if users need to see or interact with the window in order to address the dialog. For example, if the dialog requests information that the user must get from the window, the dialog should not be a sheet. In this case, a modeless dialog would allow users to see or copy information in the window and apply it to the dialog.

Don’t use a sheet for a modeless operation in which users need to observe the effects of their changes. In this situation, a panel is a better choice because users can leave it open while they make changes to their content.

Don’t use a sheet on a window that doesn’t have a title bar. Sheets should emerge from a definite visual edge.

Accepting and Applying User Input in a Dialog

Because dialogs are small, transient UI elements, users don’t expect to have in-depth interactions with them. Dialogs are most effective when they make it easy for users to input information and respond immediately to the changes users make.

As you design a dialog, keep the following points in mind to help you make user interaction easy:

  • When appropriate, display default values for controls and text fields so that the user can verify information rather than enter it from scratch.

  • Display a selection or an insertion point in the first location that accepts user input—a text entry field or a list, for example.

  • When it provides an obvious user benefit, ensure that static text is selectable. For example, a user should be able to copy an error message, a serial number, or IP address to paste elsewhere.

For the most part, changes that a user makes in a dialog should appear to take effect immediately. To support the appearance of immediate effect, you need to validate the information users enter and you need to decide when to apply their changes. The following guidelines can help you provide a good dialog experience.

As much as possible, do error checking as the user inputs information. If you wait to check for errors until the user tries to dismiss the dialog, you might have to present an alert, which is not a good user experience. It’s better to check for errors as soon as possible, because it allows users to fix the problem before they leave the context of the dialog.

Avoid validating input after each keystroke. Too-frequent validation can annoy users and slow down your app. It’s better to design your interface to automatically disallow invalid input. For example, your app could automatically convert lowercase characters to uppercase when appropriate.

Use the length of an operation to determine whether to perform it automatically. Sometimes, it’s appropriate for your app to automatically perform an operation based on user input; other times, it’s better when the user initiates the operation—for example, by clicking a button. In general, it’s acceptable to automatically perform an operation that completes quickly and returns user control within a couple of seconds. For an operation that takes a longer time to execute, it’s best to display an estimate of the time required to complete the operation and let the user initiate it.

Provide an Apply button when it makes sense. An Apply button can be appropriate in a dialog that displays multiple settings that affect the user’s view of data. In this situation, an Apply button allows the user to preview the effect of the selected settings without committing to the changes.

Be cautious about using an Apply button for operations that take a long time to implement or undo; it might not be obvious to users that they can interrupt or reverse the process. In particular, save dialogs or dialogs that allow users to make changes that can’t be previewed easily should not include an Apply button.

Don’t use an Apply button to mean the same thing as the OK button. In particular, clicking an Apply button should not dismiss a dialog because the user should first decide whether to accept the previewed changes (by clicking OK) or to reject them (by clicking Cancel). When the user dismisses the dialog without clicking OK, all previewed changes should be discarded.

Expanding Dialogs

Sometimes you need to provide the user with additional information or functionality in a dialog, but you don’t want to display it all the time. To do this, you use one of the disclosure controls to expand the dialog and reveal the additional information or capability to the user.

Use a disclosure button to provide additional choices in a dialog. In particular, the disclosure button is the appropriate choice when the additional choices are directly related to selections that are offered in a pop-up or command pop-down menu in a dialog. When users click the disclosure button the dialog expands to reveal selections in addition to those listed in the pop-up or command pop-down menu. (For more information about how to use a disclosure button in your dialog, see “Disclosure Button.”)

Use a disclosure triangle to reveal details that elaborate on the primary information in a dialog. When users open the disclosure triangle the dialog expands, revealing additional information and, if appropriate, extra functionality. (For more information about how to use a disclosure triangle in your dialog, see “Disclosure Triangle.”)

Respond appropriately when users can resize a dialog that contains columns of data. If users can resize a dialog that displays columns (such as the Open dialog), the columns should grow and additional columns should appear. All other elements should remain the same size and be anchored to the right, center, or left side of the dialog.

Dismissing Dialogs

Users expect all the buttons at the bottom right of a dialog to dismiss the dialog. A button that initiates an action is furthest to the right. This rightmost button, called the action button, confirms the main point of the dialog. The Cancel button is to the left of the action button.

Usually the rightmost button or the Cancel button is the default button. A default button has color and pulses to let the user know that when they press Return or Enter, the default button is activated.

../art/wn_dialogbuttonlayout.jpg

Follow the guidelines in this section to ensure that your dialogs look and behave as users expect.

Use a default button only if the user’s most likely action is harmless. The default button should represent the action that the user is most likely to perform if that action isn’t potentially dangerous. Users sometimes press Return merely to dismiss a dialog, without taking the time to read its content, so it’s crucial to ensure that the default button performs a harmless action.

Don’t use a default button at all if the user’s most likely action is dangerous—for example, if it causes a loss of user data. When there is no default button, pressing Return or Enter has no effect; the user must explicitly click a button to dismiss the dialog. This guideline protects users from accidentally damaging their work by pressing Return or Enter without fully understanding the dialog’s message. You can consider using a safe default button, such as Cancel, or not using a default button at all.

Don’t use a default button if you use the Return key in the dialog’s text fields. Having two behaviors for one key can confuse users and make the interface less predictable. Also, users might press Return one too many times and dismiss the dialog (and activate the default button) without meaning to.

In general, include a Cancel button. The Cancel button returns the computer to the state it was in before the dialog appeared. It means “forget I mentioned it.” Also, make sure that the keyboard shortcut Command-period and the Esc (Escape) key are mapped to the Cancel button.

Ensure that Cancel undoes applied changes. If your dialog incudes an Apply button that helps users see the effect of changes before committing to them, make sure that clicking Cancel undoes all of the applied changes. Cancel should never silently commit the changes the user previewed by clicking Apply. For more guidelines on using an Apply button, see “Accepting and Applying User Input in a Dialog.”

Place a third button for dismissing the dialog to the left of the Cancel button. If the third button could result in data loss—Don’t Save, for example—try to position it at least 24 points away from the “safe” buttons (Cancel and Save, for example).

Place a button that affects the contents of the dialog itself in the left end of the dialog. If there is no Help button, such a button should have its left edge aligned with the main dialog text; if there is a Help button, it should be placed to the right of the Help button. For example, the Help button is to the left of the Show Details button in the Print dialog, which expands the dialog to display more information about the print job.

../art/wn_dialogbuttonlayoutwithhelp.jpg

Preferences Windows

A preferences window is a modeless dialog that contains settings the user changes infrequently. In general, the user opens a preferences window to change the default way an app displays an item or performs a task, then closes the window, and expects the new settings to have taken effect. (For some guidance on how to provide a good preferences experience in your app, see “Preferences.”)

Often, a preferences window has a toolbar that contains items that function as pane switchers. When the user clicks an item in this type of toolbar, the content area of the preferences window switches to display a different view, called a pane. This design is useful for apps that need to provide multiple settings in each of several different categories. For example, the Safari preferences window contains a toolbar that allows user to choose among categories of settings, such as bookmarks, appearance, and RSS.

../art/wn_safariprefs_2x.png

Don’t enable customization of a pane-switcher toolbar in a preferences window. A pane-switcher toolbar in a preferences window does not provide a shortcut to frequently used commands, but instead acts as a convenient way to group settings. If users customize this type of toolbar, they might forget that hidden settings are still available. For the same reason, it makes sense to disable the ability to hide the toolbar in a preferences window, too.

Maintain the selected appearance of an item in a pane-switcher toolbar. When the user clicks an item in a pane-switcher toolbar, the window displays a different pane. It’s important to indicate which item is currently selected by maintaining the item’s selected appearance. For example, in the Safari preferences window, you can see the background highlighting that indicates the Tabs item is the active one.

The Finder preferences window

Don’t allow resizing or include active minimize or zoom buttons in a preferences window. Remember that preferences windows are intended to give users a place to make occasional adjustments to the way an app behaves, so there should be no need for a preferences window to be resized or to remain open for a long time.

Use the title of the current pane to title the preferences window. The preferences window title should be the same as the title of the currently selected pane even if you don’t use a pane-switcher toolbar to change panes. (Note that if your preferences window does not contain multiple panes, its title should be “App Name Preferences”.) In addition, a changeable-pane preferences window should remember which pane the user selected the last time the window was open.

Use the standard menu item and keyboard shortcut to open your preferences window. Users expect most apps to include a Preferences command in the app menu. In addition, most users expect to be able to use the Command-comma keyboard shortcut to open an app’s preferences window.

The Open Dialog

The Open dialog gives users a consistent way to find and open an item in an app. Its appearance varies slightly depending on whether the app uses the iCloud Open dialog.

If your app is document based and iCloud enabled, it has an iCloud Open dialog that opens in its own window. Other apps have an Open dialog that is app modal, which means that users can’t interact with the app until they dismiss the dialog, although they can switch to other apps.

The iCloud Open dialog contains these elements:

  • In the title bar: Tabs for iCloud and On My Mac, the app’s title—for example, “Preview”—and a search field

  • In the bottom bar: Thumbnail and list options for navigating the file system, Share and Tags menus, and Done and Open buttons

You can see most of the required elements in the iCloud Open dialog for Preview in iCloud.

An Open dialog

The On My Mac tab replaces the window body contents with a source list that mirrors the Finder sidebar as shown here:

An Open dialog

The Open dialog for non-document-based apps contains these elements:

  • The title, “Open”

  • In the tool bar: Back and forward buttons, different views for navigating the file system, a pop-up menu that contains common places a user might save things and Recent Places (the five most recent folders the user opened or saved documents to), and a search field

  • In the window body: A source list that mirrors the Finder sidebar

  • In the bottom bar: Cancel and Open buttons (the Open button is the default button)

  • The ability for expert users to specify a pathname by pressing Command-Shift-G (note that the pathname separator is the slash (/) character)

You can see most of the required elements in the Open File dialog for Safari.

An Open dialog

You can extend the Open dialog as appropriate for your app. For example, the TextEdit Open dialog contains an additional section that allows users to specify different encodings.

A customized Open dialog

The following guidelines help you use and customize an Open dialog appropriately.

As much as possible, use the Open command to mean “open,” and not “act upon.” The Open dialog is best suited to help users find an item to open in your app. If you need to help users find items to use in an app-specific task, it’s generally better to use a Choose dialog instead (for guidance on using a Choose dialog, see “The Choose Dialog”).

Make sure users can use the Open command to display the Open dialog. Users expect the Open command to display an Open dialog. Contrast this with the Choose dialog, which can be displayed by different commands in different apps. It’s also a good idea to provide the standard Command-O keyboard shortcut to display the Open dialog, because most users are accustomed to it.

Specify a reasonable default location. For the iCloud Open dialog, iCloud is the default location. You should not change this behavior. See “iCloud Storage” for more information.

Otherwise, the default location is typically one of the predefined folders in the user’s home folder. If the user selects a different folder, make sure you remember the user’s selection so that it appears the next time the dialog is displayed.

Consider including a pop-up menu that allows users to filter the types of files that appear in the list. Display items that don't meet the filtering criteria as dimmed. You can supplement this list with custom types and specify the default to show when the dialog opens. You should include an All Applicable Files item, but it does not have to be the default item.

Include an Open Recent command to accompany the Open command. The Open Recent command allows users to reopen recently opened documents without using the Open dialog.

Extend the functionality of the Open dialog, if appropriate. For example, it’s a good idea to support document preview so that users can be sure they’re opening the document they intend. In addition, you can enable multiple selection if your app allows more than one document to be opened at one time.

The Choose Dialog

A Choose dialog gives users a consistent way to select an item as the target of a task. An app can have more than one Choose dialog, but only one can be open at a time.

A Choose dialog:

  • Can be opened by various commands

  • Can support multiple selection

  • Supports document preview

  • Can be resized

For example, Calendar displays a choose dialog that allows users to choose a calendar to import.

A Choose dialog

The following guidelines help you use a Choose dialog appropriately in your app.

Use a sheet for the Choose dialog when the chosen items are specific to the document. For example, Mail displays a Choose dialog in a sheet to help users to find items to attach to the current message.

../art/wn_choosedialogsheet_2x.png

Customize the Choose dialog title to reflect the task (if the dialog is not a sheet). By default, the dialog’s title is “Choose.” If, for example, the command that displays the dialog is Choose Picture, the dialog should be titled “Choose Picture.” If it’s helpful, also change the Choose button to something more specific.

Consider including a pop-up menu that allows users to filter the types of files that appear in the list. Display items that don't meet the filtering criteria as dimmed. You can supplement this list with custom types and specify the default to show when the dialog opens. You should include an All Applicable Files item, but it does not have to be the default.

The Print and Page Setup Dialogs

Users expect most documents to be printable, or to include a printable version. OS X provides standard dialogs that your app can display so that users can have a consistent printing experience in every app they use.

The Print dialog is focused on printing the current document, but it also includes features that can be provided by individual apps and by printer modules. The Page Setup dialog gives users a way to set the scaling and orientation options for a document, based on the intended output paper size and the printer.

By default, the Print dialog appears in its minimal form (shown here in the dialog attached to a TextEdit document). Users can get additional functionality in the expanded Print dialog by clicking Show Details.

../art/wn_minprintdialog_2x.png

In the expanded Print dialog, user options are provided via the features pop-up menu, which displays panes that are drawn and controlled by printing dialog extensions (PDEs). PDEs are provided by the operating system, printer modules, and apps. Apple provides a number of printing panes. In the expanded Print dialog shown here, you can see the “Print header and footer” and “Rewrap contents to fit page” options that TextEdit provides.

A Print dialog (a sheet attached to a document window)

You might want to provide custom print panes that give users options that are relevant to the types of content your app handles. For example, Contacts helps users print their contact information in different styles, such as mailing label, envelope, and list. Here are some specific guidelines to keep in mind if you implement custom printing features:

  • Choose a menu item name that doesn’t conflict with menu items already in the features pop-up menu, and that accurately describes the content of the pane. For an app, the menu item should be the app name.

  • Make sure the features you implement are appropriate for your app. For example, an option to print in reverse order should be provided by the operating system, not by your app. (Implementing this feature requires the app to know the hardware’s capabilities.)

  • Make interdependencies among options clear to users. For example, if a user selects double-sided printing, the option to print on transparencies should become unavailable.

  • Separate more advanced features from frequently used features. When the user chooses to display the advanced features, there should be an “advanced options” title above the advanced controls.

  • When appropriate, show users what effect their choices will have. For example, a thumbnail image that shows the effect of changing a tone control helps users determine desired settings.

  • Save a user’s printing preferences for a document, at least while the document is open, and provide a way for users to save custom settings.

If you think users would appreciate being able to set printing attributes for different printers or different paper sizes, it makes sense to provide a Page Setup dialog in your app. Be sure to save the settings that users make in this dialog with the document. Below, you can see the Page Setup dialog that TextEdit provides.

The Page Setup dialog

Find Windows

A Find window is a modeless dialog that opens in response to the Find command and that provides an interface for specifying items to search for.

Find windows can be useful in document-creation apps, because users can use one Find window to search for a term in several different open documents. If it makes sense in your UI, however, you can offer find functionality in a scope bar. A scope bar is attached to a window and provides both search and filtering capabilities to users. For more information about scope bars and how to use them in your app, see “Using a Scope Bar to Enable Searching and Filtering.”

Save Dialogs

Users expect to be able to specify a title and save location when they choose to save a document for the first time. To perform the initial save, users expect to see the standard Save dialog.

The Save dialog has two states: minimal (also known as collapsed) and expanded. Clicking the disclosure button toggles between these states. For example, in the minimal Save dialog (shown here displayed by TextEdit), you can see the closed disclosure button to the right of the document title.

../art/wn_minsavedialog_2x.png

The minimal Save dialog contains these elements:

  • The Save As text field in which users enter the document name. Expert users can enter pathnames by pressing Command-Shift-G. (Note that the pathname separator is the “/” character.)

  • The Where pop-up menu, which contains mounted volumes, folders in the Finder sidebar, and Recent Places (which are the five most recent folders the user opened or saved documents to).

  • A Save button (this is the default button).

  • A Cancel button, which dismisses the dialog and returns the app to its previous state.

  • A disclosure button. Clicking it displays the expanded Save dialog. (For more information about how to use disclosure buttons, see “Disclosure Button.”)

  • An optional accessory view, which can contain information such as text encoding settings. (In general, the accessory view should not be necessary.)

The expanded Save dialog gives users a broader view of the file system than they get in the minimal Save dialog’s Where pop-up menu. For example, the expanded TextEdit Save dialog displays the browsable file-system view.

The expanded Save dialog

In addition to the items in the minimal Save dialog, the expanded Save dialog includes the following:

  • Back and forward buttons to navigate back and forth between selections made in the list or column view.

  • A source list that mirrors the Finder sidebar.

  • Options for navigating the file system.

  • A File Format (or Format) pop-up menu, which displays a list of file formats from which the user can choose.

  • A New Folder button, which displays an app-modal dialog that asks the user to name the new folder, and then creates it.

  • A “Hide extension” checkbox, which allows the user to control whether or not the filename’s extension (.jpg, for example) is visible.

In addition to the Save dialog, a document-based app can display the close confirmation save dialog. The close confirmation save dialog (shown when users close a document window that contains data that has never been saved) has the same minimal and expanded states as the standard Save dialog. For example, TextEdit displays the close confirmation save dialog when the user closes a new document window with unsaved changes.

../art/wn_closeconfirmdialog_2x.png

As with the standard Save dialog, the close confirmation save dialog includes a disclosure button to the right of the Save As text field. Clicking this button expands the dialog to show a similar browsable file system view. The differences between the close confirmation save dialog and the standard Save dialog are due to the fact that it’s unclear whether the user intends to discard their work. For this reason, the text at the top of the dialog explains why it has appeared, and the Don’t Save button at the bottom of the dialog allows the user to decline to save their work.

There are a few ways in which you can customize a Save dialog so that it provides a better user experience. Keep the following guidelines in mind as you customize the save dialogs your app displays.

Specify a reasonable default location. The default location appears in the Where pop-up menu (in the minimal Save dialog) and in the Finder view (in the expanded Save dialog). Typically, the default location is one of the predefined folders in the user’s home folder. If the user selects a different folder, make sure you remember the user’s selection so that it appears the next time the dialog is displayed.

Allow users to choose whether to view the file extension. The “Hide extension” checkbox should be selected as the default (that is, filename extensions should not appear in user-visible filenames unless the user requests them). If the user changes the state of the checkbox for a particular document, the next new document should match the last user-selected state, even after the user quits and reopens the app. The filename in the Save As field updates in real time as the checkbox is selected or deselected.

Display the default new document name before users save the document for the first time. In general, this should be “untitled.” In the Save As field, display the default name as selected so that users can easily replace it with a custom name. If the user has chosen to make the filename extension visible, the extension is not selected.

Display custom UI elements below the location-selection elements. In the minimal Save dialog, custom UI elements go between the Where pop-up menu and the buttons at the bottom of the dialog. In the expanded Save dialog, custom elements go between the file-system browser and the buttons at the bottom of the dialog.

Alerts

An alert is a dialog that appears when the system or an app needs to give users an important message about an error condition or warn them about potentially hazardous situations or consequences. An alert that applies to a single document or window is displayed as a sheet.

Alerts interrupt users and must be dismissed before users can return to their task. For the best user experience, it’s essential that you avoid displaying an alert unless it’s absolutely necessary. The guidelines in this section help you determine when to display an alert and, if one is required, how to ensure that it’s useful.

A standard alert

As you can see in the Finder alert shown above, an alert contains the following elements:

When an alert is necessary, your most important job is to explain the situation clearly and give users a way to handle it. The following guidelines can help you decide when to display an alert, and how to make sure it communicates appropriately with users.

Avoid using an alert merely to give users information. Although it’s important to tell users about serious problems, such as the potential for data loss, users don’t appreciate being interrupted by alerts that are informative but not actionable. Instead of displaying an alert that merely informs, give users the information in another way, such as in an altered status indicator. For example, when a mail server connection has been lost, Mail displays a warning indicator in the sidebar. Instead of being forced to handle an alert when the connection is lost, users can click the warning indicator if they want more information about the situation.

Avoid displaying an alert for common, undoable actions, even when they cause data loss. When users delete Mail messages or throw files away, they don’t need to see an alert that warns them about the loss of data. Because users take these actions with the intention of discarding data (and because these actions are easy to undo), an alert is inappropriate. On the other hand, if the user initiates an uncommon action that can't be undone, such as Secure Empty Trash, it’s appropriate to display an alert in case the user didn’t mean to take the action.

If a situation is worthy of an alert, don’t use any other UI element to display it. It might be tempting to use a different element to display alert information, but it would be very confusing for users. Users are familiar with the standard alert and they’re not likely to take the information in a different element as seriously.

Use the caution icon in rare cases. It’s possible to display a caution icon in your alert, badged with your app icon. This type of badged alert is appropriate only if the user is performing a task that might result in the inadvertent and unexpected destruction of data. Don’t use a caution icon for tasks whose only purpose is to overwrite or remove data, such as Save or Empty Trash because the too-frequent use of the caution icon dilutes its significance.

Write an alert message that clearly and succinctly describes the alert situation. An alert message such as “An error occurred” is mystifying to all users and is likely to annoy experienced users. It’s best to be as complete and as specific as possible, without being verbose. When possible, identify the error that occurred, the document or file it occurred in, and why it occurred.

When it’s possible that users are unaware that their action might have negative consequences, it can be appropriate to phrase the alert message as a question. For example, a question such as “Are you sure you want to clear history?” pinpoints the action users took and prompts them to consider the results. Be sure that you don’t overuse this type of alert; users tire quickly of being asked if they’re sure they want to do something.

Write informative text that elaborates on the consequences and suggests a solution or alternative. Give as much information as necessary to explain why the user should care about the situation. If it's appropriate, use the informative text to remind users that the action they initiated can't be undone.

Informative text is best when it includes a suggestion for fixing the problem. For example, when the Finder can’t use the user’s input to rename a file, it tells them to try using fewer characters or avoid including punctuation marks.

Express everything in the user’s vocabulary. An alert is an especially bad place to be cryptic or to use esoteric language, because the arrival of an alert can be very unsettling. Even though you want to be succinct, it’s important that you use clear, simple language and avoid jargon. (For some examples of jargon to avoid, see “Use User-Centric Terminology.”)

Ensure that the default button name corresponds to the action you describe. In particular, it’s a good idea to avoid using OK for the default button. The meaning of OK can be unclear even in alerts that ask if the user is sure they want to do something. For example, does OK mean “OK, I want to complete the action” or “OK, I now understand the negative results my action would have caused”?

Using a more focused button name, such as Erase, Convert, Clear, or Delete, helps make sure that users understand the action they’re taking.