Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks
On This Page

Icons

Image Size and Resolution

Supply high-resolution images with a scale factor of @2x for all artwork that appears in the Touch Bar. In a @2x graphic, one point equals two pixels. For example, an icon that’s 36px by 36px translates to 18pt by 18pt. Append a suffix of @2x to your image names, and insert them into @2x fields in the asset catalog of your Xcode project.

Custom Icons

If your app includes tasks or modes that can’t be represented by a system icon, you can create your own icons.

Design recognizable icons. Your icons should clearly relate to your app on the main screen, but may require variations in order to match the style of the Touch Bar.

Keep icons simple. Too many details can make an icon appear sloppy or unreadable. If you have high-fidelity imagery, distill it down to its essence. The best icons convey meaning through outline and contour, and include very little internal detail. Use anti-aliasing to keep your icon’s outline crisp. Don’t use drop shadows or attempt to make icons appear dimensional through shading or highlighting.

Keep icons consistent. Whether you use only custom icons or mix custom and system icons, all of your icons should have the same visual weight in terms of size, level of detail, perspective, and stroke.

Use the system icons for reference. Refer to the system icons when designing custom icons, and strive for a similar appearance.

Prepare icons as template images. A template image is a black image with a transparent background and an alpha channel. The system inverts template images when displaying them in the Touch Bar, and automatically applies the appropriate color. Template images also respond to system white-point changes based on factors such as ambient light and keyboard backlight level, and automatically react to user interactions.

Test your icons. Always preview your icons together and in context to properly gauge their appearance. Make sure template images appear as expected when they are inverted by the system.

Size

Although it’s possible to produce icons that extend to the full height of the Touch Bar, icons generally should not exceed 44px in height (36px for circular icons).

Target icon size

18pt by 18pt (36px by 36px @2x)

Maximum icon size

22pt by 22pt (44px by 44px @2x)

image: ../Art/touchbar_custom_icon_example.png

Keep icons optically centered. Crop artwork to match the icon’s width, then add padding as needed to keep icons optically centered when displayed on a control.

Prefer a 45 degree angle for diagonal icon features. In the system icons, diagonal elements are often placed at a 45 degree angle, for example, the arrows on the Enter Full Screen and Exit Full Screen icons; the chevrons on the Go Back, Go Down, Go Forward, and Go Up icons; the slash on the Audio Input Mute icon; the pencil on the Compose icon; and the compass point on the Open In Browser icon. See System-provided Icons for reference.

Color and Fill

Icons in the Touch Bar should appear similar to the glyphs on the physical keyboard keys. If you’re using template images and system colors, your icons should achieve this effect automatically.

Don’t use color to communicate on and off states. The system already changes the background appearance of standard controls that are in an off state.

Give most icons a 100% opacity fill. If variations are needed for readability, use 70% opacity fills in combination with 100% opacity fills. Use midtones only for improving readability and balance.

For related guidance, see Color.

Stroke

To match the style of the physical keyboard, give most icons a 2px stroke. If your design requires more visual weight, try a 3px stroke.

Corners

To match the style of the system icons, use square corners for icons with a 2px stroke, rounded corners with a 1px radius for icons with a 3px stroke, and rounded corners with a 4px radius for solid shapes.

Templates

Use these Photoshop and Sketch templates to design properly scaled icons for use in the Touch Bar. Download Icon Templates.

System-Provided Icons

The system provides lots of icons, representing common tasks and types of content, for use in your app controls.

Prefer system icons because they're familiar. Because system icons are template images, they automatically receive appropriate coloring, respond to system white-point changes based on factors such as ambient light and keyboard backlight level, and they automatically react to user interactions.

Don’t redefine the intended functions of system icons. To ensure a consistent experience, use system icons as intended. Don’t, for example, display the Folder Move To icon on a Download button. Instead, display the Download icon.

Use only system icons that are designed for the Touch Bar. Other types of icons, such as toolbar icons, aren’t intended for use in the Touch Bar.

Table 46-1System icons for the Touch Bar

Icon

Icon name

AppKit symbol

Function

image: ../Art/TB_adddetail.png

Add Detail

NSImageNameTouchBarAddDetailTemplate

Displays additional detail for an item.

image: ../Art/TB_add.png

Add

NSImageNameTouchBarAddTemplate

Creates a new item.

image: ../Art/TB_alarm.png

Alarm

NSImageNameTouchBarAlarmTemplate

Sets or displays an alarm.

image: ../Art/TB_audioinputmute.png

Audio Input Mute

NSImageNameTouchBarAudioInputMuteTemplate

Mutes audio input or denotes that audio input is muted.

image: ../Art/TB_audioinput.png

Audio Input

NSImageNameTouchBarAudioInputTemplate

Denotes audio input.

image: ../Art/TB_audiooutputmute.png

Audio Output Mute

NSImageNameTouchBarAudioOutputMuteTemplate

Mutes audio output or denotes that audio output is muted.

image: ../Art/TB_audiooutputvolumehigh.png

Audio Output Volume High

NSImageNameTouchBarAudioOutputVolumeHighTemplate

