Hig Patterns

Apple HIG: Interaction Patterns

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Minimize modality. Use modality only when it is critical to get attention, a task must be completed or abandoned, or saving changes is essential. Prefer non-modal alternatives.

2. Provide clear feedback. Every action should produce visible, audible, or haptic response. Activity indicators for indeterminate waits, progress bars for determinate, haptics for physical confirmation.

3. Support undo over confirmation dialogs. Destructive actions should be reversible when possible. Undo is almost always better than "Are you sure?"

4. Launch quickly. Display a launch screen that transitions seamlessly into the first screen. No splash screens with logos. Restore previous state.

5. Defer sign-in. Let users explore before requiring account creation. Support Sign in with Apple and passkeys.

6. Keep onboarding brief. Three screens max. Let users skip. Teach through progressive disclosure and contextual hints.

7. Use progressive disclosure. Show essentials first, let users drill into details. Don't overwhelm with every option on one screen.

8. Respect user attention. Consolidate notifications, minimize interruptions, give users control over alerts. Never use notifications for marketing.

Reference Index

Pattern Selection Guide

Output Format

1. Recommended pattern with rationale, citing the relevant reference file. 2. Step-by-step implementation covering each screen or state. 3. Platform variations for targeted platforms. 4. Common pitfalls that violate HIG for this pattern.

Questions to Ask

1. Where in the app does this pattern appear? What comes before and after? 2. Which platforms? 3. Designing from scratch or improving an existing flow? 4. Does this involve sensitive actions? (Destructive operations, payments, permissions)

Related Skills

• hig-foundations -- Accessibility, color, typography, and privacy principles underlying every pattern
• hig-platforms -- Platform-specific pattern implementations
• hig-components-layout -- Structural components (tab bars, sidebars, split views) for navigation patterns
• hig-components-content -- Content display within patterns (charts, collections, search results)

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/charting-data.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Charting data

• Analyzing trends based on historical or predicted values

• Visualizing the current state of a process, system, or quantity that changes over time

• Evaluating different items — or the same item at different times — by comparing data across multiple categories

Best practices

Use a chart when you want to highlight important information about a dataset.

Keep a chart simple, letting people choose when they want additional details.

Make every chart in your app accessible.

Designing effective charts

In general, prefer using common chart types.

If you need to create a chart that presents data in a novel way, help people learn how to interpret the chart.

Examine the data from multiple levels or perspectives to find details you can display to enhance the chart.

Aid comprehension by adding descriptive text to the chart.

Match the size of a chart to its functionality, topic, and level of detail.

Prefer consistency across multiple charts, deviating only when you need to highlight differences.

Maintain continuity among multiple charts that use the same data.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/charting-data

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Collaboration and sharing

Best practices

Place the Share button in a convenient location, like a toolbar, to make it easy for people to start sharing or collaborating.

If necessary, customize the share sheet or sharing popover to offer the types of file sharing your app supports.

Write succinct phrases that summarize the sharing permissions you support.

Provide a set of simple sharing options that streamline collaboration setup.

Prominently display the Collaboration button as soon as collaboration starts.

Provide custom actions in the collaboration popover only if needed.

If it makes sense in your app, customize the title of the modal view’s collaboration-management button.

Consider posting collaboration event notifications in Messages.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/collaboration-and-sharing

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/drag-and-drop.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Drag and drop

• In visionOS, people pinch and hold a virtual object while dragging it to a new location in any direction, including along the z-axis.

• iOS and iPadOS support drag and drop through gestures on the touchscreen, interactions with a pointing device, and through full keyboard-access mode.

• Universal Control lets people drag content between their Mac and iPad.

• On a Mac, people can interact with a pointing device, use full keyboard access mode, or use VoiceOver to perform drag and drop.

Best practices

As much as possible, support drag and drop throughout your app.

Offer alternative ways to accomplish drag-and-drop actions.

Determine when dragging and dropping content within your app results in a move or a copy.

Support multi-item drag and drop when it makes sense.

Prefer letting people undo a drag-and-drop operation.

Consider offering multiple versions of dragged content, ordered from highest to lowest fidelity.

Consider supporting spring loading.

Providing feedback

Display a drag image as soon as people drag a selection about three points.

If it adds clarity, modify the drag image to help people predict the result of a drag-and-drop operation.

Show people whether a destination can accept dragged content.

When people drop an item on an invalid destination, or when dropping fails, provide visual feedback.

Accepting drops

Scroll the contents of a destination when necessary.

When there’s a choice, pick the richest version of dropped content your app can accept.

Extract only the relevant portion of dropped content if necessary.

When a physical keyboard is attached, check for the Option key at drop time.

Provide feedback when dropped content needs time to transfer.

Provide feedback when dropped content initiates a task or action.

Apply appropriate styling to dropped text.

After a drop, maintain the content’s selection state in the destination, updating it in the source as needed.

Platform considerations

iOS, iPadOS

Let people perform multiple simultaneous drag activities.

macOS

Consider letting people drag content from your app into the Finder.

Let people drag selected content from an inactive window without first making the window active.

When possible, let people drag individual items from an inactive window without affecting an existing background selection.

Consider displaying a badge during multi-item drag operations.

Consider changing the pointer appearance to indicate what will happen when people drop content.

As much as possible, let people select and drag content with a single motion.

visionOS

When possible, launch your app to handle content that people drop into empty space.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/drag-and-drop

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/entering-data.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Entering data

• Pre-gathering as much information as possible to minimize the amount of data that people need to supply

• Supporting all available input methods so people can choose the method that works for them

Best practices

Get information from the system whenever possible.

Be clear about the data you need.

Use a secure text-entry field when appropriate.

Never prepopulate a password field.

When possible, offer choices instead of requiring text entry.

As much as possible, let people provide data by dragging and dropping it or by pasting it.

Dynamically validate field values.

When data entry is necessary, make sure people understand that they must provide the required data before they can proceed.

Platform considerations

macOS

Consider using an expansion tooltip to show the full version of clipped or truncated text in a field.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/entering-data

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/feedback.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Feedback

• The current status of something

• The success or failure of an important task or action

• A warning about an action that can have negative consequences

• An opportunity to correct a mistake or problematic situation

Best practices

Make sure all feedback is accessible.

Consider integrating status feedback into your interface.

Use alerts to deliver critical — and ideally actionable — information.

Warn people when they initiate a task that can cause data loss that’s unexpected and irreversible.

When it makes sense, confirm that a significant action or task has completed.

Show people when a command can’t be carried out and help them understand why.

Platform considerations

watchOS

Avoid displaying an indeterminate progress indicator — such as a loading indicator — in a watchOS app.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/feedback

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/file-management.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

File management

Creating and opening files

Use app menus and keyboard shortcuts to give people convenient ways to create and open documents.

If your app requires a custom file browser, support people’s understanding of the platform’s file system.

Saving work

Help people be confident that their work is always preserved unless they cancel or delete it.

Hide file extensions by default, but let people view them if they choose.

Quick Look previews

Use a Quick Look viewer to let people preview a file even when your app can’t open it.

Consider implementing a Quick Look generator if your app produces custom file types.

Platform considerations

iOS, iPadOS

Document launcher

• A _title card_ that displays the app title and two app-specific buttons

• A background image that appears behind the title card and additional images — called _accessories_ — that can appear around it

• A sheet that contains a file browser and optional app-specific controls

Assign the title card’s buttons to your app’s most important functions.

Provide a background that’s clearly distinct from the accessories and title card.

Be mindful of accessory placement.

Use animation sparingly.

File provider app extension

When someone uses your file provider extension to open or import documents, display only documents that are appropriate in the current context.

Let people select a destination when exporting and moving documents.

Avoid including a custom top toolbar.

macOS

Custom file management

Make your custom file-opening interface convenient.

Provide a save interface to let people change a file’s name, format, or location.

Consider extending the functionality of the Save dialog.

Finder Sync extensions

• Display badges in the Finder to indicate the sync status of items

• Provide custom contextual menu items that perform file and folder management tasks, like favoriting and adding password-protection

• Provide custom toolbar buttons that perform global actions, like initiating a sync operation

Help people avoid losing work if they turn off autosaving.

When autosaving is off, make sure people know when a document has unsaved changes.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/file-management

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/going-full-screen.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Going full screen

Best practices

Support full-screen mode when it makes sense for your experience.