Sets the audio output volume to high or denotes that the audio output volume is set to high.

image: ../Art/TB_audiooutputvolumelow.png

Audio Output Volume Low

NSImageNameTouchBarAudioOutputVolumeLowTemplate

Sets the audio output volume to low or denotes that the audio output volume is set to low.

image: ../Art/TB_audiooutputvolumemedium.png

Audio Output Volume Medium

NSImageNameTouchBarAudioOutputVolumeMediumTemplate

Sets the audio output volume to medium or denotes that the audio output volume is set to medium.

image: ../Art/TB_audiooutputvolumeoff.png

Audio Output Volume Off

NSImageNameTouchBarAudioOutputVolumeOffTemplate

Turns off audio output or denotes that audio output is turned off.

image: ../Art/TB_bookmarks.png

Bookmarks

NSImageNameTouchBarBookmarksTemplate

Shows app-specific bookmarks.

image: ../Art/TB_colorpickerfill.png

Color Picker Fill

NSImageNameTouchBarColorPickerFill

Shows a color picker so the user can select a fill color.

image: ../Art/TB_colorpickerfont.png

Color Picker Font

NSImageNameTouchBarColorPickerFont

Shows a color picker so the user can select a text color.

image: ../Art/TB_colorpickerstroke.png

Color Picker Stroke

NSImageNameTouchBarColorPickerStroke

Shows a color picker so the user can select a stroke color.

image: ../Art/TB_communicationaudio.png

Communication Audio

NSImageNameTouchBarCommunicationAudioTemplate

Initiates or denotes audio communication.

image: ../Art/TB_communicationvideo.png

Communication Video

NSImageNameTouchBarCommunicationVideoTemplate

Initiates or denotes video communication.

image: ../Art/TB_compose.png

Compose

NSImageNameTouchBarComposeTemplate

Opens a new document or view in edit mode.

image: ../Art/TB_delete.png

Delete

NSImageNameTouchBarDeleteTemplate

Deletes the current or selected item.

image: ../Art/TB_download.png

Download

NSImageNameTouchBarDownloadTemplate

Downloads an item.

image: ../Art/TB_enterfullscreen.png

Enter Full Screen

NSImageNameTouchBarEnterFullScreenTemplate

Enters full screen mode.

image: ../Art/TB_exitfullscreen.png

Exit Full Screen

NSImageNameTouchBarExitFullScreenTemplate

Exits full screen mode.

image: ../Art/TB_fastforward.png

Fast Forward

NSImageNameTouchBarFastForwardTemplate

Fast-forwards through media playback or slides.

image: ../Art/TB_foldercopyto.png

Folder Copy To

NSImageNameTouchBarFolderCopyToTemplate

Copies an item to a destination.

image: ../Art/TB_foldermoveto.png

Folder Move To

NSImageNameTouchBarFolderMoveToTemplate

Moves an item to a new destination.

image: ../Art/TB_folder.png

Folder

NSImageNameTouchBarFolderTemplate

Opens or represents a folder.

image: ../Art/TB_getinfo.png

Get Info

NSImageNameTouchBarGetInfoTemplate

Displays additional information about an item.

image: ../Art/TB_goback.png

Go Back

NSImageNameTouchBarGoBackTemplate

Returns to the previous screen or location.

image: ../Art/TB_godown.png

Go Down

NSImageNameTouchBarGoDownTemplate

Moves to the next vertical item.

image: ../Art/TB_goforward.png

Go Forward

NSImageNameTouchBarGoForwardTemplate

Moves to the next screen or location.

image: ../Art/TB_goup.png

Go Up

NSImageNameTouchBarGoUpTemplate

Moves to the previous vertical item.

image: ../Art/TB_history.png

History

NSImageNameTouchBarHistoryTemplate

Displays historical information, such as recent downloads.

image: ../Art/TB_iconview.png

Icon View

NSImageNameTouchBarIconViewTemplate

Displays items in an icon view.

image: ../Art/TB_listview.png

List View

NSImageNameTouchBarListViewTemplate

Displays items in a list view.

image: ../Art/TB_mail.png

Mail

NSImageNameTouchBarMailTemplate

Creates an email message.

image: ../Art/TB_newfolder.png

New Folder

NSImageNameTouchBarNewFolderTemplate

Creates a new folder.

image: ../Art/TB_newmessage.png

New Message

NSImageNameTouchBarNewMessageTemplate

Creates a new message or denotes the use of messaging.

image: ../Art/TB_openinbrowser.png

Open In Browser

NSImageNameTouchBarOpenInBrowserTemplate

Opens an item in the user’s browser.

image: ../Art/TB_pause.png

Pause

NSImageNameTouchBarPauseTemplate

Pauses media playback or slides. Always store the current location when pausing, so playback can resume later.

image: ../Art/TB_playpause.png

Play Pause

NSImageNameTouchBarPlayPauseTemplate

Toggles between playing and pausing media or slides.

image: ../Art/TB_play.png

Play

NSImageNameTouchBarPlayTemplate

Begins or resumes media playback or slides.