If necessary, adjust your layout in full-screen mode, but don’t programmatically resize your window.

Continue to provide access to essential features and controls so people can complete their task without exiting full-screen mode.

Except in games, let people reveal the Dock while your iPadOS or macOS app is in full-screen mode.

After people switch away from your full-screen experience, help them resume where they left off when they return.

Let people choose when to exit full-screen mode.

Prioritize content by temporarily hiding toolbars and navigation controls.

Platform considerations

iOS, iPadOS

Consider deferring system gestures to prevent accidental exits in a full-screen app or game.

macOS

Use the system-provided full-screen experience.

In a game, don’t change the display mode when players go full screen.

Always let people choose when to enter full-screen mode.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/going-full-screen

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/launching.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Launching

Best practices

Launch instantly.

If the platform requires it, provide a launch screen.

If you need a splash screen, consider displaying it at the beginning of your onboarding flow.

Restore the previous state when your app restarts so people can continue where they left off.

Launch screens

Downplay the launch experience.

Design a launch screen that’s nearly identical to the first screen of your app or game.

Avoid including text on your launch screen, even if your first screen displays text.

Don’t advertise.

Platform considerations

iOS, iPadOS

Launch in the appropriate orientation.

tvOS

In a live-viewing app, consider automatically starting playback soon after people start the app.

visionOS

Consider launching in the Shared Space even if your app is fully immersive.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/launching

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/live-viewing-apps.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Live-viewing apps

Best practices

Feature live content prominently and make it easy to access.

Let people tap once — or not at all — to start playback.

Make sure live content looks live.

Consider indicating the progress of currently playing live content.

Give people additional actions and viewing alternatives.

Consider using a content footer for browsing channels during playback.

• Give it a subtle treatment, such as a darkening, to keep text legible and help all items remain visually distinct from the content playing behind it.

• Make it easy for people to identify the thumbnail that represents the currently playing content by, for example, badging the thumbnail or tinting its progress bar.

• Match the categories in the content footer to those in your electronic program guide (for related guidance, see EPG experience).

• Design a simple, predictable way for people to invoke and dismiss the content footer — for example, if swiping up invokes the footer, people would expect swiping down to dismiss it.

Provide instant visual feedback when people change channels.

Match audio to the current context.

EPG experience

Prominently display current information and make it easy to return to playback.

Make browsing the EPG effortless.

Group content into familiar categories to help people find it more easily.

Let people browse the EPG without leaving their current content.

Cloud DVR

Let people start and stop recording from the info panel.

Let people record a future program in a view that provides details about the content.

Help people adapt the recording experience to their needs.

Allow playback and other content-specific actions within your cloud DVR area.

Consider offering a control that lets people manage cloud DVR settings.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/live-viewing-apps

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/loading.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Loading

Best practices

Show something as soon as possible.

Let people do other things in your app or game while they wait for content to load.

If loading takes an unavoidably long time, give people something interesting to view while they wait.

Improve installation and launch time by downloading large assets in the background.

Showing progress

Clearly communicate that content is loading and how long it might take to complete.

For games, consider creating a custom loading view.

Platform considerations

watchOS

As much as possible, avoid showing a loading indicator in your watchOS experience.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/loading

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/managing-accounts.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Managing accounts

Best practices

Explain the benefits of creating an account and how to sign up.

Delay sign-in for as long as possible.

If you don’t use Sign in with Apple in your iOS, iPadOS, macOS, or visionOS app, prefer using a passkey.

Always identify the authentication method you offer.

Refer only to authentication methods that are available in the current context.

In general, avoid offering an app-specific setting for opting in to biometric authentication.

Avoid using the term _passcode_ to refer to account authentication.

Deleting accounts

Provide a clear way to initiate account deletion within your app or game.

Provide a consistent account-deletion experience whether people perform it within your app or game or on the website.

Consider letting people schedule account deletion to occur in the future.

Tell people when account deletion will complete, and notify them when it’s finished.

If you support in-app purchases, help people understand how billing and cancellation work when they delete their account.

• Billing for an auto-renewable subscription continues through Apple until people cancel the subscription, regardless of whether they delete their account.

• After they delete their account, people need to cancel their subscription or request a refund.

TV provider accounts

Avoid displaying a sign-out option when people are signed in at the system level.