image: ../Art/TB_quicklook.png

Quick Look

NSImageNameTouchBarQuickLookTemplate

Opens an item in Quick Look.

image: ../Art/TB_recordstart.png

Record Start

NSImageNameTouchBarRecordStartTemplate

Begins recording.

image: ../Art/TB_recordstop.png

Record Stop

NSImageNameTouchBarRecordStopTemplate

Stops recording or stops media playback or slides.

image: ../Art/TB_refresh.png

Refresh

NSImageNameTouchBarRefreshTemplate

Refreshes data on screen.

image: ../Art/TB_rewind.png

Rewind

NSImageNameTouchBarRewindTemplate

Moves backwards through media playback or slides.

image: ../Art/TB_rotateleft.png

Rotate Left

NSImageNameTouchBarRotateLeftTemplate

Rotates an item to the left.

image: ../Art/TB_rotateright.png

Rotate Right

NSImageNameTouchBarRotateRightTemplate

Rotates an item to the right.

image: ../Art/TB_search.png

Search

NSImageNameTouchBarSearchTemplate

Displays a search field or initiates a search.

image: ../Art/TB_share.png

Share

NSImageNameTouchBarShareTemplate

Shares content with others or to social media.

image: ../Art/TB_sidebar.png

Sidebar

NSImageNameTouchBarSidebarTemplate

Displays a sidebar in the current view.

image: ../Art/TB_skipahead15seconds.png

Skip Ahead 15 Seconds

NSImageNameTouchBarSkipAhead15SecondsTemplate

Skips 15 seconds ahead during media playback.

image: ../Art/TB_skipahead30seconds.png

Skip Ahead 30 Seconds

NSImageNameTouchBarSkipAhead30SecondsTemplate

Skips 30 seconds ahead during media playback.

image: ../Art/TB_skipahead.png

Skip Ahead

NSImageNameTouchBarSkipAheadTemplate

Skips to the next chapter or location during media playback.

image: ../Art/TB_skipback15seconds.png

Skip Back 15 Seconds

NSImageNameTouchBarSkipBack15SecondsTemplate

Skips 15 seconds back during media playback.

image: ../Art/TB_skipback30seconds.png

Skip Back 30 Seconds

NSImageNameTouchBarSkipBack30SecondsTemplate

Skips 30 seconds back during media playback.

image: ../Art/TB_skipback.png

Skip Back

NSImageNameTouchBarSkipBackTemplate

Skips to the previous chapter or location during media playback.

image: ../Art/TB_skiptoend.png

Skip To End

NSImageNameTouchBarSkipToEndTemplate

Skips to the end during media playback.

image: ../Art/TB_skiptostart.png

Skip To Start

NSImageNameTouchBarSkipToStartTemplate

Skips to the beginning during media playback.

image: ../Art/TB_slideshow.png

Slideshow

NSImageNameTouchBarSlideshowTemplate

Starts a slideshow.

image: ../Art/TB_tagicon.png

Tag

NSImageNameTouchBarTagIconTemplate

Applies a tag to an item.

image: ../Art/TB_textbold.png

Text Bold

NSImageNameTouchBarTextBoldTemplate

Makes text bold.

image: ../Art/TB_textbox.png

Text Box

NSImageNameTouchBarTextBoxTemplate

Inserts a text box.

image: ../Art/TB_textcenteralign.png

Text Center Align

NSImageNameTouchBarTextCenterAlignTemplate

Center aligns text.

image: ../Art/TB_textitalic.png

Text Italic

NSImageNameTouchBarTextItalicTemplate

Italicizes text.

image: ../Art/TB_textjustifiedalign.png

Text Justified Align

NSImageNameTouchBarTextJustifiedAlignTemplate

Justifies text, aligning it to both the left and right.

image: ../Art/TB_textleftalign.png

Text Left Align

NSImageNameTouchBarTextLeftAlignTemplate

Left aligns text.

image: ../Art/TB_textlist.png

Text List

NSImageNameTouchBarTextListTemplate

Inserts a list or converts text to list form.

image: ../Art/TB_textrightalign.png

Text Right Align

NSImageNameTouchBarTextRightAlignTemplate

Right aligns text.

image: ../Art/TB_textstrikethrough.png

Text Strikethrough

NSImageNameTouchBarTextStrikethroughTemplate

Applies a strikethrough to text.

image: ../Art/TB_textunderline.png

Text Underline

NSImageNameTouchBarTextUnderlineTemplate

Underlines text.

image: ../Art/TB_useradd.png

User Add

NSImageNameTouchBarUserAddTemplate

Creates a new user.

image: ../Art/TB_usergroup.png

User Group

NSImageNameTouchBarUserGroupTemplate

Shows or represents a group of users.

image: ../Art/TB_user.png

User

NSImageNameTouchBarUserTemplate

Shows or represents user information.

image: ../Art/TB_volumedown.png

Volume Down

NSImageNameTouchBarVolumeDownTemplate

Reduces the volume.

image: ../Art/TB_volumeup.png

Volume Up

NSImageNameTouchBarVolumeUpTemplate

Increases the volume.