Never instruct people to sign out by adjusting privacy controls.

Platform considerations

tvOS

Prefer letting people use another device to sign up or authenticate.

When people are signed in to a shared account, avoid asking them to choose their profile every time they become the current user.

Minimize data entry.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/managing-accounts

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/managing-notifications.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Managing notifications

Integrating with Focus

• A Focus helps people filter notifications during a time period they reserve for an activity like sleeping, working, reading, or driving.

• Delivery scheduling lets people choose whether to receive notification alerts immediately or in a summary that’s delivered at times they choose.

• _Passive_. Information people can view at their leisure, like a restaurant recommendation.

• _Active_ (the default). Information people might appreciate knowing about when it arrives, like a score update on their favorite sports team.

• _Time Sensitive_. Information that directly impacts the person and requires their immediate attention, like an account security issue or a package delivery.

• _Critical_. Urgent information about health and safety that directly impacts the person and demands their immediate attention. Critical notifications are extremely rare and typically come from governmental and public agencies or apps that help people manage their health or home.

Best practices

Build trust by accurately representing the urgency of each notification.

Use the Time Sensitive interruption level only for notifications that are relevant in the moment.

Sending marketing notifications

Never use the Time Sensitive interruption level to send a marketing notification.

Get people’s permission if you want to send them promotional or marketing notifications.

Make sure people can manage their notification settings within your app.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/managing-notifications

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/modality.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Modality

• Ensure that people receive critical information and, if necessary, act on it

• Provide options that let people confirm or modify their most recent action

• Help people perform a distinct, narrowly scoped task without losing track of their previous context

• Give people an immersive experience or help them concentrate on a complex task

Best practices

Present content modally only when there’s a clear benefit.

Aim to keep modal tasks simple, short, and streamlined.

Take care to avoid creating a modal experience that feels like an app within your app.

Consider using a full-screen modal style for in-depth content or a complex task.

Always give people an obvious way to dismiss a modal view.

When necessary, help people avoid data loss by getting confirmation before closing a modal view.

Make it easy to identify a modal view’s task.

Let people dismiss a modal view before presenting another one.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/modality

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/multitasking.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Multitasking

Best practices

Pause activities that require people’s attention or active participation when they switch away.

Respond smoothly to audio interruptions.

• Pause audio indefinitely for primary audio interruptions, such as playing music, podcasts, or audiobooks.

• Temporarily lower the volume or pause the audio for shorter interruptions, such as GPS directional notifications, and resume the original volume or playback when the interruption ends.

Finish user-initiated tasks in the background.

Use notifications sparingly.

Platform considerations

visionOS

Avoid interfering with the system-provided multitasking behavior.

Don’t pause a window’s video playback when people look away from it.

Be prepared for situations where your audio can duck.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/multitasking

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/offering-help.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Offering help

Best practices

Let your app’s tasks inform the types of help people might need.

Use relevant and consistent language and images in your help content.

Make sure all help content is inclusive.

Avoid bloating your help content by explaining how standard components or patterns work.

Creating tips

Use the most appropriate tip type for your app’s user interface.

Use tips for simple features.

Make tips short, actionable, and engaging.

Define rules to help ensure your tips reach the intended audience.

If there’s an image or symbol that people associate with the feature, consider including it in the tip, and prefer the filled variant.

Use buttons to direct people to information or options.

Platform considerations

macOS, visionOS

Describe only the control that people indicate interest in.

Explain the action or task the control initiates.

In general, avoid repeating a control’s name in its tooltip.

Be brief.

Use sentence case.

Consider offering context-sensitive tooltips.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/offering-help

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/onboarding.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Onboarding

Best practices

Teach through interactivity.

Consider providing a collection of context-specific tips instead of a single onboarding flow.

If you need to present a prerequisite onboarding flow, design a brief, enjoyable experience that doesn’t require people to memorize a lot of information.

If it makes sense to offer a separate tutorial, consider making it optional.

Keep onboarding content focused on the experience you provide.

Additional content

Briefly display a splash screen if necessary.

Don’t let large downloads hinder onboarding.

Avoid displaying licensing details within your onboarding flow.

Additional requests

Postpone nonessential setup flows or customization steps.

If your app or game needs access to private data or resources before it can function, consider integrating the permission request into your onboarding flow.

Prefer letting people experience your app or game before prompting them for ratings or purchases.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/onboarding

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/playing-audio.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Playing audio

Silence.

Volume.

Headphones.

Best practices

Adjust levels automatically when necessary — don’t adjust the overall volume.

Permit rerouting of audio when possible.

Use the system-provided volume view to let people make audio adjustments.

Choose an audio category that fits the way your app or game uses sound.

Respond to audio controls only when it makes sense.

Avoid repurposing audio controls.

Consider creating custom audio player controls only if you need to offer commands that the system doesn’t support.

Let other apps know when your app finishes playing temporary audio.

Handling interruptions

Determine how to respond to audio-session interruptions.

When an interruption ends, determine whether to resume audio playback automatically.

Platform considerations

iOS, iPadOS

Use the system’s sound services to play short sounds and vibrations.

visionOS

Prefer playing sound.

Design custom sounds for custom UI elements.

Use Spatial Audio to create an intuitive, engaging experience.

Consider defining a range of places from which your app sounds can originate.

Consider varying sounds that people could perceive as repetitive over time.

Decide whether you need to play sound that’s fixed to the wearer or tracked by the wearer.

watchOS

Use the recommended encoding values for media assets.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/playing-audio

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/playing-haptics.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Playing haptics

• In an iPadOS, macOS, tvOS, or visionOS app or game, game controllers can provide haptic feedback (for developer guidance, see Playing Haptics on Game Controllers).

• Apple Pencil Pro and some trackpads can provide haptic feedback when connected to certain iPad models. (For details on Apple Pencil features and compatibility, see Apple Pencil.)

Best practices

Use system-provided haptic patterns according to their documented meanings.

Use haptics consistently throughout your app or game.

Prefer using haptics to complement other feedback in your app or game.

Avoid overusing haptics.

In most apps, prefer playing short haptics that complement discrete events.

Make haptics optional.

Be aware that playing haptics might impact other user experiences.

Custom haptics

• _Transient_ events are brief and compact, often feeling like taps or impulses. The experience of tapping the Flashlight button on the Home Screen is an example of a transient event.

• _Continuous_ events feel like sustained vibrations, such as the experience of the lasers effect in a message.

Platform considerations

iOS

• Use standard UI components — like toggles, sliders, and pickers — that play Apple-designed system haptics by default.

• When it makes sense, use a feedback generator to play one of several predefined haptic patterns in the categories of notification, impact, and selection (for developer guidance, see `UIFeedbackGenerator`).

Notification

Success.

Warning.

Error.

Impact

Light.

Medium.

Heavy.

Rigid.

Soft.

Selection

Selection.

watchOS

• Notification
• Up
• Down
• Success
• Failure
• Retry
• Start
• Stop
• Click

Notification.

Up.

Down.

Success.

Failure.

Retry.

Start.

Stop.

Click.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/playing-haptics

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/playing-video.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Playing video

• In full-screen — or _aspect-fill_ — mode, the video scales to fill the display, and some edge cropping may occur. This mode is the default for wide video (2:1 through 2.40:1). For developer guidance, see `resizeAspectFill`.

• In fit-to-screen — or _aspect_ — mode, the entire video is visible onscreen, and letterboxing or pillarboxing occurs as needed. This mode is the default for standard video (4:3, 16:9, and anything up to 2:1) and ultrawide video (anything above 2.40:1). For developer guidance, see `resizeAspect`.

Best practices

Use the system video player to give people a familiar and convenient experience.

Always display video content at its original aspect ratio.

• Result of padding a 4:3 video
• Result of padding a 21:9 video

Provide additional information when it adds value.

Support the interactions people expect, regardless of the input device they’re using to control playback.

If people need to access playback options or content-specific information in your tvOS app, consider adding a transport control or a custom content tab.

Avoid allowing audio from different sources to mix as viewers switch between modes.

Integrating with the TV app

Ensure a smooth transition to your app.

Show the expected content immediately.

Avoid asking people if they want to resume playback.

Play or pause playback when people press Space on a connected Bluetooth keyboard.

Make sure content plays for the correct viewer.

Use the previous end time when resuming playback of a long video clip.

Loading content

Avoid displaying loading screens when possible.

Start playback immediately.

Minimize loading screen content.

Exiting playback

Show a contextually relevant screen.

Be prepared for an immediate exit.

Platform considerations

tvOS

Defer to content when displaying logos or noninteractive overlays above video.

Show interactive overlays gracefully.

visionOS

Help people stay comfortable when playing video in your app.

• Letting them choose when to start playing a video

• Using a small window for playback, letting people resize it if they want

• Making sure people can see their surroundings during playback

In a fully immersive experience, avoid letting virtual content obscure playback or transport controls.

Avoid automatically starting a fully immersive video playback experience.

Create a thumbnail track if you want to support scrubbing.

Avoid expanding an inline video player to fill a window.

Use a RealityKit video player if you need to play video in a view like a splash screen or a transitional view.

watchOS

Keep video clips short.

Use the recommended sizes and encoding values for media assets.

Avoid creating a poster image that looks like a system control.

Consider creating a poster image that represents a video clip’s contents.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/playing-video

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/printing.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Printing

Best practices

Make printing discoverable.

Present a printing option only when it’s possible.

Present relevant printing options.

Platform considerations

macOS

If your macOS app offers app-specific print options that the system doesn’t offer, consider creating a custom category for the print panel.

If your app supports document-specific page settings, consider presenting a page setup dialog.

Make sure interdependencies between options are clear.

Separate advanced features from frequently used features.

Consider letting people preview the effect of a setting.

Consider storing modified settings with the document.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/printing

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Ratings and reviews

Best practices

Ask for a rating only after people have demonstrated engagement with your app or game.

Avoid interrupting people while they’re performing a task or playing a game.

Avoid pestering people.

Prefer the system-provided prompt.

Weigh the benefits of resetting your summary rating against the potential disadvantage of showing fewer ratings.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/ratings-and-reviews

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/searching.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Searching

Best practices

If search is important, consider making it a primary action.

Aim to make your app’s content searchable through a single location.

Use placeholder text to indicate what content is searchable.

Clearly display the current scope of a search.

Provide suggestions to make searching easier.

Take privacy into consideration before displaying search history.

Systemwide search

Make your app’s content searchable in Spotlight.

Define metadata for custom file types you handle.

Use Spotlight to offer advanced file-search capabilities within the context of your app.

Prefer using the system-provided open and save views.

Implement a Quick Look generator if your app produces custom file types.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/searching

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/settings.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Settings

Best practices

Aim to provide default settings that give the best experience to the largest number of people.

Minimize the number of settings you offer.

Make settings available in ways people expect.

Avoid using settings to ask for setup information you can get in other ways.

Respect people’s systemwide settings and avoid including redundant versions of them in your custom settings area.

General settings

Put general, infrequently changed settings in your custom settings area.

Task-specific options

When possible, prefer letting people modify task-specific options without going to your settings area.

System settings

Add only the most rarely changed options to the system-provided Settings app.

Platform considerations

macOS

Include a settings item in the[App menu](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar#App-menu).

Dim a settings window’s minimize and maximize buttons.

In your settings window, use a noncustomizable toolbar that remains visible and always indicates the active toolbar button.

Update the window’s title to reflect the currently visible pane.

Restore the most recently viewed pane.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/settings

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/undo-and-redo.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Undo and redo

Best practices

Help people predict the results of undo and redo as much as possible.

Show the results of an undo or redo.

Let people undo multiple times.

Consider giving people the option to revert multiple changes at once.

Provide undo and redo buttons only when necessary.

Platform considerations

iOS, iPadOS

Avoid redefining standard gestures for undo and redo.

Briefly and precisely describe the operation to be undone or redone.

macOS

Place undo and redo commands in the Edit menu and support the standard keyboard shortcuts.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/undo-and-redo

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/workouts.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Workouts

Best practices

In a watchOS fitness app, use workout sessions to provide useful data and relevant controls.

Avoid distracting people from a workout with information that’s not relevant.

Use a distinct visual appearance to indicate an active workout.

Provide workout controls that are easy to find and tap.

Help people understand the health information your app records if sensor data is unavailable during a workout.

Provide a summary at the end of a session.

Discard extremely brief workout sessions.

Make sure text is legible for when people are in motion.

Use Activity rings correctly.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/workouts